wehub-resource-sync
60 lines
3.5 KiB
Markdown
60 lines
3.5 KiB
Markdown
Quickstart:
|
|
|
|
```bash
|
|
npx skills add mattpocock/skills --skill=to-spec
|
|
```
|
|
|
|
```bash
|
|
npx skills update to-spec
|
|
```
|
|
|
|
[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/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](https://aihero.dev/skills-grill-with-docs). To split the finished spec into tickets, use [to-tickets](https://aihero.dev/skills-to-tickets).
|
|
|
|
## Prerequisites
|
|
|
|
`to-spec` publishes into your issue tracker, so [setup-matt-pocock-skills](https://aihero.dev/skills-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:
|
|
|
|
```txt
|
|
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](https://aihero.dev/skills-grill-with-docs), which sharpens the context so the spec is precise, and [to-tickets](https://aihero.dev/skills-to-tickets), which turns the spec into a set of tickets for [implement](https://aihero.dev/skills-implement) to build. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
|