grill-with-docs

grill-with-docs

Adapted from Matt Pocock's grill-with-docs. A grill-me session that builds two artifacts as it runs:

• CONTEXT.md — the project's shared language.
• docs/adr/NNNN-*.md — one ADR per non-obvious decision.

When to use: Required at packet-intake start of every build (default). Also during packet authoring before the run. Never mid-build — mid-run judgment goes to human-queue.md at the end.

This is the most leveraged skill in the set. A good CONTEXT.md from upfront grilling cuts subagent token usage by 30–50% and is what makes the autonomous build loop possible.

Workflow

1. Establish the lay of the land

Before grilling, read or dispatch an explore subagent to read:

• README.md, package.json, top-level folder names.
• Any existing CONTEXT.md or docs/.

This gives you the existing vocabulary. Don't invent new terms when one already exists.

2. Grill, but log

Run a grill-me session. Start with that skill's preamble if you have not already said it in this chat. After each resolved question:

• If the answer introduces a new noun or verb you'll use repeatedly → add it to CONTEXT.md.
• If the answer is a non-obvious tradeoff → start an ADR.

3. CONTEXT.md format

# CONTEXT — <project name>

## Glossary

- **Slice** — one independently-shippable unit of work in a adam build, defined by `slices/<id>/SPEC.md`.
- **Materialization cascade** — the chain of effects when a draft lesson becomes real.
- **Builder** — a Composer 2 subagent dispatched against one slice.

## Architecture in one paragraph

We use ... with ... boundaries. Data flows from ... to ... via ...

## Conventions

- All times stored as UTC ISO 8601 strings.
- DB IDs are uuid v4.
- We never throw inside React renders; errors bubble through ErrorBoundary.

## Out-of-scope concepts

Things the project explicitly does not implement. Mention them so future agents don't try to wire them up. Example: "We do not have user organizations. There is one user per resource."