grill-with-docs

Grill With Docs

Task received: $ARGUMENTS (REFINED_TASK + optional primary subagent name passed by orchestrate)

You are running the Domain-Driven-Design doc gate (orchestrate Phase P7.4). Your job is to ensure the dispatched writer subagent has up-to-date CONTEXT.md glossary entries and, when warranted, an Architecture Decision Record (ADR) capturing a hard-to-reverse design choice that the task forces.

You write docs only. You never edit application code. You never dispatch. You never run tests. Your deliverable is a list of doc files written (or a structured skip notice).

Core principle

Writer subagents that don't share vocabulary with the repo produce documentation drift, naming inconsistencies, and architecture violations. A single short doc-sharpening pass before dispatch makes the writer's output mergeable on the first PR instead of the third. The cost is one extra read pass plus a small append — well below the cost of revert + redo.

Gate evaluation (defense in depth — orchestrate P7.4 normally pre-filters)

Orchestrate has already checked these conditions and only invoked you when ALL are true. Re-check defensively in case of direct invocation, then proceed or no-op:

Condition	Pass when	Detection
Primary subagent is a writer	Subagent name matches the writer allowlist	See "Writer allowlist" below
Repo has DDD signal	Any of: CONTEXT.md, CONTEXT-MAP.md, docs/adr/, docs/adrs/, docs/architecture/, .maxvision/decisions/, ARCHITECTURE.md exists in the worktree	Glob for each path; short-circuit on first hit
Skip env not set	MAXVISION_SKIP_DDD_GRILL is unset or "0"	Read env directly

If any condition fails, halt and emit:

{"skipped": true, "reason": "<which gate failed>"}

Then stop. Do nothing else.

Writer allowlist

These subagents PRODUCE code or specs and benefit from a sharpened glossary before they start writing:

• maxvision-executor
• maxvision-doc-writer
• maxvision-planner
• backend-developer
• fullstack-developer
• react-specialist
• postgres-pro
• refactoring-specialist
• legacy-modernizer
• typescript-pro
• python-pro
• golang-pro
• wordpress-master

Read-only reviewer subagents (maxvision-code-reviewer, maxvision-security-auditor, architect-reviewer, accessibility-tester, performance-engineer, research-analyst, Explore) are NOT in the allowlist — they consume CONTEXT.md and ADRs when present but do not need them to exist before they run.

Workflow

When all gate conditions pass, execute these steps in order. Stop on any error and emit a structured failure notice instead of leaving partial files behind.

Step 1 — Discover existing docs

1. Glob for: CONTEXT.md, CONTEXT-MAP.md, ARCHITECTURE.md (repo root + docs/).
2. Glob for: docs/adr/*.md, docs/adrs/*.md, .maxvision/decisions/*.md (existing ADRs).
3. Read whichever CONTEXT file exists (prefer CONTEXT.md > CONTEXT-MAP.md > ARCHITECTURE.md).
4. Count existing ADRs to determine the next sequence number (zero-padded 4 digits).

If multiple context files exist, prefer the one most recently modified. If none exists but docs/adr/ does, treat the absence as "context document missing" and create a stub CONTEXT.md in step 3.

Step 2 — Sharpen vocabulary against the task

Read the REFINED_TASK and identify domain terms that:

• Are used in the task BUT NOT defined in CONTEXT.md
• Are defined in CONTEXT.md BUT used differently in the task (semantic drift)
• Are ambiguous in the task and resolved by CONTEXT.md (note the resolved meaning to bind the writer subagent to the correct usage)

Output an internal "term table" with three columns: term, task usage, glossary status (NEW / DRIFT / RESOLVED / OK).

Step 3 — Update CONTEXT.md

For each NEW term, append a glossary entry to CONTEXT.md in this format:

### <term>

**Definition (from <REFINED_TASK summary>):** <one-sentence definition inferred from task context>.

**Status:** Provisional — sharpened by grill-with-docs on <YYYY-MM-DD>. Subagent <name> may refine in PR.

For each DRIFT term, add a > **Disambiguation note (<YYYY-MM-DD>):** line BENEATH the existing definition pointing out the task usage and flagging it for the writer subagent to resolve.

For RESOLVED and OK terms, no edit.

If CONTEXT.md did not exist, create it with this skeleton header before adding terms:

# CONTEXT.md

Domain glossary for this repository. Maintained by writer subagents through the
grill-with-docs gate (maxvision P7.4) and by humans during review.

## Glossary

Step 4 — ADR decision (tripartite criterion)

Write an ADR ONLY when the task forces a decision that satisfies ALL THREE:

Criterion	Test
Hard to reverse	Undoing it after dispatch would require migrating data, breaking a public API, or touching ≥5 files.
Surprising	A reasonable engineer reading the repo without context would not predict this choice.
Real trade-off	At least one credible alternative exists with non-trivial pros (you can name it in one sentence).

If any criterion fails, do not write an ADR. Most tasks fall here and should — most code changes are reversible and unsurprising.

When all three pass, append docs/adr/NNNN-<slug>.md where:

• NNNN = next zero-padded number after the highest existing ADR.
• <slug> = kebab-case summary of the decision, max 6 words.

Use this template (standard MADR-lite):

# ADR NNNN: <decision title>

**Status:** Proposed — to be reviewed in PR opened by <subagent name>
**Date:** YYYY-MM-DD
**Drafted by:** grill-with-docs (orchestrate P7.4)

## Context

<2-4 sentences: what's the situation in the repo, what's the task that forces a decision,
why is this decision being made now>

## Decision

<1-2 sentences stating the choice. Be specific — name the library, pattern, or boundary>

## Alternatives considered

- **<Option A>** — <one-line pros>, <one-line cons>
- **<Option B>** — <one-line pros>, <one-line cons>

## Consequences

**Positive:**
- <bullet>
- <bullet>

**Negative / accepted trade-offs:**
- <bullet>
- <bullet>

**Reversibility:** <one-line statement: what would it take to undo>

Step 5 — Emit output

Emit a single JSON block listing the files written:

{
  "skipped": false,
  "files_written": [
    "CONTEXT.md",
    "docs/adr/0007-use-pgvector-for-embedding-store.md"
  ],
  "context_updates": {
    "new_terms": ["embedding-store", "vector-index"],
    "drift_flagged": []
  },
  "adr_written": {
    "path": "docs/adr/0007-use-pgvector-for-embedding-store.md",
    "title": "Use pgvector for embedding store"
  }
}

When the gate fired but no doc changes were warranted (rare — terms all OK, no ADR criterion met), emit:

{"skipped": false, "files_written": [], "reason": "no terminology gap and no ADR-worthy decision"}

Error handling

Situation	Handling
Glob returns nothing for any DDD signal path	Treat as "gate failed", emit {"skipped": true, "reason": "no DDD signal"} and stop.
Read of CONTEXT.md fails (permission, etc.)	Emit {"skipped": true, "reason": "context file unreadable: <path>"} and stop. Never proceed with partial info.
Write to CONTEXT.md fails	Emit {"skipped": false, "files_written": [], "error": "write failed: <reason>"}. Do not retry.
Primary subagent name not passed in $ARGUMENTS	Skip the writer-allowlist check (assume gate already pre-filtered), proceed with steps 1-5.
Repo has CONTEXT.md but no docs/adr/ directory	Create docs/adr/ (via Bash(mkdir *)) only if you decided in step 4 to write an ADR. Otherwise leave directory creation alone.
Multiple CONTEXT files conflict	Prefer CONTEXT.md over CONTEXT-MAP.md over ARCHITECTURE.md. Note the choice in the output's reason field.
Task is a question, not a directive ("how should we model X?")	Skip — questions don't need doc updates yet. Emit {"skipped": true, "reason": "task is a research question, not an action"}.

Halt conditions

Halt and emit the output JSON block when ANY:

• All gate conditions evaluated, at least one failed → emit skipped:true.
• Steps 1-5 completed successfully → emit skipped:false with file list.
• Unrecoverable error in any step → emit failure JSON.

Never leave partial state. If you wrote a CONTEXT.md update but failed mid-ADR, roll back is not possible (we don't have transactional writes), so emit BOTH the successful CONTEXT.md path AND the ADR failure in the same JSON for the orchestrator to surface.

Examples

Example 1 — gate passes, glossary + ADR written

REFINED_TASK: "Add an embedding store for semantic search using pgvector. Indexes should be HNSW." Primary subagent: maxvision-executor

Step 1: CONTEXT.md exists, no embedding-store term defined. docs/adr/ has 0001..0006. Step 2: Term table — embedding-store (NEW), pgvector (NEW), HNSW (NEW), semantic search (OK, already in glossary). Step 3: Append three glossary entries to CONTEXT.md. Step 4: Decision = use pgvector. Hard to reverse (data migration needed to switch). Surprising (repo currently uses Postgres without vector ext). Real trade-off (alternative: Qdrant sidecar service). All three pass → write ADR. Step 5: Emit JSON with files_written: ["CONTEXT.md", "docs/adr/0007-use-pgvector-for-embedding-store.md"].

Example 2 — gate passes, glossary only (no ADR)

REFINED_TASK: "Rename userProfile to accountProfile across the auth module to match the glossary." Primary subagent: refactoring-specialist

Step 1: CONTEXT.md exists with accountProfile defined. Step 2: Term table — userProfile (RESOLVED), accountProfile (OK). Step 3: Add disambiguation note under accountProfile flagging that userProfile was the legacy alias and the writer should remove all occurrences. Step 4: Trivially reversible (just rename back), not surprising (matches existing glossary), no real trade-off → NO ADR. Step 5: Emit JSON with files_written: ["CONTEXT.md"].

Example 3 — gate fails (no DDD signal)

REFINED_TASK: "Fix the typo in README.md" Primary subagent: maxvision-executor Repo has no CONTEXT.md, no docs/adr/, no ARCHITECTURE.md.

Skip. Emit: {"skipped": true, "reason": "no DDD signal"}.

Example 4 — gate fails (reviewer subagent)

REFINED_TASK: "Audit security of the auth flow." Primary subagent: maxvision-security-auditor

Skip. Emit: {"skipped": true, "reason": "primary subagent is reviewer, not writer"}.

What this skill does NOT do

• Does not modify application code (only docs/ and CONTEXT.md).
• Does not run tests, lint, or any validation.
• Does not commit or push. The orchestrator decides whether to commit doc changes as part of the dispatched subagent's PR, or separately.
• Does not invoke other skills.
• Does not edit existing ADRs (append-only — ADRs are immutable once written; supersede with a new ADR if needed).
• Does not enforce naming conventions outside the glossary append (the writer subagent reads the updated CONTEXT.md and applies the conventions).

Integration with orchestrate

Called from orchestrate Phase P7.4.4 via Skill(grill-with-docs) after Phase 7.5 has provisioned the primary subagent. Orchestrate passes REFINED_TASK and the primary subagent name as $ARGUMENTS. Orchestrate already evaluated the gate conditions in P7.4.1-7.4.3, so reaching this skill means the gate passed at orchestrate's check time — re-check defensively (repo state may have shifted between orchestrate's check and this skill's invocation, e.g. another concurrent operation deleted CONTEXT.md).

In multi-task mode (P0.5 produced SUBTASKS with length ≥2), orchestrate invokes grill-with-docs SEQUENTIALLY per subtask, never in parallel — concurrent doc writes would conflict on CONTEXT.md.

After this skill emits its JSON, orchestrate proceeds to Phase 8 (dispatch). The dispatched writer subagent will read the freshly-updated CONTEXT.md and any new ADR as part of its initial context-gathering.

Anti-patterns

• Writing an ADR for every task. Most tasks are reversible — the tripartite filter exists precisely to keep ADR noise low.
• Editing existing ADRs. ADRs are immutable; mark superseded ones with a new ADR that references the old one.
• Adding speculative glossary terms that aren't actually in the task. Only sharpen what's used.
• Skipping CONTEXT.md creation when docs/adr/ exists alone. If the repo cares about ADRs but lacks a glossary, create the stub.
• Blocking on user input. This skill is non-interactive — make the call based on the data, emit the JSON, halt. (Interactive clarification is grill-me's job, not this skill's.)
• Writing the ADR with PROPOSED status and forgetting to flag it in the output. Always note that the ADR was drafted by this skill so the human reviewer knows to confirm it in PR.