docs-plan

name	docs-plan
description	Turn a shaped spec/{slug}/GOAL.md into a design and a phased roadmap. Runs an invariant gate against AGENTS.md, fans out read-only research subagents (scaled to appetite; existing-site-first), synthesizes spec/{slug}/PLAN.md, re-checks invariants, and generates spec/{slug}/TECH.md — the phased YAML-FSM driven by /docs-draft. Second step of the documentation factory (see .agents/factory/methodology.md).
disable-model-invocation	true
argument-hint	[appetite small|big] [skip research] [status]
allowed-tools	Read, Write, Edit, Grep, Glob, Agent, AskUserQuestion, WebSearch, WebFetch, Bash(git status *), Bash(git branch *), Bash(git rev-parse *), Bash(git log *), Bash(git add *), Bash(git commit *), Bash(python3 .agents/factory/bin/*), Bash(python3 -c *)

docs-plan — research → PLAN → TECH

Design the change and generate the phased FSM the drafting step resumes from. Two invariant gates bracket the design so it can't drift from the constitution.

Step 1 — Pre-flight & load

• Confirm a feature/|fix/|refactor/ branch with a clean tree; resolve {slug} from the branch.
• Assert the environment: python3 -c "import yaml, mkdocs" (activate .venv/conda if it fails).
• Read spec/{slug}/GOAL.md, .agents/factory/invariants.md, .agents/factory/style-guide.md, and AGENTS.md. GOAL.md must be committed with no unresolved [NEEDS CLARIFICATION] — if any remain, STOP and return to /docs-feature.

Step 2 — Invariant gate #1 (pre-research)

List the invariant sections this change touches (branch/deploy, generated-content firewall, nav-is-manual, links/assets, front-matter, macros/Jinja, build integrity, WCAG, per-cluster parallelism, HPC accuracy). Confirm the intent is sane; STOP/escalate on a fundamental conflict.

Step 3 — Research fan-out (appetite-scaled)

• small / fix / skip research → skip the fan-out; do a couple of targeted reads (the gold-standard page to mirror, the relevant macros in main.py, the nav neighborhood).
• big → launch parallel read-only Agent subagents, one per rabbit-hole topic, each writing spec/{slug}/research/NN-topic.md (numbered to avoid write conflicts). Existing-site-first: survey how the current docs handle this (archetype, macros, snippets, nav) before the web; reserve WebSearch/WebFetch for external unknowns (HPC vendor specs, reference sites). Then synthesize spec/{slug}/research/00-digest.md.

Research is the one place we parallelize; drafting never is.

Step 4 — Write PLAN.md

From .agents/factory/templates/PLAN.md: summary; design at the right altitude (archetype, page structure/outline, exact nav: placement, macros/snippets to reuse, assets, cross-links, a11y plan); a requirement → design map covering every R-ID; rabbit holes resolved; risks/open questions; and a verification strategy that seeds each phase's verify: (the --strict gate plus nav/front-matter/render checks).

Step 5 — Invariant gate #2 (post-design)

Re-walk the touched invariants against the drafted design; fill PLAN's deviation-justification table (empty is the goal). STOP on an unavoidable CRITICAL conflict.

Step 6 — Generate TECH.md (the FSM)

From .agents/factory/templates/TECH.md, author phases as publishable units (a page or coherent section that builds clean, is wired into nav, and passes structural a11y), ordered scaffold-first (the index.md/hub that sets nav anchors and the resource var), then dependent pages, then a final integration phase (cross-links, breadcrumbs). Per phase set id, name, satisfies (R-IDs), depends_on, parallel (false for anything editing mkdocs.yml/main.py/shared snippets/hubs), hammerable (false for HPC-accuracy/a11y/build phases), hill: uphill, and a real verify:. Set top status: in_progress, current_phase = first phase, base: main, last_updated today.

Validate: python3 .agents/factory/bin/next_phase.py spec/{slug}/TECH.md must exit 0 and report the first phase. If it reports invalid, fix it before committing.

Step 7 — Commit

git add spec/{slug}/research spec/{slug}/PLAN.md spec/{slug}/TECH.md → git commit -m "[{kind}] Plan {slug}: design + phased roadmap" (no Co-Authored-By trailer).

Step 8 — Report & hand off

Summarize the design, the phase list, and any risks/open questions for the human. Recommend /docs-draft to begin executing the roadmap.