arda/skills
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add "It's working if" convention; flesh out PRD section

Browse source 
- Replace the inline "watch for the leading words" line with an
  optional `## It's working if` section — a short list of observable
  signals the skill is doing its job. Keeps observability from being
  hammered onto leading words specifically.
- Build out to-prd's "What the PRD includes" with proper casing and a
  one-line explainer per section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Matt Pocock 2026-07-01 11:05:35 +01:00
parent 77cc47773c
commit 340d01b145
2 changed files with 19 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

6
.agents/writing-docs.md
View file

@ -47,7 +47,11 @@ Optional — include only when the skill needs something in place to be function
One to three short sections, in the skill's *own vocabulary*, that make it click — choose whatever headings fit the skill: the loop it runs, the artifact it produces, the fork it makes, the one anti-pattern it kills. There is no prescribed heading; the skills are too heterogeneous for one. One to three short sections, in the skill's *own vocabulary*, that make it click — choose whatever headings fit the skill: the loop it runs, the artifact it produces, the fork it makes, the one anti-pattern it kills. There is no prescribed heading; the skills are too heterogeneous for one.
The single non-negotiable: **surface the skill's leading word / load-bearing idea** — `tight` feedback loop, `deep module`, throwaway-code-answers-a-question, red-green. It pays off three ways: the reader learns what the skill *is*, learns the word they'll later think with to *reach for* it, and learns the word to *watch for in the agent's output* — if the leading words come out, the skill fired and is thinking in its own frame; if they don't, that's the tell something is off. The single non-negotiable: **surface the skill's leading word / load-bearing idea** — `tight` feedback loop, `deep module`, throwaway-code-answers-a-question, red-green. It pays off twice: the reader learns what the skill *is*, and learns the word they'll later think with to *reach for* it.
## It's working if
Optional. A short, checkable list of the observable signals that tell the reader the skill is actually doing its job — what they should see when it fires, and by absence when it hasn't. Include it when a skill has crisp tells (e.g. `to-prd` writes without re-interviewing you; a leading word reappearing in the trace); omit the heading when the signals are vague. A few bullets, no more.
## Where it fits ## Where it fits

22
docs/engineering/to-prd.md
View file

@ -28,19 +28,25 @@ Reach for it once a change has been talked through and the domain language is se
## What the PRD includes ## What the PRD includes
- problem statement - **Problem statement** — what is broken or missing, and why it's worth solving, in the project's own vocabulary.
- solution - **Solution** — the shape of the fix at a high level, before any implementation detail.
- extensive numbered user stories - **User stories** — an extensive, numbered list of the concrete behaviours the change must support, each one independently checkable.
- implementation decisions - **Implementation decisions** — the choices already settled during the conversation, so they aren't relitigated later.
- testing decisions - **Testing decisions** — the seams the feature will be tested at, and what "done" looks like.
- out-of-scope items - **Out-of-scope items** — what this change deliberately does *not* cover, to keep the ticket bounded.
- further notes - **Further notes** — anything else worth carrying forward that doesn't fit the sections above.
## Deep modules ## Deep modules
Before writing the PRD, `to-prd` sketches the **seams** at which the feature will be tested and looks for **deep module** opportunities — a lot of functionality hidden behind a small, stable interface. It prefers existing seams to new ones and the highest seam possible, ideally just one across the whole change. Before writing the PRD, `to-prd` sketches the **seams** at which the feature will be tested and looks for **deep module** opportunities — a lot of functionality hidden behind a small, stable interface. It prefers existing seams to new ones and the highest seam possible, ideally just one across the whole change.
That matters for agentic development: a good interface gives tests something durable to target, so the code underneath can change without the tests moving. If you see the words _seam_ and _deep module_ coming back at you as it works, the skill is doing its job. That matters for agentic development: a good interface gives tests something durable to target, so the code underneath can change without the tests moving.
## It's working if
- It starts writing the PRD instead of asking you a fresh round of questions.
- It checks the seams with you before writing, and proposes as few as possible.
- The PRD comes back in your project's domain vocabulary, not generic boilerplate.
## Where it fits ## Where it fits