Matt PocockandClaude Opus 4.8
386d4ff719
Executes the `unify-to-tickets` decision (personal-wiki #23), reworking this PR from "add /to-plan" into the full planning-skills unification. - Rename /to-prd → /to-spec. "spec" is now the single through-line term (the skill still opens with "you may know this document as a PRD" for discoverability). - Merge /to-plan + /to-issues into one /to-tickets skill; delete /to-issues. /to-tickets emits a set of tickets, each declaring its blocking edges — one medium-agnostic artifact that reads as a sequential plan (local `tickets.md`, edges as text) or a parallelizable DAG (real tracker, native blocking links). The edges live in the ticket either way; the medium only decides whether anything acts on them in parallel. - ask-matt now routes idea → /to-spec → /to-tickets → /implement. - Sweep every cross-reference (docs pages, chain diagrams, CONTEXT.md, ADRs, .agents, setup templates) to the new names and vocabulary. - Rewrite the changeset to describe the unification. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
3.5 KiB
Quickstart:
npx skills add mattpocock/skills --skill=to-spec
npx skills update to-spec
What it does
to-spec turns the current conversation and your codebase understanding into a spec (you may know this document as a PRD), then publishes it to your issue tracker.
It does not interview you again. By the time you reach for it, the alignment work is done — to-spec synthesises what is already known rather than asking a fresh round of questions.
When to reach for it
You invoke this by typing /to-spec — 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 before any code is written. If you haven't aligned yet, grill first — for that, use grill-with-docs. To split the finished spec into tickets, use to-tickets.
Prerequisites
to-spec 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 spec includes
- Problem statement — what is broken or missing, and why it's worth solving, in the project's own vocabulary.
- Solution — the shape of the fix at a high level, before any implementation detail.
- User stories — an extensive, numbered list of the concrete behaviours the change must support, each one independently checkable.
- Implementation decisions — the choices already settled during the conversation, so they aren't relitigated later.
- Testing decisions — the seams the feature will be tested at, and what "done" looks like.
- Out-of-scope items — what this change deliberately does not cover, to keep the ticket bounded.
- Further notes — anything else worth carrying forward that doesn't fit the sections above.
Deep modules
Before writing the spec, to-spec 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.
It's working if
- It starts writing the spec instead of asking you a fresh round of questions.
- It checks the seams with you before writing, and proposes as few as possible.
- The spec comes back in your project's domain vocabulary, not generic boilerplate.
Where it fits
to-spec is a step in the main build chain:
grill-with-docs → to-spec → to-tickets → implement → code-review
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 spec is precise, and to-tickets, which turns the spec into a set of tickets for implement to build. When you're unsure which skill or flow fits, ask-matt routes you.