edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-09-12 10:28:06 +07:00
Code Issues Packages Projects Releases Wiki Activity

fix: correct stale claims in the router and the READMEs

Browse Source 
Coherence pass over the rewritten docs set. The recurring defect was a
refactor whose removals landed and whose replacements did not.

- tdd: restore the pointer to /codebase-design that the v1.0 changelog
  and ask-matt both claim exists. The inline deep-module notes were
  deleted then; nothing replaced them.
- ask-matt: /grilling and /resolving-merge-conflicts were missing from
  the router entirely. Split grill-me from grill-with-docs on the
  working directory rather than on whether the subject is code.
- READMEs: wayfinder maps decision tickets, not investigation tickets;
  the diagnosing-bugs loop starts by building a loop that goes red;
  improve-codebase-architecture is a survey, not a rescue; grilling
  resolves a design tree and is the primitive behind five skills.
- Drop the /implement reliability claim from the implement and tdd
  pages.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt Pocock
2026-08-05 12:48:02 +01:00
co-authored by Claude Opus 5
parent c33ce1c187
commit 8a475c438d
10 changed files with 20 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/engineering/tdd.md
-4
View File
@@ -54,10 +54,6 @@ Because the refactor step was removed and the description was not. Matt dropped
This is the most-reported friction with the skill ([issue #607](https://github.com/mattpocock/skills/issues/607)). The prompt lists candidate seams by name only, with nothing about what each one catches or misses, so you are choosing between labels. There is no fix shipped yet. The practical workaround is to ask the agent for the trade-offs before answering — what does the component-level seam miss that the integration seam catches, and how much slower is it. It is also why the chain agrees seams up front in `to-spec`, where you have the whole feature in view rather than one prompt.
**I ran `/implement` and it never invoked `/tdd`.**
Known and common. One user's estimate on [issue #479](https://github.com/mattpocock/skills/issues/479) is that `/implement` fails to trigger `/tdd` in about 80% of runs. Two structural reasons: `implement` says to use `tdd` "where possible, at pre-agreed seams", which is satisfied by doing TDD-shaped work without ever invoking the skill, and by the time implementation finishes the instruction is hundreds of lines back in the transcript. Naming it explicitly at the start of the run, or invoking `/tdd` yourself per slice, is the reliable path today.
**It wrote the implementation before the test, even though the skill says red first.**
It happens. One user pushed the model on it and got an unusually honest answer: "I knew the skill said 'one test at a time, watch it fail for the right reason' — I read it. I just defaulted to my normal habit." Matt's position is to live with it: "I've not managed to get agents to do anything 100% of the time. Being too forceful about this is also negative because we don't want to restrict an agent's creativity. So what I've done is I've just accepted that sometimes it will not follow TDD strictly. But overall I still get better results." If strict adherence matters for a particular slice, watch the run rather than trusting the skill to enforce it.