hotspot-weekly

Step 1: Run the weekly pipeline (stops at narrate-prepare)

Run: hotspot weekly --json

Parse the JSON output. Check phases_run:

• If phases_run contains "render", the report for this week already exists — display the contents of file_path and stop.
• If phases_run contains "narrate-prepare" but NOT "narrate-finalize":
  • snapshot_id = value from JSON
  • report_id = value from JSON
  • Continue to Step 2.

Do NOT rely on file_path being non-null to detect completion — file_path is null until the render phase runs.

Step 2: Get the narration request path

Run: hotspot narrate-prepare --snapshot {snapshot_id} --report-id {report_id} --json

Both --snapshot and --report-id are required (no defaults exist).

Parse the JSON output:

• request_path = the path to narration_request.json
• response_path = {parent directory of request_path}/narration_response.json

Step 3: Read the narration request and write the narrative

Read the file at request_path.

It contains:

{
  "snapshot_id": N,
  "hotspots": [
    {
      "cluster_id": C,
      "domain": "ai",
      "allowed_paper_ids": [1, 2, 3, ...],
      "context_block": {
        "top_papers": [...]
      }
    }
  ]
}

For each hotspot in the list, write a HotspotNarrative JSON object with these exact fields:

• summary: 2-3 sentence overview of what this research cluster is about and why it matters
• why_hot: list of {"text": "...[paper_id=N]...", "paper_ids": [N]} objects — each claim grounded in specific papers using [paper_id=N] syntax
• representative_papers: list of paper_ids that best represent the hotspot
• potential_disagreements: null, or a list of {"text": "...[paper_id=N]...", "paper_ids": [N]} objects showing competing viewpoints

CRITICAL: cite ONLY paper_ids from that hotspot's allowed_paper_ids list. Use [paper_id=N] syntax for every claim. Do not invent or hallucinate paper_ids.

Write the complete response as JSON to response_path:

{
  "snapshot_id": N,
  "narratives": [
    {
      "cluster_id": C,
      "narrative": {
        "summary": "...",
        "why_hot": [{"text": "...[paper_id=1]...", "paper_ids": [1]}],
        "representative_papers": [1, 2],
        "potential_disagreements": null
      }
    }
  ]
}

Step 4: Validate and finalize (up to 2 rounds, N=2 cap)

Round 1:

Run: hotspot narrate-finalize --request {request_path} --response {response_path} --snapshot {snapshot_id} --report-id {report_id} --json

Parse the JSON output:

• If needs_correction: false → proceed to Step 5.
• If needs_correction: true:
  • Read the file at correction_path (present in the JSON when needs_correction is true).
  • It shows which paper_ids were invalid for which hotspots.
  • Re-narrate only the flagged hotspot(s), using ONLY allowed_paper_ids from the original request.
  • Update response_path with the corrected narratives for the flagged clusters (preserve passing narratives unchanged).

Note: needs_correction: true exits with code 0 — this is an expected state, not a crash.

Round 2 (MUST use --is-retry):

Run: hotspot narrate-finalize --request {request_path} --response {response_path} --snapshot {snapshot_id} --report-id {report_id} --json --is-retry

• If needs_correction: false → proceed to Step 5.
• If still needs_correction: true after round 2 → state plainly to the user that a placeholder narrative was used for the affected hotspot(s) due to persistent grounding failures, then proceed to Step 5.

Hard cap: N=2 rounds maximum. Never loop further. Never hang. Never silently trust a bad narrative.

Step 5: Render the report

Run: hotspot weekly --resume --snapshot-existing {snapshot_id} --json

Parse the JSON output and display the full report from file_path. The report is also saved to reports/YYYY-WW.md.