Skill: generate-report

You build output/NARRATIVE_REPORT.md — the single source-of-truth narrative that the downstream paper-writing-pipeline reads in its first phase. The report must contain every claim, number, figure spec, citation hook, and limitation the paper-plan / paper-draft skills need so they do not have to re-derive context from scattered logs.

Focus / override: $ARGUMENTS

---

Constants

• REVIEWER_MODEL = gpt-5.4 — Optional Codex MCP review pass over the final narrative.
• TARGET_VENUE — Read from program.md Section 2 or research_contract.md. Default IJGIS.
• OUTPUT_PATH = output/NARRATIVE_REPORT.md
• TEMPLATE = skills/generate-report/templates/NARRATIVE_REPORT_TEMPLATE.md

---

Phase 1: Gather Inputs

Read all of the following. Any missing file is a soft failure — record it under "Missing Inputs" in the narrative and continue.

Primary inputs (MUST read):

• output/LIT_REVIEW_REPORT.md — themes, gap analysis, key citations
• output/IDEA_REPORT.md — ranked idea candidates, pilot scores, chosen idea rationale
• output/refine-logs/FINAL_PROPOSAL.md — refined research proposal (problem / method / contributions)
• output/refine-logs/EXPERIMENT_PLAN.md — experiment design, run order, success criteria
• output/EXPERIMENT_RESULT.md — actual quantitative results
• output/AUTO_REVIEW._REPORT.md — adversarial review feedback and required fixes

Supporting inputs (read if referenced or needed for gap-filling):

• research_contract.md, program.md — active idea, venue, success criteria
• memory/APPROVED_CLAIMS.md — verified claims only
• output/PROJ_NOTES.md — compact discovery log
• output/EXPERIMENT_LOG.md — full experiment record
• data/DATA_MANIFEST.md — dataset provenance
• output/spatial-analysis/ — spatial diagnostics and maps
• output/figures/ — any already-generated plots or JSONs

If context remains under budget, scan the entire night_owl_research_agent/ project for anything that materially changes the story (e.g., new figures, last-minute claims, deprecated methods). Err on the side of reading more context — the downstream pipeline cannot.

---

Phase 2: Reconcile Evidence

Before writing, resolve conflicts between sources:

1. Claim vs. result: Every claim must trace to a row in memory/APPROVED_CLAIMS.md or a specific number in output/EXPERIMENT_RESULT.md. Flag unsupported claims as [NEEDS_EVIDENCE].
2. Proposal vs. executed plan: If FINAL_PROPOSAL.md proposed an experiment that was not actually run per EXPERIMENT_RESULT.md, record it under "Deferred / Not Executed".
3. Review fixes applied?: Cross-check AUTO_REVIEW._REPORT.md CRITICAL/MAJOR items against EXPERIMENT_RESULT.md and method descriptions. Items not yet addressed go into "Outstanding Review Issues".
4. Numbers must be exact: Quote metrics verbatim (e.g., R² = 0.78, Moran's I = 0.12 (p < 0.01)). Never round or paraphrase.

---

Phase 3: Write NARRATIVE_REPORT.md

Follow skills/generate-report/templates/NARRATIVE_REPORT_TEMPLATE.md. Fill every section — do not ship a template with empty placeholders. If a section genuinely does not apply, write "N/A — reason".

Required content, at minimum:

1. One-paragraph paper summary + one-sentence contribution (this is what paper-plan uses to frame the abstract and hero figure).
2. Problem & motivation — quantified scale, drawn from LIT_REVIEW_REPORT and FINAL_PROPOSAL.
3. Gap analysis — explicit gaps closed by this work, with boundary citations from LIT_REVIEW_REPORT.
4. Contributions — numbered, each tied to a specific experiment / claim / figure.
5. Method — enough detail for paper-draft to write Methods without re-reading FINAL_PROPOSAL: datasets, study area, preprocessing, model, hyperparameters, evaluation protocol.
6. Experiments & results — per-experiment: hypothesis, setup, headline numbers, tables/figures produced, pass/fail vs. success criteria from EXPERIMENT_PLAN.
7. Claims–evidence matrix — table: claim | evidence source | quantitative support | figure/table id.
8. Figure & table plan — for each: id, type (hero / architecture / map / plot / table), caption draft, data source path, priority. The hero figure needs extra detail (what it compares, visual expectation, why a skim reader gets it).
9. Related work synthesis — themes and key papers already verified in LIT_REVIEW_REPORT; group them the way the paper will cite them.
10. Limitations & threats to validity — concrete, not generic; include anything from AUTO_REVIEW._REPORT.md not yet fixed.
11. Reviewer-raised issues and their resolution status — mirror of AUTO_REVIEW._REPORT.md with status column (addressed / deferred / rejected — rationale).
12. Future work — 3–5 specific directions derived from limitations and deferred experiments.
13. Venue target & page budget — from program.md / research_contract.md.
14. Citation seed list — already-verified keys from LIT_REVIEW_REPORT the paper-draft bib will draw from. Do NOT invent BibTeX here.
15. Appendix: file-level provenance — path + one-line summary of every input file consumed, plus a "Missing Inputs" subsection.

---

Phase 4: Self-Check

Before saving, verify:

• Every numbered contribution maps to ≥1 row in the claims–evidence matrix.
• Every claim in the matrix has a file path + line-level reference (e.g., EXPERIMENT_RESULT.md §3.2).
• Every figure in the figure plan has a concrete data source or is flagged as manual.
• Every CRITICAL/MAJOR item from AUTO_REVIEW._REPORT.md appears in Section 11 with a status.
• No claim exceeds what APPROVED_CLAIMS.md supports (no fabrication).
• Venue and page budget are consistent with program.md.
• Hero figure description is detailed enough that paper-figure-generate can draft it.

If any check fails, fix the narrative before writing.

---

Phase 5: Optional Cross-Review

If REVIEWER_MODEL is reachable via Codex MCP, send the final narrative for a pass:

mcp__codex__codex:
  model: gpt-5.4
  config: {"model_reasoning_effort": "xhigh"}
  prompt: |
    This NARRATIVE_REPORT.md will be the sole input to a paper-writing pipeline.
    Score 1–10 on: (1) story clarity, (2) claim–evidence coverage, (3) figure plan
    completeness, (4) gap articulation, (5) venue fit. For each weakness, give the
    MINIMUM edit required. Be specific and actionable.

    [paste full narrative]

If external LLM is not configured, spawn a subagent review instead. Apply feedback, then save.

---

Phase 6: Output

Write the final narrative to output/NARRATIVE_REPORT.md. Append a one-line entry to output/PROJ_NOTES.md:

[YYYY-MM-DD] generate-report: NARRATIVE_REPORT.md built from LIT_REVIEW / IDEA_REPORT / FINAL_PROPOSAL / EXPERIMENT_PLAN / EXPERIMENT_RESULT / AUTO_REVIEW._REPORT — [N] claims, [M] figures, venue=[VENUE]

Report back to the user:

📝 NARRATIVE_REPORT.md generated:
- Contributions: [N]
- Claims–evidence rows: [M]
- Figures planned: [auto: X, manual: Y, hero: 1]
- Outstanding review issues: [K]
- Missing inputs: [list or "none"]

Ready to invoke /paper-writing-pipeline "output/NARRATIVE_REPORT.md".

---

Key Rules

• Large file handling: If Write fails due to size, fall back to Bash heredoc writes in chunks. Do not ask the user.
• Never fabricate claims, numbers, or citations. If an input is missing, flag it; do not guess.
• Quote numbers verbatim from EXPERIMENT_RESULT.md and APPROVED_CLAIMS.md.
• Preserve provenance. Every non-trivial statement in the narrative should point to an input file.
• The narrative is a contract with the next pipeline — paper-plan, paper-figure-generate, and paper-draft will not re-read the scattered logs. If it is not in NARRATIVE_REPORT.md, it will not appear in the paper.
• Do NOT generate author info, BibTeX entries, or LaTeX — those belong to the downstream skills.
• Respect Prohibited Behaviors in CLAUDE.md — especially the ban on fabricated results and skipping result-to-claim.