AGENT SKILL

grill-with-docs

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.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 152
Forks
7

01 前言 Front Matter

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.

02 资源文件 2

03 SKILL.md 正文

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. 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: 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, 2026). AgentSmith makes the workflow self-contained and keeps every settled decision in the repository plan.

04 同仓库更多 Skills

PromptPartner
PromptPartner/agentsmith

portable-fixture

Fixture proving that skill identity comes from metadata rather than its installation path.

★ 152
PromptPartner
PromptPartner/agentsmith

portable-fixture

Fixture proving that skill identity comes from metadata rather than its installation path.

★ 152
PromptPartner
PromptPartner/agentsmith

writing-rules

Write or review anything an agent reads — a core rule, a profile gate, a SKILL.md description, an instruction-file line, a subagent prompt, a handoff note, a verify-phase label. Part of the Agentsmith harness; supplies the levers that decide whether a line changes behaviour or only costs tokens — the two loads, context pointers, the ladder, completion criteria, leading words, the no-op test. Its default move is deletion, so it earns most on a draft that already exists.

★ 152
PromptPartner
PromptPartner/agentsmith

wayfinder

Wayfind a foggy, multi-session effort into an accepted repository spec and separate implementation-ticket drafts. Use when the destination is known but important decisions, dependencies, or scope are not yet clear enough to implement safely.

★ 152
PromptPartner
PromptPartner/agentsmith

verify

Answer "is this shippable / done?" with evidence before a commit or PR — fires on "verify", "is this done", "ready to ship?", pre-commit or pre-PR. Part of the Agentsmith harness; runs the project's verify phases and never claims "passing" without showing the output (R5).

★ 152
PromptPartner
PromptPartner/agentsmith

new-research

Start a durable research / source note that captures what you read and found — fires on "start a research note", "capture these sources", "log my research". Part of the Agentsmith harness; scaffolds docs/research/<slug>.md so findings live in the repo, never in disposable memory (R9), and are never silently deleted.

★ 152