/generate-report

name: generate-report
description: Consolidates literature review, idea discovery, refined proposal, experiment plan, experiment results, and automated review into a single NARRATIVE_REPORT.md that is rich enough to drive the downstream paper-writing-pipeline (paper-plan → paper-figure-generate → paper-draft → paper-review-loop → paper-convert).
argument-hint: [optional-focus-or-output-path]
allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, Agent, WebSearch, WebFetch, mcp__codex__codex, mcp__codex__codex-reply

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`).
• [ ] Ever