Merge pull request #734 from mattpocock/chore/purge-prd-references

docs: finish the to-prd → to-spec rename in shipped text
2026-09-13 02:48:06 +07:00 · 2026-08-04 07:18:55 +01:00 · 2026-08-03 17:37:30 +01:00 · 2026-07-29 12:37:09 +01:00 · 2026-07-29 12:33:07 +01:00 · 2026-07-29 12:29:11 +01:00
11 changed files with 24 additions and 12 deletions
@@ -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.
@@ -209,7 +209,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
@@ -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).
@@ -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.

@@ -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`.
@@ -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
@@ -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

@@ -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

@@ -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

@@ -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.

@@ -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.
Author	SHA1	Message	Date
Matt Pocock	d53cabc383	Merge pull request #734 from mattpocock/chore/purge-prd-references docs: finish the to-prd → to-spec rename in shipped text	2026-08-04 07:18:55 +01:00
Matt PocockandClaude Opus 5	a2f9333669	docs: finish the to-prd → to-spec rename in shipped text 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) <noreply@anthropic.com>	2026-08-03 17:37:30 +01:00
Matt PocockandClaude Opus 5	14b92236dd	docs: describe grilling as round-by-round everywhere The round-by-round rework left the wrappers and callers still promising a one-question-at-a-time interview. Sync grill-me, grill-with-docs and triage (docs + skill step), plus grilling's Codex short_description and the loop-me draft. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-29 12:37:09 +01:00
Matt PocockandClaude Opus 5	950dc79bb0	feat(grilling): bold the question title The title now carries its own bold alongside the bold Q-number, so the question line reads as a heading. Sync the docs page and changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-29 12:33:07 +01:00
Matt PocockandClaude Opus 5	781efca60a	feat(grilling): lead each question with a question-mark emoji Prefix the numbered question line with ❓ so questions and their ➡️ recommendations are both scannable. Sync the docs page and changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-29 12:29:11 +01:00
Matt PocockandClaude Opus 5	4b2d9a8a8a	docs(grilling): drop the Recommendation label from the question format The recommendation now stands alone on its arrow line. Sync the docs page and changeset to match. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-29 12:28:33 +01:00
Matt PocockandClaude Opus 5	a557705dcb	docs(grilling): pin the question format and document it Add the fixed per-question shape (numbered title, body, recommendation line) to grilling's SKILL.md, sync the docs page, and add a changeset. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>	2026-07-29 12:26:31 +01:00
Matt Pocock	9c470b321d	Merge branch 'release/v1.2' of https://github.com/mattpocock/skills into release/v1.2	2026-07-29 12:11:20 +01:00
Matt Pocock	f1df19e6b0	fix: correct formatting in SKILL.md for clarity and consistency	2026-07-29 12:11:19 +01:00
Matt Pocock	41283677d6	Merge pull request #682 from mattpocock/wfa-environment-cache feat(writing-for-agents): add the cache leading word for environment truth	2026-07-28 12:18:20 +01:00
Matt PocockandClaude Opus 5	d4e8664be2	feat(writing-for-agents): add the cache leading word for environment truth Single source of truth now reaches past the document into the environment. package.json scripts, config files, directory layout and --help output are authoritative already, so a doc restating them is a cache of a lookup that earns its load only when the lookup is expensive. Co-authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 12:16:51 +01:00
Matt Pocock	6e742d6441	Merge pull request #679 from mattpocock/graduate-to-questionnaire Graduate to-questionnaire into the Productivity bucket	2026-07-28 10:03:14 +01:00
Matt PocockandClaude Opus 5	ad5ee1e12f	feat: graduate to-questionnaire into the productivity bucket Move `to-questionnaire` out of in-progress into `productivity/` and wire it up as a promoted skill: plugin.json entry, top-level + Productivity READMEs under User-invoked, a docs page at docs/productivity/to-questionnaire.md, and a Standalone route in ask-matt framing it as the inverse of /grill-me. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-07-28 09:59:33 +01:00
Matt Pocock	fa3b2a6b35	Merge pull request #650 from mattpocock/writing-for-agents-rename feat!: rename writing-great-skills → writing-for-agents and restructure	2026-07-27 14:30:41 +01:00
Matt PocockandClaude Opus 4.8	17f22a371b	feat!: rename writing-great-skills to writing-for-agents and restructure The reference now covers any document an agent consumes — skills, AGENTS.md/CLAUDE.md, docs reached by a pointer. GLOSSARY.md merged into SKILL.md as a dedup (Avoid-lists and the standalone Predictability definition pruned); skill-only mechanics disclosed to SKILL-MECHANICS.md; the skill is now model-invoked. Clean rename, no alias. Spec: mattpocock/personal-wiki#187 · ships via mattpocock/personal-wiki#193 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-23 15:29:58 +01:00
Matt PocockandClaude Opus 4.8	9c32629965	feat(prototype): logic branch produces a shareable HTML demo Reshape the logic branch from a terminal app into a single self-contained HTML file a non-developer can drive: a labelled state panel, free-play buttons, and tabbed guided walkthroughs (scenarios) with the ordered buttons to press underneath each. The portable pure-logic module still lifts into the real code; the HTML shell is the throwaway primary source. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-17 10:50:17 +01:00
Matt PocockandClaude Opus 4.8	b8fd9afa42	feat(grilling): round-by-round frontier interview Rework grilling from one-question-at-a-time to asking the whole frontier each round, with background sub-agents for fact-finding so research never blocks the round. Fold the batch-grill-me experiment into grilling and delete it. Re-sync the docs page, including how to opt back into one-at-a-time via global CLAUDE.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-16 13:12:55 +01:00