77cc47773c
Reframe docs pages around cognitive-load relief: most skills are user-invoked, so the human is the index that must remember when to reach for each one. Each page's job is to make one skill memorable and situate it in the system. Template changes (.agents/writing-docs.md): - Quickstart block: install + `npx skills update`, install-first - New `## When to reach for it` (invocation mode + trigger boundary) - New optional `## Prerequisites` (workspace/state, prior setup, tooling) - Free-form middle with one firm rule: surface the leading word (also an observability signal in the agent's output) - `## Where it fits`: role-based, absorbs "Pairs well with", links ask-matt - No H1; every cross-link absolute Nest docs under bucket folders (docs/<bucket>/<name>.md); the published URL stays skills-<name> regardless. Re-sync to-prd as the worked exemplar. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2.7 KiB
Quickstart:
npx skills add mattpocock/skills --skill=to-prd
npx skills update to-prd
What it does
to-prd turns the current conversation and your codebase understanding into a product requirements document, then publishes it to your issue tracker.
The load-bearing constraint: it does not interview you again. By the time you reach for it, the alignment work is done — to-prd synthesises what is already known rather than asking a fresh round of questions.
When to reach for it
You invoke this by typing /to-prd — the agent won't reach for it on its own.
Reach for it once a change has been talked through and the domain language is settled, and you want that shared understanding written down as a spec before any code is written. If you haven't aligned yet, grill first — for that, use grill-with-docs. To split the finished PRD into tickets, use to-issues.
Prerequisites
to-prd publishes into your issue tracker, so setup-matt-pocock-skills must have configured the tracker and triage labels for this repo first. It applies the ready-for-agent label itself — no separate triage pass needed.
What the PRD includes
- problem statement
- solution
- extensive numbered user stories
- implementation decisions
- testing decisions
- out-of-scope items
- further notes
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.
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.
Where it fits
to-prd is a step in the main build chain:
grill-with-docs → to-prd → to-issues → tdd
Reach for it after the plan and domain language are resolved, and before you break the work into implementation tickets. Its key neighbours are grill-with-docs, which sharpens the context so the PRD is precise, and to-issues, which turns the PRD into independently-grabbable issues for tdd to implement. When you're unsure which skill or flow fits, ask-matt routes you.