docs: implementation plan for narrative-driven report redesign

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

docs/superpowers/plans/2026-04-03-report-redesign.md

@@ -0,0 +1,723 @@
+# Report Redesign Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the status-dashboard PDF report with a narrative-driven report where EO indicators tell a connected story.
+
+**Architecture:** New `app/outputs/narrative.py` module generates cross-indicator narratives and per-indicator interpretations using template-based pattern matching. Existing `app/outputs/report.py` is rewritten to use the new 4-section structure (The Place, Situation Assessment, Indicator Deep Dives, Technical Annex). The `generate_pdf_report()` signature stays the same — no changes to the worker or indicator code.
+
+**Tech Stack:** Python, reportlab (existing), pytest
+
+**Spec:** `docs/superpowers/specs/2026-04-03-report-redesign-design.md`
+
+---
+
+### Task 1: Narrative Engine — Core Functions
+
+**Files:**
+- Create: `app/outputs/narrative.py`
+- Create: `tests/test_narrative.py`
+
+- [ ] **Step 1: Write failing tests for the narrative engine**
+
+Create `tests/test_narrative.py`:
+
+```python
+"""Tests for app.outputs.narrative — cross-indicator narrative generation."""
+from app.models import IndicatorResult, StatusLevel, TrendDirection, ConfidenceLevel
+
+
+def _make_result(
+    indicator_id: str,
+    status: StatusLevel = StatusLevel.GREEN,
+    trend: TrendDirection = TrendDirection.STABLE,
+    data_source: str = "satellite",
+    headline: str = "Test headline",
+    summary: str = "Test summary.",
+) -> IndicatorResult:
+    return IndicatorResult(
+        indicator_id=indicator_id,
+        headline=headline,
+        status=status,
+        trend=trend,
+        confidence=ConfidenceLevel.HIGH,
+        map_layer_path="",
+        chart_data={"dates": ["2025-06"], "values": [0.5]},
+        summary=summary,
+        methodology="Test methodology.",
+        limitations=["Test limitation."],
+        data_source=data_source,
+    )
+
+
+def test_generate_narrative_all_green():
+    from app.outputs.narrative import generate_narrative
+    results = [
+        _make_result("ndvi"),
+        _make_result("water"),
+    ]
+    narrative = generate_narrative(results)
+    assert "within normal ranges" in narrative.lower() or "stable" in narrative.lower()
+    assert len(narrative) > 20
+
+
+def test_generate_narrative_drought_pattern():
+    from app.outputs.narrative import generate_narrative
+    results = [
+        _make_result("ndvi", status=StatusLevel.RED, trend=TrendDirection.DETERIORATING),
+        _make_result("rainfall", status=StatusLevel.RED, trend=TrendDirection.DETERIORATING),
+    ]
+    narrative = generate_narrative(results)
+    assert "drought" in narrative.lower() or "precipitation" in narrative.lower()
+
+
+def test_generate_narrative_landuse_pattern():
+    from app.outputs.narrative import generate_narrative
+    results = [
+        _make_result("ndvi", status=StatusLevel.AMBER, trend=TrendDirection.DETERIORATING),
+        _make_result("buildup", status=StatusLevel.AMBER, trend=TrendDirection.DETERIORATING),
+    ]
+    narrative = generate_narrative(results)
+    assert "settlement" in narrative.lower() or "land-use" in narrative.lower()
+
+
+def test_generate_narrative_placeholder_caveat():
+    from app.outputs.narrative import generate_narrative
+    results = [
+        _make_result("ndvi", data_source="placeholder"),
+        _make_result("water"),
+    ]
+    narrative = generate_narrative(results)
+    assert "placeholder" in narrative.lower() or "estimated" in narrative.lower() or "limited" in narrative.lower()
+
+
+def test_generate_narrative_single_indicator():
+    from app.outputs.narrative import generate_narrative
+    results = [_make_result("ndvi", status=StatusLevel.AMBER, trend=TrendDirection.DETERIORATING)]
+    narrative = generate_narrative(results)
+    assert isinstance(narrative, str)
+    assert len(narrative) > 20
+
+
+def test_get_interpretation_returns_nonempty():
+    from app.outputs.narrative import get_interpretation
+    for ind_id in ["ndvi", "water", "sar", "buildup", "fires", "rainfall"]:
+        for status in [StatusLevel.GREEN, StatusLevel.AMBER, StatusLevel.RED]:
+            result = get_interpretation(ind_id, status)
+            assert isinstance(result, str)
+            assert len(result) > 10, f"Empty interpretation for {ind_id}/{status}"
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run: `pytest tests/test_narrative.py -v`
+Expected: FAIL with ModuleNotFoundError (narrative.py doesn't exist yet)
+
+- [ ] **Step 3: Implement the narrative engine**
+
+Create `app/outputs/narrative.py`:
+
+```python
+"""Cross-indicator narrative generation for Aperture reports."""
+from __future__ import annotations
+
+from typing import Sequence
+
+from app.models import IndicatorResult, StatusLevel, TrendDirection
+
+
+# --- Per-indicator interpretation templates ---
+_INTERPRETATIONS: dict[tuple[str, StatusLevel], str] = {
+    ("ndvi", StatusLevel.RED): "A decline of this magnitude typically indicates severe crop stress, overgrazing, or drought impact.",
+    ("ndvi", StatusLevel.AMBER): "Moderate vegetation decline may reflect seasonal stress or early-stage degradation.",
+    ("ndvi", StatusLevel.GREEN): "Vegetation cover is within the normal range for this area and season.",
+    ("water", StatusLevel.RED): "Significant water extent change beyond the baseline suggests major flooding or hydrological disruption.",
+    ("water", StatusLevel.AMBER): "Moderate water extent changes may indicate seasonal flooding or irrigation changes.",
+    ("water", StatusLevel.GREEN): "Water extent is within normal seasonal variation.",
+    ("sar", StatusLevel.RED): "Major SAR backscatter anomalies indicate significant ground surface changes \u2014 possible flooding, construction, or deforestation.",
+    ("sar", StatusLevel.AMBER): "Moderate SAR changes may reflect seasonal soil moisture variation or gradual land-use change.",
+    ("sar", StatusLevel.GREEN): "SAR backscatter is within the normal range, indicating stable ground conditions.",
+    ("buildup", StatusLevel.RED): "Rapid settlement expansion at this rate suggests significant population displacement or unplanned urban growth.",
+    ("buildup", StatusLevel.AMBER): "Moderate settlement growth detected, consistent with gradual urbanization.",
+    ("buildup", StatusLevel.GREEN): "Settlement extent is stable relative to the baseline period.",
+    ("fires", StatusLevel.RED): "Active fire density at critical levels \u2014 indicates widespread burning requiring immediate attention.",
+    ("fires", StatusLevel.AMBER): "Elevated fire activity detected, likely agricultural burning or localized wildfire.",
+    ("fires", StatusLevel.GREEN): "Fire activity is within normal seasonal patterns.",
+    ("rainfall", StatusLevel.RED): "Severe precipitation deficit against the long-term average is consistent with drought conditions.",
+    ("rainfall", StatusLevel.AMBER): "Below-average precipitation may lead to crop stress if the deficit persists.",
+    ("rainfall", StatusLevel.GREEN): "Precipitation is within normal ranges for the season.",
+    ("lst", StatusLevel.RED): "Surface temperatures are critically elevated, indicating severe thermal stress.",
+    ("lst", StatusLevel.AMBER): "Moderately elevated surface temperatures may affect crop health and water availability.",
+    ("lst", StatusLevel.GREEN): "Surface temperatures are within the normal seasonal range.",
+    ("nightlights", StatusLevel.RED): "Significant nighttime light changes indicate major disruption to infrastructure or population activity.",
+    ("nightlights", StatusLevel.AMBER): "Moderate nighttime light changes may reflect economic shifts or partial service disruption.",
+    ("nightlights", StatusLevel.GREEN): "Nighttime light patterns are stable, suggesting no major disruption.",
+}
+
+# --- Cross-indicator pattern rules ---
+# Each rule: (required indicator statuses, narrative sentence)
+_CROSS_PATTERNS: list[tuple[dict[str, set[StatusLevel]], str]] = [
+    (
+        {"ndvi": {StatusLevel.RED, StatusLevel.AMBER}, "rainfall": {StatusLevel.RED, StatusLevel.AMBER}},
+        "Vegetation decline is consistent with reduced precipitation, suggesting drought-driven stress.",
+    ),
+    (
+        {"ndvi": {StatusLevel.RED, StatusLevel.AMBER}, "buildup": {StatusLevel.RED, StatusLevel.AMBER}},
+        "Vegetation loss coincides with settlement expansion, indicating possible land-use conversion.",
+    ),
+    (
+        {"ndvi": {StatusLevel.RED, StatusLevel.AMBER}, "sar": {StatusLevel.RED, StatusLevel.AMBER}},
+        "Vegetation decline paired with SAR backscatter anomalies may indicate flood damage or soil saturation.",
+    ),
+    (
+        {"water": {StatusLevel.RED, StatusLevel.AMBER}, "sar": {StatusLevel.RED, StatusLevel.AMBER}},
+        "Increased water extent and SAR signal changes suggest flooding or waterlogging.",
+    ),
+    (
+        {"fires": {StatusLevel.RED, StatusLevel.AMBER}, "ndvi": {StatusLevel.RED, StatusLevel.AMBER}},
+        "Active fire detections combined with vegetation decline indicate burning-driven land cover change.",
+    ),
+]
+
+_LEAD_TEMPLATES = {
+    StatusLevel.RED: "The situation shows critical concern across one or more indicators.",
+    StatusLevel.AMBER: "The situation shows elevated concern requiring monitoring.",
+    StatusLevel.GREEN: "All indicators are within normal ranges for this area and period.",
+}
+
+
+def get_interpretation(indicator_id: str, status: StatusLevel) -> str:
+    """Return a 1-2 sentence interpretation for the given indicator and status."""
+    return _INTERPRETATIONS.get(
+        (indicator_id, status),
+        f"{indicator_id.replace('_', ' ').title()} status is {status.value}.",
+    )
+
+
+def generate_narrative(results: Sequence[IndicatorResult]) -> str:
+    """Generate a cross-indicator narrative paragraph from indicator results."""
+    if not results:
+        return "No indicator data available for narrative generation."
+
+    parts: list[str] = []
+
+    # 1. Lead sentence — worst status drives framing
+    worst = max(
+        (r.status for r in results),
+        key=lambda s: [StatusLevel.GREEN, StatusLevel.AMBER, StatusLevel.RED].index(s),
+    )
+    parts.append(_LEAD_TEMPLATES[worst])
+
+    # 2. Per-indicator sentences — key metric from headline
+    for r in results:
+        parts.append(f"{r.headline}.")
+
+    # 3. Cross-indicator connection — first matching pattern
+    result_map = {r.indicator_id: r.status for r in results}
+    for required, sentence in _CROSS_PATTERNS:
+        if all(
+            ind_id in result_map and result_map[ind_id] in allowed_statuses
+            for ind_id, allowed_statuses in required.items()
+        ):
+            parts.append(sentence)
+            break
+
+    # 4. Placeholder caveat
+    placeholder_count = sum(1 for r in results if r.data_source == "placeholder")
+    if placeholder_count:
+        parts.append(
+            f"{placeholder_count} indicator(s) used estimated data "
+            "\u2014 cross-indicator interpretation is limited."
+        )
+
+    return " ".join(parts)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `pytest tests/test_narrative.py -v`
+Expected: All 6 tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/outputs/narrative.py tests/test_narrative.py
+git commit -m "feat: add cross-indicator narrative engine with interpretation templates"
+```
+
+---
+
+### Task 2: Rewrite PDF Report — The Place + Situation Assessment
+
+**Files:**
+- Modify: `app/outputs/report.py:226-556` (replace `generate_pdf_report` body)
+- Test: `tests/test_report.py`
+
+- [ ] **Step 1: Run existing report test to establish baseline**
+
+Run: `pytest tests/test_report.py -v`
+Expected: PASS
+
+- [ ] **Step 2: Rewrite `generate_pdf_report` with new structure**
+
+Replace the entire body of `generate_pdf_report` in `app/outputs/report.py` (lines 250-555) with the new structure. Keep the function signature, styles, and page template helpers (`_build_styles`, `_status_badge_table`, `_on_page`, `_indicator_label`) unchanged. Replace the `_indicator_block` function and the `story` construction inside `generate_pdf_report`.
+
+Replace the `_indicator_block` function (lines 163-223) with:
+
+```python
+def _indicator_block(result: IndicatorResult, styles: dict, map_path: str = "", chart_path: str = "") -> list:
+    """Build the flowables for a single indicator deep-dive section."""
+    from reportlab.platypus import Image
+    from app.outputs.narrative import get_interpretation
+
+    elements = []
+
+    # Badge + headline row
+    badge = _status_badge_table(result.status, styles)
+    headline = Paragraph(result.headline, styles["indicator_headline"])
+    row = Table(
+        [[badge, headline]],
+        colWidths=[2.2 * cm, None],
+        rowHeights=[None],
+    )
+    row.setStyle(TableStyle([
+        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+        ("LEFTPADDING", (1, 0), (1, 0), 8),
+        ("TOPPADDING", (0, 0), (-1, -1), 0),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 0),
+    ]))
+    elements.append(row)
+    elements.append(Spacer(1, 3 * mm))
+
+    # Placeholder data warning
+    if result.data_source == "placeholder":
+        elements.append(Paragraph(
+            '<font color="#CA5D0F"><b>\u26a0 Placeholder data</b> \u2014 real satellite data was '
+            'unavailable for this indicator. Results are illustrative only.</font>',
+            styles["body_muted"],
+        ))
+        elements.append(Spacer(1, 2 * mm))
+
+    # Map and chart — side by side if both exist, otherwise full width
+    has_map = map_path and os.path.exists(map_path)
+    has_chart = chart_path and os.path.exists(chart_path)
+    if has_map and has_chart:
+        map_img = Image(map_path, width=8 * cm, height=6 * cm)
+        chart_img = Image(chart_path, width=8 * cm, height=6 * cm)
+        img_row = Table([[map_img, chart_img]], colWidths=[8.5 * cm, 8.5 * cm])
+        img_row.setStyle(TableStyle([
+            ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+            ("ALIGN", (0, 0), (-1, -1), "CENTER"),
+        ]))
+        elements.append(img_row)
+    elif has_map:
+        img = Image(map_path, width=12 * cm, height=9 * cm)
+        img.hAlign = "CENTER"
+        elements.append(img)
+    elif has_chart:
+        img = Image(chart_path, width=12 * cm, height=6 * cm)
+        img.hAlign = "CENTER"
+        elements.append(img)
+    elements.append(Spacer(1, 3 * mm))
+
+    # "What the data shows"
+    elements.append(Paragraph("<b>What the data shows</b>", styles["body"]))
+    elements.append(Paragraph(result.summary, styles["body"]))
+    elements.append(Spacer(1, 2 * mm))
+
+    # "What this means"
+    interpretation = get_interpretation(result.indicator_id, result.status)
+    elements.append(Paragraph("<b>What this means</b>", styles["body"]))
+    elements.append(Paragraph(interpretation, styles["body"]))
+    elements.append(Spacer(1, 2 * mm))
+
+    # Data quality line
+    confidence_str = result.confidence.value.capitalize()
+    trend_str = result.trend.value.capitalize()
+    quality_line = (
+        f"Confidence: <b>{confidence_str}</b> &nbsp;|&nbsp; "
+        f"Trend: <b>{trend_str}</b> &nbsp;|&nbsp; "
+        f"Data source: <b>{result.data_source}</b>"
+    )
+    elements.append(Paragraph(quality_line, styles["body_muted"]))
+
+    elements.append(Spacer(1, 4 * mm))
+    elements.append(
+        HRFlowable(width="100%", thickness=0.5, color=colors.HexColor("#D8D5CF"))
+    )
+    elements.append(Spacer(1, 2 * mm))
+    return elements
+```
+
+Now replace the story construction inside `generate_pdf_report` (everything after `story = []` up to `doc.build(story)`):
+
+```python
+    story = []
+
+    from datetime import datetime as _dt, timezone as _tz
+    from app.outputs.narrative import generate_narrative
+
+    generated_at = _dt.now(_tz.utc).strftime("%Y-%m-%d %H:%M UTC")
+
+    # ------------------------------------------------------------------ #
+    #  Section 1: The Place                                               #
+    # ------------------------------------------------------------------ #
+    story.append(Paragraph("MERLx Aperture \u2014 Situation Report", styles["title"]))
+    story.append(Paragraph(aoi.name, styles["subtitle"]))
+    story.append(Spacer(1, 2 * mm))
+
+    # True-color overview map
+    if overview_map_path and os.path.exists(overview_map_path):
+        from reportlab.platypus import Image
+        img = Image(overview_map_path, width=14 * cm, height=10.5 * cm)
+        img.hAlign = "CENTER"
+        story.append(img)
+        story.append(Spacer(1, 3 * mm))
+
+    story.append(
+        Paragraph(
+            f"Analysis period: {time_range.start} \u2013 {time_range.end}",
+            styles["body_muted"],
+        )
+    )
+    story.append(
+        Paragraph(
+            f"Bounding box: {aoi.bbox[0]}\u00b0E, {aoi.bbox[1]}\u00b0N \u2013 "
+            f"{aoi.bbox[2]}\u00b0E, {aoi.bbox[3]}\u00b0N &nbsp;|&nbsp; "
+            f"Area: {aoi.area_km2:.1f} km\u00b2 &nbsp;|&nbsp; Generated: {generated_at}",
+            styles["body_muted"],
+        )
+    )
+
+    # Data sources summary
+    sources = set()
+    for r in results:
+        if "Sentinel-2" in r.methodology:
+            sources.add("Sentinel-2")
+        if "Sentinel-1" in r.methodology or "SAR" in r.methodology:
+            sources.add("Sentinel-1")
+        if "FIRMS" in r.methodology:
+            sources.add("NASA FIRMS")
+        if "CHIRPS" in r.methodology:
+            sources.add("CHIRPS")
+        if "Sentinel-3" in r.methodology or "SLSTR" in r.methodology:
+            sources.add("Sentinel-3")
+        if "VIIRS" in r.methodology:
+            sources.add("VIIRS")
+    if sources:
+        source_str = ", ".join(sorted(sources))
+        story.append(Paragraph(
+            f"Based on {len(results)} indicator(s) using {source_str}.",
+            styles["body_muted"],
+        ))
+
+    story.append(Spacer(1, 4 * mm))
+    story.append(HRFlowable(width="100%", thickness=1, color=INK_MUTED))
+    story.append(Spacer(1, 6 * mm))
+
+    # ------------------------------------------------------------------ #
+    #  Section 2: Situation Assessment                                    #
+    # ------------------------------------------------------------------ #
+    story.append(Paragraph("Situation Assessment", styles["section_heading"]))
+    story.append(Spacer(1, 2 * mm))
+
+    # Composite badge + headline
+    if overview_score:
+        composite_status_enum = {
+            "GREEN": StatusLevel.GREEN,
+            "AMBER": StatusLevel.AMBER,
+            "RED": StatusLevel.RED,
+        }.get(overview_score.get("status", "RED"), StatusLevel.RED)
+
+        badge = _status_badge_table(composite_status_enum, styles)
+        ov_headline = Paragraph(
+            overview_score.get("headline", ""),
+            styles["indicator_headline"],
+        )
+        row = Table([[badge, ov_headline]], colWidths=[2.2 * cm, None])
+        row.setStyle(TableStyle([
+            ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+            ("LEFTPADDING", (1, 0), (1, 0), 8),
+            ("TOPPADDING", (0, 0), (-1, -1), 0),
+            ("BOTTOMPADDING", (0, 0), (-1, -1), 0),
+        ]))
+        story.append(row)
+        story.append(Spacer(1, 4 * mm))
+
+    # Cross-indicator narrative
+    narrative = generate_narrative(results)
+    story.append(Paragraph(narrative, styles["body"]))
+    story.append(Spacer(1, 4 * mm))
+
+    # Compact summary table
+    summary_header = [
+        Paragraph("<b>Indicator</b>", styles["body"]),
+        Paragraph("<b>Status</b>", styles["body"]),
+        Paragraph("<b>Trend</b>", styles["body"]),
+        Paragraph("<b>Confidence</b>", styles["body"]),
+        Paragraph("<b>Headline</b>", styles["body"]),
+    ]
+    summary_rows = [summary_header]
+    for result in results:
+        label = _indicator_label(result.indicator_id)
+        status_cell = Paragraph(
+            f'<font color="white"><b>{STATUS_LABELS[result.status]}</b></font>',
+            ParagraphStyle(
+                "ov_badge",
+                fontName="Helvetica-Bold",
+                fontSize=7,
+                textColor=colors.white,
+                alignment=TA_CENTER,
+            ),
+        )
+        summary_rows.append([
+            Paragraph(label, styles["body_muted"]),
+            status_cell,
+            Paragraph(result.trend.value.capitalize(), styles["body_muted"]),
+            Paragraph(result.confidence.value.capitalize(), styles["body_muted"]),
+            Paragraph(result.headline[:80], styles["body_muted"]),
+        ])
+
+    ov_col_w = (PAGE_W - 2 * MARGIN)
+    ov_table = Table(
+        summary_rows,
+        colWidths=[ov_col_w * 0.15, ov_col_w * 0.10, ov_col_w * 0.12, ov_col_w * 0.13, ov_col_w * 0.50],
+    )
+    ov_ts = TableStyle([
+        ("BACKGROUND", (0, 0), (-1, 0), colors.HexColor("#E8E6E0")),
+        ("ROWBACKGROUNDS", (0, 1), (-1, -1), [colors.white, colors.HexColor(_SHELL_HEX)]),
+        ("GRID", (0, 0), (-1, -1), 0.3, colors.HexColor("#D8D5CF")),
+        ("TOPPADDING", (0, 0), (-1, -1), 3),
+        ("BOTTOMPADDING", (0, 0), (-1, -1), 3),
+        ("LEFTPADDING", (0, 0), (-1, -1), 4),
+        ("RIGHTPADDING", (0, 0), (-1, -1), 4),
+        ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+        ("ALIGN", (1, 1), (1, -1), "CENTER"),
+    ])
+    for row_idx, result in enumerate(results, start=1):
+        ov_ts.add("BACKGROUND", (1, row_idx), (1, row_idx), STATUS_COLORS[result.status])
+    ov_table.setStyle(ov_ts)
+    story.append(ov_table)
+
+    story.append(Spacer(1, 6 * mm))
+    story.append(HRFlowable(width="100%", thickness=0.5, color=colors.HexColor("#D8D5CF")))
+    story.append(Spacer(1, 4 * mm))
+
+    # ------------------------------------------------------------------ #
+    #  Section 3: Indicator Deep Dives                                    #
+    # ------------------------------------------------------------------ #
+    story.append(Paragraph("Indicator Detail", styles["section_heading"]))
+    story.append(Spacer(1, 2 * mm))
+
+    # Build chart path lookup from results_dir (same directory as output_path)
+    results_dir = os.path.dirname(output_path)
+    for result in results:
+        indicator_label = _indicator_label(result.indicator_id)
+        map_path = (indicator_map_paths or {}).get(result.indicator_id, "")
+        chart_path = os.path.join(results_dir, f"{result.indicator_id}_chart.png")
+        if not os.path.exists(chart_path):
+            chart_path = ""
+        block = [Paragraph(indicator_label, styles["section_heading"])]
+        block += _indicator_block(result, styles, map_path=map_path, chart_path=chart_path)
+        story.append(KeepTogether(block))
+
+    # ------------------------------------------------------------------ #
+    #  Section 4: Technical Annex                                        #
+    # ------------------------------------------------------------------ #
+    story.append(Paragraph("Technical Annex", styles["section_heading"]))
+    story.append(Spacer(1, 2 * mm))
+
+    # Methodology per indicator
+    story.append(Paragraph("<b>Methodology</b>", styles["body"]))
+    for result in results:
+        indicator_label = _indicator_label(result.indicator_id)
+        story.append(
+            Paragraph(
+                f"<b>{indicator_label}:</b> {result.methodology}",
+                styles["body"],
+            )
+        )
+    story.append(Spacer(1, 4 * mm))
+
+    # Limitations
+    all_limitations = []
+    for result in results:
+        for lim in result.limitations:
+            if lim not in all_limitations:
+                all_limitations.append(lim)
+    if all_limitations:
+        story.append(Paragraph("<b>Limitations</b>", styles["body"]))
+        for lim in all_limitations:
+            story.append(Paragraph(f"\u2022 {lim}", styles["limitation"]))
+    story.append(Spacer(1, 4 * mm))
+
+    # Disclaimer
+    story.append(HRFlowable(width="100%", thickness=0.5, color=colors.HexColor("#D8D5CF")))
+    story.append(Spacer(1, 3 * mm))
+    disclaimer = (
+        "This report has been generated automatically by MERLx Aperture using satellite "
+        "remote sensing data. Results are intended to support humanitarian situation analysis "
+        "and should be interpreted alongside ground-truth information and expert judgement. "
+        "MERLx Aperture makes no warranty as to the accuracy or completeness of the data presented."
+    )
+    story.append(Paragraph("Disclaimer", styles["section_heading"]))
+    story.append(Paragraph(disclaimer, styles["body_muted"]))
+
+    # ------------------------------------------------------------------ #
+    #  Build PDF                                                          #
+    # ------------------------------------------------------------------ #
+    doc.build(story)
+```
+
+- [ ] **Step 3: Update `_indicator_block` signature**
+
+The `_indicator_block` function now accepts an optional `chart_path` parameter. Update the function signature and body as shown in Step 2. Remove the old version entirely.
+
+- [ ] **Step 4: Run report test**
+
+Run: `pytest tests/test_report.py -v`
+Expected: PASS (generates PDF > 5000 bytes with new structure)
+
+- [ ] **Step 5: Run full test suite**
+
+Run: `pytest --tb=short -q`
+Expected: All tests pass
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add app/outputs/report.py
+git commit -m "feat: rewrite PDF report with narrative structure (The Place, Assessment, Deep Dives, Annex)"
+```
+
+---
+
+### Task 3: Update Report Test for New Content
+
+**Files:**
+- Modify: `tests/test_report.py`
+
+- [ ] **Step 1: Update test to verify new structure and removed sections**
+
+Replace `tests/test_report.py` with:
+
+```python
+import pytest
+import tempfile
+import os
+from datetime import date
+from app.outputs.report import generate_pdf_report
+from app.models import AOI, TimeRange, IndicatorResult, StatusLevel, TrendDirection, ConfidenceLevel
+
+
+def _make_result(indicator_id, status=StatusLevel.AMBER, headline="Test headline"):
+    return IndicatorResult(
+        indicator_id=indicator_id,
+        headline=headline,
+        status=status,
+        trend=TrendDirection.DETERIORATING,
+        confidence=ConfidenceLevel.HIGH,
+        map_layer_path="",
+        chart_data={"dates": ["2025-06"], "values": [1]},
+        summary="Test summary of data.",
+        methodology="Sentinel-2 NDVI at 100m resolution.",
+        limitations=["Cloud cover."],
+    )
+
+
+def test_generate_pdf_report():
+    aoi = AOI(name="Khartoum North", bbox=[32.45, 15.65, 32.65, 15.80])
+    time_range = TimeRange(start=date(2025, 3, 1), end=date(2026, 3, 1))
+    results = [
+        _make_result("fires", headline="3 fire events detected"),
+        _make_result("ndvi", status=StatusLevel.RED, headline="34% decline vs. baseline"),
+    ]
+    with tempfile.TemporaryDirectory() as tmpdir:
+        out_path = os.path.join(tmpdir, "report.pdf")
+        generate_pdf_report(aoi=aoi, time_range=time_range, results=results, output_path=out_path)
+        assert os.path.exists(out_path)
+        assert os.path.getsize(out_path) > 5000
+
+
+def test_generate_pdf_report_single_indicator():
+    aoi = AOI(name="Test Area", bbox=[32.0, 15.0, 33.0, 16.0])
+    time_range = TimeRange(start=date(2025, 1, 1), end=date(2025, 12, 31))
+    results = [_make_result("ndvi")]
+    with tempfile.TemporaryDirectory() as tmpdir:
+        out_path = os.path.join(tmpdir, "report.pdf")
+        generate_pdf_report(aoi=aoi, time_range=time_range, results=results, output_path=out_path)
+        assert os.path.exists(out_path)
+        assert os.path.getsize(out_path) > 3000
+
+
+def test_generate_pdf_report_with_overview_score():
+    aoi = AOI(name="Test Area", bbox=[32.0, 15.0, 33.0, 16.0])
+    time_range = TimeRange(start=date(2025, 1, 1), end=date(2025, 12, 31))
+    results = [
+        _make_result("ndvi", status=StatusLevel.RED),
+        _make_result("water", status=StatusLevel.GREEN),
+    ]
+    overview_score = {
+        "score": 45,
+        "status": "AMBER",
+        "headline": "Area conditions: AMBER (score 45/100)",
+    }
+    with tempfile.TemporaryDirectory() as tmpdir:
+        out_path = os.path.join(tmpdir, "report.pdf")
+        generate_pdf_report(
+            aoi=aoi, time_range=time_range, results=results,
+            output_path=out_path, overview_score=overview_score,
+        )
+        assert os.path.exists(out_path)
+        assert os.path.getsize(out_path) > 5000
+
+
+def test_generate_pdf_report_with_placeholder():
+    aoi = AOI(name="Test Area", bbox=[32.0, 15.0, 33.0, 16.0])
+    time_range = TimeRange(start=date(2025, 1, 1), end=date(2025, 12, 31))
+    results = [_make_result("ndvi")]
+    results[0].data_source = "placeholder"
+    with tempfile.TemporaryDirectory() as tmpdir:
+        out_path = os.path.join(tmpdir, "report.pdf")
+        generate_pdf_report(aoi=aoi, time_range=time_range, results=results, output_path=out_path)
+        assert os.path.exists(out_path)
+        assert os.path.getsize(out_path) > 3000
+```
+
+- [ ] **Step 2: Run updated tests**
+
+Run: `pytest tests/test_report.py -v`
+Expected: All 4 tests PASS
+
+- [ ] **Step 3: Run full test suite**
+
+Run: `pytest --tb=short -q`
+Expected: All tests pass
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add tests/test_report.py
+git commit -m "test: update report tests for new narrative structure"
+```
+
+---
+
+### Task 4: Verify Full Integration
+
+**Files:** None (verification only)
+
+- [ ] **Step 1: Run full test suite**
+
+Run: `pytest --tb=short -q`
+Expected: All tests pass.
+
+- [ ] **Step 2: Spot-check narrative module**
+
+Run: `python -c "from app.outputs.narrative import generate_narrative, get_interpretation; from app.models import StatusLevel; print(get_interpretation('ndvi', StatusLevel.RED)); print('OK')"`
+Expected: Prints interpretation text and "OK".
+
+- [ ] **Step 3: Spot-check report imports**
+
+Run: `python -c "from app.outputs.report import generate_pdf_report; print('OK')"`
+Expected: Prints "OK" with no import errors.