From a2f9333669ff53db762c87ecda5a15442060a3be Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Mon, 3 Aug 2026 17:37:30 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20finish=20the=20to-prd=20=E2=86=92=20to-?= =?UTF-8?q?spec=20rename=20in=20shipped=20text?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Drop the "you may know this document as a PRD" hedge from to-spec and the local tracker template, switch code-review to issue/spec, bring the GitHub and GitLab tracker templates in line with the local one, and fix research.md's dead skills-to-prd link. CHANGELOG and existing changesets keep the old term where they document the rename itself. Co-Authored-By: Claude Opus 5 (1M context) --- .changeset/spec-not-prd.md | 12 ++++++++++++ README.md | 2 +- docs/engineering/research.md | 2 +- docs/engineering/to-spec.md | 2 +- skills/engineering/README.md | 2 +- skills/engineering/code-review/SKILL.md | 6 +++--- .../setup-matt-pocock-skills/issue-tracker-github.md | 2 +- .../setup-matt-pocock-skills/issue-tracker-gitlab.md | 2 +- .../setup-matt-pocock-skills/issue-tracker-local.md | 2 +- skills/engineering/to-spec/SKILL.md | 2 +- skills/in-progress/claude-handoff/SKILL.md | 2 +- 11 files changed, 24 insertions(+), 12 deletions(-) create mode 100644 .changeset/spec-not-prd.md diff --git a/.changeset/spec-not-prd.md b/.changeset/spec-not-prd.md new file mode 100644 index 0000000..f8e3082 --- /dev/null +++ b/.changeset/spec-not-prd.md @@ -0,0 +1,12 @@ +--- +"mattpocock-skills": patch +--- + +Finish the `to-prd` → `to-spec` rename: "spec" is now the only term in the shipped text. + +- **`to-spec`** no longer opens with "you may know this document as a PRD" — the parenthetical is dropped from the skill and its docs page. The local-markdown tracker template drops the same hedge. +- **`code-review`** talks about the originating issue/spec rather than issue/PRD, in its frontmatter description, its two-axis summary, and the spec-source search order. Both READMEs re-synced. +- **The GitHub and GitLab tracker templates** now say "Issues and specs for this repo live as GitHub/GitLab issues" — they had been left on "PRDs" when the local template was updated, so the stale term propagated into every repo they were written into. +- **`docs/engineering/research.md`** pointed at `https://aihero.dev/skills-to-prd`, a dead slug for the renamed skill; it now links `to-spec` like the other nineteen docs pages do. + +The CHANGELOG and existing changesets still name PRDs where they document the rename itself, which is correct. diff --git a/README.md b/README.md index 8c9e72b..5304e37 100644 --- a/README.md +++ b/README.md @@ -194,7 +194,7 @@ Skills I use daily for code work. - **[tdd](./skills/engineering/tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./skills/engineering/domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms against the glossary, stress-test with edge-case scenarios, and update `CONTEXT.md` and ADRs inline. - **[codebase-design](./skills/engineering/codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. -- **[code-review](./skills/engineering/code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/PRD?), run as parallel sub-agents so neither pollutes the other. +- **[code-review](./skills/engineering/code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents so neither pollutes the other. - **[resolving-merge-conflicts](./skills/engineering/resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`. ### Productivity diff --git a/docs/engineering/research.md b/docs/engineering/research.md index 308765c..5254b41 100644 --- a/docs/engineering/research.md +++ b/docs/engineering/research.md @@ -26,4 +26,4 @@ The defining move is that the reading runs as a **background agent**. You keep w ## Where it fits -A reach-for-it-anytime standalone that feeds the thinking skills: the file it produces is something to grill, plan, or design against, so it sits upstream of work like [grilling](https://aihero.dev/skills-grilling) and [to-prd](https://aihero.dev/skills-to-prd) rather than in the build chain. For the whole map, see [ask-matt](https://aihero.dev/skills-ask-matt). +A reach-for-it-anytime standalone that feeds the thinking skills: the file it produces is something to grill, plan, or design against, so it sits upstream of work like [grilling](https://aihero.dev/skills-grilling) and [to-spec](https://aihero.dev/skills-to-spec) rather than in the build chain. For the whole map, see [ask-matt](https://aihero.dev/skills-ask-matt). diff --git a/docs/engineering/to-spec.md b/docs/engineering/to-spec.md index 2e3c99d..1f9b23f 100644 --- a/docs/engineering/to-spec.md +++ b/docs/engineering/to-spec.md @@ -12,7 +12,7 @@ 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. +`to-spec` turns the current conversation and your codebase understanding into a spec, 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. diff --git a/skills/engineering/README.md b/skills/engineering/README.md index 4d66549..aef27be 100644 --- a/skills/engineering/README.md +++ b/skills/engineering/README.md @@ -27,5 +27,5 @@ Model- or user-reachable (rich trigger phrasing so the model can reach for them) - **[tdd](./tdd/SKILL.md)** — Test-driven development with a red-green-refactor loop. Builds features or fixes bugs one vertical slice at a time. - **[domain-modeling](./domain-modeling/SKILL.md)** — Actively build and sharpen a project's domain model — challenge terms, stress-test with scenarios, update `CONTEXT.md` and ADRs inline. - **[codebase-design](./codebase-design/SKILL.md)** — Shared discipline and vocabulary for designing deep modules: small interfaces, clean seams, testable through the interface. -- **[code-review](./code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/PRD?), run as parallel sub-agents. +- **[code-review](./code-review/SKILL.md)** — Two-axis review of the diff since a fixed point: **Standards** (does it follow the repo's coding standards, plus a Fowler smell baseline?) and **Spec** (does it faithfully implement the originating issue/spec?), run as parallel sub-agents. - **[resolving-merge-conflicts](./resolving-merge-conflicts/SKILL.md)** — Work through an in-progress git merge or rebase conflict hunk by hunk, resolving by intent traced to each side's primary source, then finish the operation — never `--abort`. diff --git a/skills/engineering/code-review/SKILL.md b/skills/engineering/code-review/SKILL.md index 2a0b524..62a18e4 100644 --- a/skills/engineering/code-review/SKILL.md +++ b/skills/engineering/code-review/SKILL.md @@ -1,12 +1,12 @@ --- name: code-review -description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/PRD asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". +description: Review the changes since a fixed point (commit, branch, tag, or merge-base) along two axes — Standards (does the code follow this repo's documented coding standards?) and Spec (does the code match what the originating issue/spec asked for?). Runs both reviews in parallel sub-agents and reports them side by side. Use when the user wants to review a branch, a PR, work-in-progress changes, or asks to "review since X". --- Two-axis review of the diff between `HEAD` and a fixed point the user supplies: - **Standards** — does the code conform to this repo's documented coding standards? -- **Spec** — does the code faithfully implement the originating issue / PRD / spec? +- **Spec** — does the code faithfully implement the originating issue / spec? Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. @@ -28,7 +28,7 @@ Look for the originating spec, in this order: 1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`. 2. A path the user passed as an argument. -3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature. +3. A spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature. 4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available". ### 3. Identify the standards sources diff --git a/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md b/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md index 82cfbf5..bf595e2 100644 --- a/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md +++ b/skills/engineering/setup-matt-pocock-skills/issue-tracker-github.md @@ -1,6 +1,6 @@ # Issue tracker: GitHub -Issues and PRDs for this repo live as GitHub issues. Use the `gh` CLI for all operations. +Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations. ## Conventions diff --git a/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md b/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md index 8a54714..95e49cb 100644 --- a/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md +++ b/skills/engineering/setup-matt-pocock-skills/issue-tracker-gitlab.md @@ -1,6 +1,6 @@ # Issue tracker: GitLab -Issues and PRDs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations. +Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations. ## Conventions diff --git a/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md b/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md index 6b124b3..fbda5e0 100644 --- a/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md +++ b/skills/engineering/setup-matt-pocock-skills/issue-tracker-local.md @@ -1,6 +1,6 @@ # Issue tracker: Local Markdown -Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`. +Issues and specs for this repo live as markdown files in `.scratch/`. ## Conventions diff --git a/skills/engineering/to-spec/SKILL.md b/skills/engineering/to-spec/SKILL.md index f3cca8d..3fd6495 100644 --- a/skills/engineering/to-spec/SKILL.md +++ b/skills/engineering/to-spec/SKILL.md @@ -4,7 +4,7 @@ description: Turn the current conversation into a spec and publish it to the pro disable-model-invocation: true --- -This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know. +This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user — just synthesize what you already know. The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not. diff --git a/skills/in-progress/claude-handoff/SKILL.md b/skills/in-progress/claude-handoff/SKILL.md index 88ce8be..69b26bc 100644 --- a/skills/in-progress/claude-handoff/SKILL.md +++ b/skills/in-progress/claude-handoff/SKILL.md @@ -11,7 +11,7 @@ Always pass `-n`/`--name` with a descriptive name (e.g. `--name "Fix login bug"` Include a "suggested skills" section in the summary, which suggests skills that the agent should invoke. -Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. +Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead. Redact any sensitive information, such as API keys, passwords, or personally identifiable information — the summary becomes the agent's prompt.