report-new

You are running the user's /report-new command.

Steps

1. Ask the user which run(s) the report covers. Accept either explicit run_ids or "the last run", "all of exp-X", "compare runs A and B".

   • For implicit selectors, call mcp__projtool__list_runs with the appropriate filters and confirm with the user before continuing.
   • If a run is is_dirty=true, mention it — the report frontmatter will get a provenance_warnings field.

2. Decide the report type and scope:

   • type: single, comparison, ablation, seed_sweep, milestone. If unsure, ask. Default for one run is single; for >1 run on the same branch, ask whether it's an ablation or comparison; for runs spanning multiple branches, the report is a cross-branch summary.
   • scope: branch (default — report belongs to one code-repo branch, filed under that branch's directory in the docs repo) or summary (cross-branch — filed under summary/).

3. Call mcp__projtool__start_report with experiment_id, run_ids, report_type, and scope. The tool:

   • Loads each run's manifest (via load_manifest).
   • Generates a report frontmatter prefilled with references and metrics_inlined skeletons, plus the cross-repo fields git.branch, git.commit, git.code_repo_url, git.commit_url.
   • Writes the file to the docs repo (NOT to the code repo!). The path is either <docs_repo>/<branch_full>/<date>-<topic_slug>.md (scope=branch) or <docs_repo>/summary/<date>-<topic_slug>.md (scope=summary), where <docs_repo> = <container_root>/docs/ (the independent docs git repo at the container root, alongside code/ and output/). The slug is initially "TBD"; pass a real slug to commit_report later.

4. Show the user the path to the new file. Open it (with view) so they can see the frontmatter and start drafting the body.

5. Reference handling:

   • When the body cites a number, also fill the corresponding field in metrics_inlined. If a number is in the body but missing from frontmatter, that's a violation — call it out.
   • If the run group is >8 runs, the tool will have generated a data/<sweep-name>.csv (alongside the report, in the same docs-repo subdirectory) instead of inlining the list; tell the user.

6. Do not commit yet. The report is a draft. Tell the user to use /report-commit (or mcp__projtool__commit_report) once they're done. commit_report will:

   • Validate that all cited code commits are pushed to the code repo's origin. If not, it errors with a clear instruction to git push first (cross-repo invariant).
   • git add the specific .md and (if externalized) CSV files, then commits and pushes to the docs repo's current branch (resolved via git symbolic-ref --short HEAD, never hardcoded as main) in the docs repo (NOT the code repo).