edit-docs

Edit MadGraph Documentation

Guided workflow for editing the MadGraph documentation with parallel review and revision.

Task

$ARGUMENTS

If no task was given, ask the user what they want to change.

Workspace Setup

If a draft already exists from a previous edit, skip setup — reuse it.

Otherwise, call the get_doc_draft MCP tool to create a writable copy:

get_doc_draft("/workspace/docs_draft")

Workflow

Round 1: Edit

Invoke the doc-editor agent with the task. It edits the draft files at /workspace/docs_draft.

After it finishes, generate a diff using the MCP tool (this correctly handles the overview file which lives outside /madgraph_docs/):

get_doc_diff("/workspace/docs_draft")

Save the diff output to /workspace/docs_changes.diff.

Round 1: Parallel Review

Invoke ALL THREE reviews simultaneously — do not run them sequentially:

1. doc-style-reviewer agent — review the changed files for style and formatting

2. doc-quality-reviewer agent — review the changed files for structure, placement, duplication

3. verifier agent — extract and verify factual claims from the changed content. Dispatch with:

   Extract and verify all factual claims from the documentation changes.

   • Diff of changes: /workspace/docs_changes.diff
   • Updated docs: /workspace/docs_draft/

   Read the diff to understand what was changed, then read the relevant files for full context. Only extract claims from new or changed content — do not extract claims from unchanged parts of the documentation.

   Doc-specific extraction rules:

   • Extract both factual claims AND executable code blocks.
   • Any fenced code block tagged as mg5, madgraph, mg5_amc, bash, or python that involves MadGraph commands must be extracted. For each, include the source file and section for context, what the code block accomplishes, and the full code block content.

   Doc-specific verification rules:

   • MG5 code blocks must be executed to confirm they run without errors.
   • Default values must be verified by reading source code (e.g., banner.py, template card files) — not by trusting existing documentation.
   • Check that claims do not contradict each other within the document.
   • Do NOT verify: general physics concepts, high-level descriptions, cross-references, formatting, or style choices.
   • If you discover pre-existing errors in the existing documentation (under /madgraph_docs/) while verifying, report them separately as incidental errors.

   Write verdicts to /workspace/verify/verdicts.json.