generate-report - SKILL.md Agent Skill

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, mcpcodexcodex, mcpcodexcodex-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:

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].
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".
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".
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:

One-paragraph paper summary + one-sentence contribution (this is what paper-plan uses to frame the abstract and hero figure).
Problem & motivation — quantified scale, drawn from LIT_REVIEW_REPORT and FINAL_PROPOSAL.
Gap analysis — explicit gaps closed by this work, with boundary citations from LIT_REVIEW_REPORT.
Contributions — numbered, each tied to a specific experiment / claim / figure.
Method — enough detail for paper-draft to write Methods without re-reading FINAL_PROPOSAL: datasets, study area, preprocessing, model, hyperparameters, evaluation protocol.
Experiments & results — per-experiment: hypothesis, setup, headline numbers, tables/figures produced, pass/fail vs. success criteria from EXPERIMENT_PLAN.
Claims–evidence matrix — table: claim | evidence source | quantitative support | figure/table id.
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).
Related work synthesis — themes and key papers already verified in LIT_REVIEW_REPORT; group them the way the paper will cite them.
Limitations & threats to validity — concrete, not generic; include anything from AUTO_REVIEW._REPORT.md not yet fixed.
Reviewer-raised issues and their resolution status — mirror of AUTO_REVIEW._REPORT.md with status column (addressed / deferred / rejected — rationale).
Future work — 3–5 specific directions derived from limitations and deferred experiments.
Venue target & page budget — from program.md / research_contract.md.
Citation seed list — already-verified keys from LIT_REVIEW_REPORT the paper-draft bib will draw from. Do NOT invent BibTeX here.
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.