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/implement.md
+1 -5
View File
@@ -44,14 +44,10 @@ One run covers one ticket. The tickets [to-tickets](https://aihero.dev/skills-to
The idea the skill runs on is the **seam**: the public boundary you observe behaviour at, without reaching inside. Tests live at seams. Working at a seam agreed before any code is written is what keeps the tests durable, because the implementation underneath can be rewritten without the tests moving.
The word "pre-agreed" is doing real work, and it is also the skill's weakest joint. Nothing inside `implement` agrees the seams. `tdd` is the skill that asks, and it refuses to write a test at an unconfirmed seam. So in practice the agreement happens either upstream in the spec, or in the first exchange of the run. If it happens nowhere, the precondition never fires and the run quietly becomes "just write the code". That failure is common enough to be the first question below.
The word "pre-agreed" is doing real work, and it is also the skill's weakest joint. Nothing inside `implement` agrees the seams. `tdd` is the skill that asks, and it refuses to write a test at an unconfirmed seam. So in practice the agreement happens either upstream in the spec, or in the first exchange of the run. If it happens nowhere, the precondition never fires and the run quietly becomes "just write the code". Naming the seams in the spec is what stops that.
## Common questions
**It implemented the work but never ran `/tdd` or `/code-review`. Is that expected?**
It is a known, open bug, and it is the single most reported thing about this skill. One reporter estimated `/tdd` fails to fire in about 80% of runs. The diagnosis in the issue thread is context burial: the skill's text is injected once at invocation, and by the time the implementation is done the closing steps are hundreds of lines back with nothing re-surfacing them, so they are the first thing dropped. Others report the opposite inconsistency, with `code-review` running some sessions and not others, or firing per ticket when they didn't ask for it. Matt rejected the proposed fix of stronger completion wording as a no-op, on the grounds that "must" buried 500 lines back reads the same as "should". Until it is fixed structurally, the reliable move is to invoke `/tdd` and `/code-review` yourself rather than expect the chain to hold.
**It finished, but my ticket is still open and the acceptance criteria are still unchecked.**
Correct, and expected. `implement` has no completion step. It ends at the commit and never touches the work item, confirmed on GitHub Issues and on the local markdown tracker, so it is not a tracker integration problem. It also does not act on the findings `code-review` produced, and does not tick the `- [ ]` boxes on the originating issue. Close the ticket and reconcile the criteria yourself. This bites hardest on a dependency chain, because `to-tickets` defines the frontier as tickets whose blockers are all closed. If nothing gets closed, nothing ever becomes visibly unblocked.