diff --git a/.agents/writing-docs.md b/.agents/writing-docs.md index 433c6bf..cc525a8 100644 --- a/.agents/writing-docs.md +++ b/.agents/writing-docs.md @@ -1,57 +1,81 @@ # Writing docs pages -Every promoted skill (`engineering/`, `productivity/`, `misc/`) has a human-facing **docs page** at `docs/.md`, published at `https://aihero.dev/skills-`. The page is not the skill and not a copy of `SKILL.md` — it is the explainer a human reads to decide whether to reach for the skill. Skills in `personal/`, `in-progress/`, and `deprecated/` get no page, mirroring the README rule. +Every promoted skill (`engineering/`, `productivity/`, `misc/`) has a human-facing **docs page** at `docs//.md` — the docs tree mirrors the bucket folders under `skills/`. It is published at `https://aihero.dev/skills-`; the URL is always `skills-` regardless of bucket, so the docs path is repo organisation only. The page is not the skill and not a copy of `SKILL.md`. -Act whenever a promoted skill is added, renamed, or has its behaviour changed: create or re-sync its docs page. A rename moves the file too (`docs/.md` → `docs/.md`), because the published URL tracks the name. +Most of these skills are **user-invoked**: the agent will never fire them for you, so *you* are the index that has to remember they exist and when to reach for them. That memory is **cognitive load**. The job of a docs page is to relieve it — to orient one reader around one skill so they can hold it in their head, know when to reach for it, and see where it sits in the system. The pages are collectively a distributed router; each is a node. + +Act whenever a promoted skill is added, renamed, or has its behaviour changed: create or re-sync its docs page. A rename moves the file too (`docs//.md` → `docs//.md`), because the published URL tracks the name; a skill that moves buckets moves its docs file to the matching folder. Skills in `personal/`, `in-progress/`, and `deprecated/` get no page, mirroring the README rule. Because these pages are published on `aihero.dev`, **every link is absolute** — never a repo-relative path. A link to another skill points at `https://aihero.dev/skills-`; a link into the repo points at its full `https://github.com/mattpocock/skills/...` URL. A relative link that works in the repo breaks once published. +There is no H1 — the published page takes its title from the slug. + ## Page structure -Fill the template below. The **fixed frame** (install block, source link, `## What it does`) appears on every page. The **adaptable middle** carries only the sections this particular skill earns — delete the ones it doesn't. +Fill the template below. The **fixed frame** (Quickstart block, source link, `## What it does`, `## When to reach for it`, `## Where it fits`) appears on every page. The **adaptable middle** — `## Prerequisites` and the free-form substance sections — carries only what this particular skill earns; delete the rest. +Quickstart: + ```bash npx skills add mattpocock/skills --skill= ``` +```bash +npx skills update +``` + [Source](https://github.com/mattpocock/skills/tree/main/skills//) ## What it does One or two plain-language paragraphs. Lead with the skill's one-sentence job, then state the **load-bearing constraint** — the single fact that makes this skill behave differently from the obvious default (for `to-prd`: it does not interview the user again, it synthesises what is already known). This line is the most valuable on the page; never omit it. -## +## When to reach for it -Unpack what the skill produces or how it moves — e.g. a list of the artifact's parts, or a description of the loop it runs. Use as many of these sections as the skill needs; omit if it needs none. +How and when you reach for the skill — two beats, both effectively always present: -## +- **Invocation mode.** State whether you type it or the agent fires it. A user-invoked skill: "You invoke this by typing `/` — the agent won't reach for it on its own." A model-invoked skill: "Type `/`, or the agent reaches for it automatically when a task fits." +- **Trigger boundary.** The index entry: "reach for this when …". Where the skill is confusable with a sibling, add the other half — "for instead, use [](https://aihero.dev/skills-)." -Name the one idea worth calling out, in the skill's own vocabulary, and say why it matters (`to-prd`'s `## Deep modules` explains what a deep module is and why it helps agentic testing). Omit if there is none. +## Prerequisites -## How it fits the workflow +Optional — include only when the skill needs something in place to be functional; omit the heading entirely otherwise. Covers: a **workspace it writes into** (a stateful skill like `grill-with-docs` writes `CONTEXT.md` and ADRs; `teach` builds a whole directory — say what it writes and where), **prior setup** (`triage`/`to-prd`/`to-issues` need `setup-matt-pocock-skills` to have configured an issue tracker), or **repo-specific tooling**. A stateless skill that runs anywhere has no prerequisites — drop the section. -```txt -grill-with-docs → to-prd → to-issues → tdd -``` +## -A sentence on where in that chain to reach for the skill. Include only when the skill belongs to a chain. +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. -## Pairs well with +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. -- [](https://aihero.dev/skills-), because-clause saying what the pairing buys +## 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 + +Always present. Situate the skill in the system in a sentence or two: + +- **Role.** Name it: a **chain step** (`grill-with-docs → to-prd → to-issues → tdd`), a **run-once setup** (`setup-matt-pocock-skills`), **periodic maintenance** (`improve-codebase-architecture`, "every few days"), or a **reach-for-it-anytime standalone** (`diagnosing-bugs`, `prototype`, `handoff`). A standalone's map is one honest sentence — far better than omitting the section. +- **Neighbours.** The one or two siblings that matter, each with a because-clause, linked absolutely. +- **The map.** Point to [ask-matt](https://aihero.dev/skills-ask-matt), the router over the whole set, so this page stays a node and never has to redraw the graph. ## Conventions -- Explain the **why**, not the process. The page sells and situates the skill; it never reproduces the `SKILL.md` steps or template dumps — a human choosing a tool does not need the runbook. +- Explain the **why**, not the process. The page orients and situates the skill; it never reproduces the `SKILL.md` steps or template dumps — a human choosing a tool does not need the runbook. - Use the skill's **leading words** (_seam_, _deep module_, _tracer bullet_) so the page and the skill speak one language. +- Keep the page itself low-load. It is documentation *about* low-cognitive-load skills; furniture (spare headings, restated links) is the thing it is arguing against. ## Done when -- The page exists at `docs/.md`, and no stale page survives a rename. -- The install command and source link name the correct bucket and skill. -- The load-bearing constraint is stated in `## What it does`. +- The page exists at `docs//.md`, and no stale page survives a rename or bucket move. +- The Quickstart block and source link name the correct bucket and skill; the update line names the skill. +- `## What it does` states the load-bearing constraint. +- `## When to reach for it` states invocation mode and the trigger boundary. +- `## Where it fits` names the role and links to `ask-matt`. +- A prerequisite (workspace, prior setup, tooling) is stated where one exists, and the section is absent where none does. +- The middle surfaces the leading word. - Every link is absolute, and every one resolves. diff --git a/CLAUDE.md b/CLAUDE.md index b164ee0..39435de 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -13,7 +13,7 @@ Each skill entry in the top-level `README.md` must link the skill name to its `S Each bucket folder has a `README.md` that lists every skill in the bucket with a one-line description, with the skill name linked to its `SKILL.md`. Bucket `README.md`s and the top-level `README.md` group entries into **User-invoked** and **Model-invoked**. -Every promoted skill also has a human-facing docs page at `docs/.md`. When you add, rename, or change the behaviour of a skill in `engineering/`, `productivity/`, or `misc/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). +Every promoted skill also has a human-facing docs page at `docs//.md` (the docs tree mirrors the bucket folders under `skills/`). The published URL is `https://aihero.dev/skills-` regardless of bucket — the docs path is repo organisation only. When you add, rename, or change the behaviour of a skill in `engineering/`, `productivity/`, or `misc/`, create or re-sync its docs page following [.agents/writing-docs.md](./.agents/writing-docs.md). Every `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). See [.agents/invocation.md](./.agents/invocation.md). diff --git a/docs/engineering/to-prd.md b/docs/engineering/to-prd.md new file mode 100644 index 0000000..49f7e94 --- /dev/null +++ b/docs/engineering/to-prd.md @@ -0,0 +1,59 @@ +Quickstart: + +```bash +npx skills add mattpocock/skills --skill=to-prd +``` + +```bash +npx skills update to-prd +``` + +[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/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](https://aihero.dev/skills-grill-with-docs). To split the finished PRD into tickets, use [to-issues](https://aihero.dev/skills-to-issues). + +## Prerequisites + +`to-prd` 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 PRD 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 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. + +## 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 + +`to-prd` is a step in the main build chain: + +```txt +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](https://aihero.dev/skills-grill-with-docs), which sharpens the context so the PRD is precise, and [to-issues](https://aihero.dev/skills-to-issues), which turns the PRD into independently-grabbable issues for [tdd](https://aihero.dev/skills-tdd) to implement. When you're unsure which skill or flow fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you. diff --git a/docs/to-prd.md b/docs/to-prd.md deleted file mode 100644 index 0655d00..0000000 --- a/docs/to-prd.md +++ /dev/null @@ -1,47 +0,0 @@ -Install this skill: - -```bash -npx skills add mattpocock/skills --skill=to-prd -``` - -[Source](https://github.com/mattpocock/skills/tree/main/skills/engineering/to-prd) - -## What it does - -`to-prd` turns the current conversation context and codebase understanding into a product requirements document. - -The important constraint is that it does not interview the user again. It synthesizes what is already known. - -## What the PRD includes - -The generated PRD includes: - -- problem statement -- solution -- extensive numbered user stories -- implementation decisions -- testing decisions -- out-of-scope items -- further notes - -The skill also asks the agent to sketch the major modules that need to be built or modified. - -## Deep modules - -`to-prd` actively looks for deep module opportunities. - -A deep module hides meaningful complexity behind a small, stable, testable interface. That matters for agentic development because a good interface gives tests something durable to target. - -## How it fits the workflow - -```txt -grill-with-docs → to-prd → to-issues → tdd -``` - -Use `to-prd` after the plan and domain language have been resolved. Then use `to-issues` to break the PRD into tracer-bullet implementation issues. - -## Pairs well with - -- [grill-with-docs](https://aihero.dev/skills-grill-with-docs), to make sure the context is precise before the PRD is written -- [to-issues](https://aihero.dev/skills-to-issues), to turn the PRD into implementation tickets -- [tdd](https://aihero.dev/skills-tdd), to implement the resulting issues one behavior at a time