# Grill With Docs > Post-plan stress test. Use AFTER a plan is drafted (Goal anchor, ideation candidate, rebuttal strategy, pipeline template) to gap-check the plan against the project's existing documentation, terminology, and recent reviewer / handoff history in `.copilot/`. Sharpens fuzzy terms inline, cross-references the codebase / tex / logs, and offers ADRs only when a decision is hard to reverse. Never used to draft the plan itself. Triggers on: '校验计划', '对着文档拷问', '把计划放到文档里盘一遍', 'grill the plan', 'stress-test plan', 'audit plan against docs', 'check plan for gaps'. - Skill: `ldm2060/grill-with-docs` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ldm2060/grill-with-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/ldm2060/grill-with-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: ldm2060 (https://skillmd.com/u/ldm2060) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ldm2060/grill-with-docs --- # Grill with docs — Post-plan gap check Run **after** a plan exists (Goal anchor in `experiments.md`, selected direction in `ideas.md`, response strategy in `rebuttal/round-N.md`, or routing decision in `decisions.md`). Purpose: stress-test that plan against the project's existing language and documented state, surface contradictions, and update the docs inline as terminology is resolved. This skill is **not for plan drafting**. If no plan exists yet, run `deep-interview` first, hand off to the planning agent, then return here. ## When this skill fires Fire automatically when the most recent disk write was one of: - `## Goal anchor` block freshly written to `.copilot/experiments.md` - A new `## Selected direction` in `.copilot/ideas.md` - A new `## Reviewer N strategy` block in `rebuttal/round-N.md` - A new pipeline template entry in `.copilot/decisions.md` Also fires on user request: "校验一下这个计划" / "grill this plan." ## Documentation surface (auto-detected) ``` .copilot/ ├── state.md ← stage cursor + loop counters ├── literature.md ← locked baseline + related work ├── ideas.md ← user preferences + candidates + selected ├── experiments.md ← Goal anchor + Run-N history ├── handoff.md ← writer / polisher / reviewer / rebuttal facts ├── decisions.md ← approval-gate decisions ├── glossary.md ← created lazily by THIS skill on first term resolve ├── adr/ ← created lazily by THIS skill on first ADR └── reviews/round-N.md ← independent review rounds ``` `glossary.md` and `adr/` are created **only when** the first term / first ADR appears — do not pre-create empty scaffolds. ## Procedure ### Step 1 — Read the plan + the docs Load the just-written plan block and the relevant `.copilot/` files. For multi-doc projects (rare in this repo), also load any sibling `CONTEXT.md` / `CONTEXT-MAP.md` if present. ### Step 2 — Run the four challenges, in order | Challenge | What you do | |---|---| | **Glossary clash** | For every noun phrase in the plan, check `.copilot/glossary.md` (and the existing tex / `ideas.md` / `literature.md`). If a term collides with prior usage or is fuzzy ("module," "robustness," "improvement"), propose a precise canonical term and ask the user to confirm. Update `glossary.md` inline when resolved. | | **Sharpen fuzzy language** | For every claim ("works better," "more robust," "faster"), demand the metric / unit / baseline / threshold. Push the user to a number or a falsifiable shape. | | **Concrete scenario stress test** | For every relationship in the plan ("Module A feeds Module B"), spell out one concrete scenario end-to-end. If the scenario breaks, flag it before any experiment burns compute. | | **Cross-reference with code / data** | For every "how it works" claim, grep the codebase / tex / logs and confirm the code agrees. If the plan describes behaviour the code does not exhibit, the plan is wrong — flag it. | Each challenge runs **once** per pass. One question at a time, with a recommended answer + the file:line that motivated the question. ### Step 3 — Update docs inline (lazy creation) When a term is resolved, write to `.copilot/glossary.md` immediately: ```markdown ## - Definition: - First defined: (during grill-with-docs of ) - Aliases to avoid: - Used in: ``` Create `glossary.md` if it does not yet exist. ### Step 4 — Offer an ADR only when all three are true Add to `.copilot/adr/NNNN-.md` only when: 1. **Hard to reverse** — changing this mid-project means redoing experiments / rewriting sections 2. **Surprising without context** — a future reader (or a reviewer) will ask "why this way?" 3. **Result of a real trade-off** — there were ≥2 alternatives, one was picked for a specific reason If even one is false, skip the ADR. Most decisions live in `decisions.md` already and do not need promotion. Number ADRs by file count: first ADR is `0001-.md`. ADR template: ```markdown # — - Status: accepted | superseded by NNNN - Date: <YYYY-MM-DD> - Context: <2-3 sentences — why this came up, which plan triggered it> - Decision: <the chosen alternative, one sentence> - Alternatives considered: <list with one-line "why not"> - Consequences: <experiments / sections / future ablations this commits us to> ``` ## Output When the pass finishes, emit: ```markdown ## Grill-with-docs report — <plan slug> - Date: <YYYY-MM-DD> - Plan reviewed: <file:line> - Glossary entries added / updated: <count> → <glossary.md anchors> - Fuzzy claims sharpened: <count> → <plan file:line edits> - Scenarios stress-tested: <count> → <list of scenarios + outcomes> - Code cross-references: <count> → <files / functions verified> - ADRs created: <count> → <adr/NNNN-*.md anchors, or "none — bar not met"> - Plan changes proposed: <list of edits to the plan file, with file:line> - Residual risks: <list anything you grilled and could not resolve> - Hand off to: <agent who acts on the changes, or "user approval" if changes need confirmation> ``` ## Hard constraints - **Post-plan only** — if no plan block exists, exit and recommend `deep-interview` first - **Read before challenging** — every challenge must cite a concrete file:line, not "in general" - **Update docs inline** — never batch glossary updates "for the end" - **ADR bar is strict** — three conditions, ALL must hold; otherwise leave the decision in `decisions.md` - **Do not edit the plan unilaterally** — propose edits with file:line; the writing agent (or user) applies them - **One challenge round per pass** — do not loop the four challenges; if more passes are needed, the user explicitly re-invokes - **Lazy file creation** — `glossary.md` and `adr/` directory created only on first real entry