blog.dopana

Back

Alignment first, then feedback loops, then design. This is part 2 of the mattpocock/skills ↗ series — the hands-on loop: /grill-with-docs → /tdd → /diagnosing-bugs → /code-review. Part 1 covered the overview.

The Loop in One Picture#

yesno/grill-with-docs: every branchresolvedOne vertical sliceRED: failing test through publicinterfaceGREEN: minimal fixREFACTOR: deepen moduleMore slices?/code-review: Standards x SpecBug reportReproduce: loop goes red onthis bugMinimiseHypothesise + instrumentFix + regression test

[!NOTE] Grilling only pays if you engage. Short answers in, vague builds out. The skill forces every branch of the design tree resolved before code.

1. Grill-With-Docs: Interview Plus Shared Language#

/grill-me interviews relentlessly about any plan. /grill-with-docs adds the engineering goodies: it sharpens terminology into GLOSSARY.md and records hard decisions as ADRs inline.

ELI5: the agent plays a stubborn 5-year-old asking “why” until no ambiguity remains — then writes down the agreed words so next session starts smart.

session
/grill-with-docs
# agent: "What does 'done' mean for this feature? Which modules change?"
# agent: "You said 'publish' — does that mean persist, enqueue, or notify?"
# result: terms land in GLOSSARY.md, decisions land in docs/adr/
text

Payoff is compounding: concise language → consistent variable, function, file names → easier navigation → fewer thinking tokens.

[!TIP] Use grilling every time before a change, not just big ones. Most popular skills in the repo for a reason.

2. TDD: Red-Green-Refactor per Slice#

The /tdd skill slots into any project: one vertical slice at a time, tests through public interfaces, never implementation details.

tdd-loop
# RED: write failing test for one slice
# GREEN: smallest change making it pass
# REFACTOR: deepen module — more behavior, same small interface
# repeat per slice; /implement drives this at pre-agreed seams
text

Good vs bad, per skill guidance:

  • Good: behavior through public interface, one slice, clear name from glossary
  • Bad: testing internals, giant slices, mocking the unit under test into meaninglessness

3. Diagnosing-Bugs: Disciplined Loop, Gated Phases#

For hard bugs and perf regressions, /diagnosing-bugs wraps best practice into a gated loop:

diagnose
1. Feedback loop going red on THIS bug (reproduce first, always)
2. Minimise the repro
3. Hypothesise (one at a time)
4. Instrument to confirm or kill the hypothesis
5. Fix
6. Regression test so it never returns
text

No jumping to step 5. Each gate must pass before the next opens.

4. Code Review and Ship: Two Axes#

/code-review runs two axes as parallel subagents so neither pollutes the other:

  • Standards — repo coding standards plus Fowler smell baseline
  • Spec — faithful to originating issue/spec?

Then /pr shapes the body: smallest-visual summary, before/after evidence it works, merge-danger call (one-way vs two-way door, blast radius).

5. Architecture: Survey, Not Rescue#

Entropy accelerates at agent speed. Two tools:

  • /to-spec quizzes which modules you touch before speccing
  • /improve-codebase-architecture surveys deepening opportunities (Ousterhout deep modules: much behavior, small interface) into a visual HTML report, then grills your pick

Run it every few days. Honest scope: on genuinely old code it finds candidates but will not untangle mud for you.

Practical Example: Bug to Green#

example
/grill-with-docs      # "checkout retry" — agree: retry means re-enqueue, max 3, idempotency key required
/to-tickets           # slice 1: idempotency key plumbing; slice 2: retry policy; slice 3: UI state
/implement            # TDD per slice at agreed seams
# bug appears: duplicate charge on retry
# model-invoked /diagnosing-bugs: repro red → minimise → hypothesis (key not propagated) → instrument → fix → regression test
# /code-review then /pr
text

Cost Control#

Skills are text and process — cost lives in long grilling, architecture scans, decomposition, repeated reads. Control it: narrow skills per task (/diagnosing-bugs one bug, /tdd one slice, /to-tickets one plan, /handoff to compress context transfer).

Conclusion#

Grill every change, test each slice, diagnose gated, review two-axis. Discipline, not magic — the thinking baked in is the value.

References#