/grill-with-docs

name: grill-with-docs
description: Grill a fuzzy, single-session repository change into shared language, recorded decisions, and a handoff-ready plan. Use when the operator asks to grill or stress-test a plan or design in a repository; route multi-session uncertainty to wayfinder.
compatibility: Requires an Agent Skills-compatible coding agent with filesystem access.

Grill with docs

Resolve a change's design tree with the operator while recording each answer where a fresh session can use it. Stop at a handoff-ready plan; implementation is a separate unit of work.

Route

• Use this workflow when a repository change is fuzzy but can be settled in one session.
• Use `wayfinder` when the destination spans sessions, has dependent decisions that need separate

research, or cannot yet become one implementation plan.

• Use the ordinary plan flow when scope, language, and consequential choices are already settled.

Establish the tree

1. Read the tracked item, existing plan/spec, `CONTEXT-MAP.md`, relevant `CONTEXT.md` files, ADRs, and the code or assets that constrain the change. Facts come from the repository; decisions come from the operator. 2. Locate the project's plan convention. Reuse an existing change plan; otherwise create one from `.harness/templates/plan.md`, `templates/plan.md`, or the same shape at `.planning/<slug>.md`, in that order of availability. 3. Map the unresolved choices as a design tree. Its **frontier** is the independent questions whose prerequisites are settled now.

Work the frontier

Ask a small numbered round from the frontier. For each question, state why it matters, the real options and trade-offs, and your recommended answer. Then wait for the operator's decisions.

After each answer round:

1. Recompute the tree. Cross-check claims against the repository and surface contradictions. 2. Record every settled decision in the plan with its original precision: boundaries, ordering, defaults, failure behaviour, numeric constraints, and evidence requirements. 3. Record resolved project language and qualifying ADRs before the next question round.

Repeat until the frontier is empty. A question that depends on an unresolved answer stays off the current frontier.

Durable artifacts

Plan

The plan is the complete decision ledger and implementation handoff. Keep its scope, approach, risks, verification, and done criteria current after each round. Place rationale once: in the plan for ordinary choices, or in an ADR for a qualifying architectural choice with a link from the plan.

Project language

When a project-specific term resolves, update the relevant `CONTEXT.md` immediately using [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md). A root `CONTEXT-MAP.md` selects the bounded context; without one, use the root glossary. Create the file lazily on the first qualifying term.

Architectural decisions

Create an ADR only when the choice passes all three gates in [`ADR-FORMAT.md`](ADR-FORMAT.md): hard to reverse, surprising without context, and the result of a real trade-off. Create `docs/adr/` lazily and preserve the repository's existing ADR convention when one exists.

Completion

Offer the plan for confirmation only when the frontier is empty, every settled decision is durable, repository contradictions are resolved or explicit, and the plan defines end-to-end evidence. The session completes when the operator confirms shared understanding. Report the plan path, glossary and ADR changes, and whether the next route is implementation or `wayfinder`.

--- *Adapted from Matt Pocock's `grilling`, `domain-modeling`, and `grill-with-docs` skills ([MIT](https://github.com/mattpocock/skills/blob/main/LICENSE), 2026). AgentSmith makes the workflow self-contained and keeps every settled decision in the repository plan.*