Add Task ticket type to decision-mapping skill

Some blockers are neither a decision, a prototype, nor research — just
literal manual work (moving data, signing up for a service, provisioning
access) that must happen before discussion can move forward.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

.agents/writing-docs.md

@@ -0,0 +1,57 @@
+# Writing docs pages
+
+Every promoted skill (`engineering/`, `productivity/`, `misc/`) has a human-facing **docs page** at `docs/<skill-name>.md`, published at `https://aihero.dev/skills-<skill-name>`. 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.
+
+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/<old>.md` → `docs/<new>.md`), because the published URL tracks the name.
+
+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-<name>`; 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.
+
+## 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.
+
+<page-template>
+
+```bash
+npx skills add mattpocock/skills --skill=<name>
+```
+
+[Source](https://github.com/mattpocock/skills/tree/main/skills/<bucket>/<name>)
+
+## 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.
+
+## <Substance heading>
+
+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.
+
+## <Concept highlight>
+
+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.
+
+## How it fits the workflow
+
+```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.
+
+## Pairs well with
+
+- [<sibling>](https://aihero.dev/skills-<sibling>), because-clause saying what the pairing buys
+
+</page-template>
+
+## 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.
+- Use the skill's **leading words** (_seam_, _deep module_, _tracer bullet_) so the page and the skill speak one language.
+
+## Done when
+
+- The page exists at `docs/<name>.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`.
+- Every link is absolute, and every one resolves.

.changeset/decision-mapping-task-type.md

@@ -0,0 +1,5 @@
+---
+"mattpocock-skills": minor
+---
+
+Add a fourth **Task** ticket type to the **`decision-mapping`** skill. Some blockers are neither a decision, a prototype, nor research — just literal manual work that has to happen before the discussion can move forward (moving data, signing up for a third-party service, provisioning access). The agent automates it where it can, otherwise hands the human a precise checklist, and records any resulting facts later tickets depend on.

.changeset/review-smell-baseline.md

@@ -0,0 +1,5 @@
+---
+"mattpocock-skills": patch
+---
+
+Give the in-progress **`review`** skill an always-on Fowler smell baseline on its Standards axis. A curated ~12 high-signal "Bad Smells in Code" (Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man, Refused Bequest) are inlined into `SKILL.md` as a fixed baseline alongside whatever the repo documents — not a new third axis. Two binding rules keep it safe: a documented repo standard overrides the baseline, and every smell is reported as a judgement call, never a hard violation.

CLAUDE.md

@@ -13,4 +13,8 @@ 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 `SKILL.md` is either user-invoked (`disable-model-invocation: true`, reachable only by the human) or model-invoked (model- or user-reachable). For the full definitions, description conventions, and why a user-invoked skill can invoke model-invoked skills but never another user-invoked one, see [docs/invocation.md](./docs/invocation.md).
+Every promoted skill also has a human-facing docs page at `docs/<skill-name>.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 `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).
+
+To (re)link every skill into the local harness skill directories (`~/.claude/skills`, `~/.agents/skills`), run `scripts/link-skills.sh`. Each entry is a symlink into this repo, so a `git pull` keeps installed skills current; re-run the script after adding, removing, or renaming a skill.

docs/to-prd.md

@@ -0,0 +1,47 @@
+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

scripts/link-skills.sh

@@ -1,6 +1,10 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
+# NOTE: This is a dev-only script, intended for use by maintainers of this repo.
+# It is not a supported installer. Modifications to it — or requests for
+# modifications — will not be approved.
+#
 # Links all skills in the repository into the local skill directories used by
 # each agent harness:
 #   - ~/.claude/skills  — Claude Code

skills/in-progress/decision-mapping/SKILL.md

@@ -4,7 +4,7 @@ description: Turn a loose idea into a sequenced map of investigation tickets, th
 disable-model-invocation: true
 ---
 
-This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or grilling.
+This skill is invoked when a loose idea requires more than one agent session to turn into a plan. It creates a stateful decision map in a markdown file, and drives the user through a sequence of tickets to resolve the open questions - which may require either prototyping, research or grilling. The map is domain-agnostic: it plans engineering work, course content, or anything else that fits the same shape.
 
 ## The Decision Map
 
@@ -23,7 +23,7 @@ terse enough to stay token-efficient, and unique within the map.
 
 Blocked by: <slug>, <slug>
 Status: open | in-progress | resolved
-Type: Research | Prototype | Grilling
+Type: Research | Prototype | Grilling | Task
 
 ### Question
 
@@ -44,11 +44,12 @@ Each ticket must be sized to one 100K token agent session.
 
 ## Ticket Types
 
-There are three types of tickets:
+There are four types of tickets:
 
 - **Research**: Reading documentation, third-party API's, or local resources like knowledge bases. Creates a markdown summary as an asset. Use this when knowledge outside the current working directory is required.
-- **Prototype**: Writing UI or logic code to test a hypothesis, or to explore a design space. Uses the /prototype skill. Creates a prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question.
+- **Prototype**: Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Creates the prototype as an asset. Use this when "how should it look" or "how should it behave" is the key question.
 - **Grilling**: Conversation with the agent. Uses the /grilling and /domain-modeling skills. Asks one question at a time. The default case.
+- **Task**: Literal manual work that must be done before the discussion can move forward — nothing to decide, prototype, or research. Moving data from one place to another, signing up for a third-party service, provisioning access. The agent automates it where it can; otherwise it hands the human a precise checklist to do by hand. Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
 
 ## Fog of war
 
@@ -72,7 +73,7 @@ User invokes with a path to an existing map. A ticket slug is **optional** — w
 
 1. Load the **whole map** as context.
 2. Choose the ticket. If the user named one, use it. Otherwise pick the first `open` ticket in document order that is [unblocked](#structure). [Claim it](#structure): set `Status: in-progress` and save before any work.
-3. Resolve it, invoking skills as needed. If in doubt, use `/grilling` and `/domain-modeling`.
+3. Resolve it, invoking skills as needed — including any the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
 4. Record the answer in the ticket's body and set `Status: resolved`.
 5. Add newly-discovered tickets with correct `Blocked by` edges. If the decisions made invalidate other parts of the map, update or delete those nodes.
 6. Handoff.
@@ -101,3 +102,7 @@ End every session by clearing the context and opening one or more fresh sessions
 > ```
 
 **No open tickets remain.** The fog is pushed back far enough that the path to the finish line is clear — the map is done. (The initial grilling may also surface no fog at all, in which case there was never a map to build.) Recommend implementing directly, or using `/to-prd` to schedule a multi-session implementation.
+
+## Notes
+
+An optional block declaring the **domain**, any skills every session should `consult`, and freeform standing preferences the planning surfaces.

skills/in-progress/review/SKILL.md

@@ -35,6 +35,26 @@ Look for the originating spec, in this order:
 
 Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`.
 
+On top of whatever the repo documents, the Standards axis always carries the **smell baseline** below — a fixed set of Fowler code smells (_Refactoring_, ch.3) that applies even when a repo documents nothing. Two rules bind it:
+
+- **The repo overrides.** A documented repo standard always wins; where it endorses something the baseline would flag, suppress the smell.
+- **Always a judgement call.** Each smell is a labelled heuristic ("possible Feature Envy"), never a hard violation — and, like any standard here, skip anything tooling already enforces.
+
+Each smell reads *what it is* → *how to fix*; match it against the diff:
+
+- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+
 ### 4. Spawn both sub-agents in parallel
 
 Send a single message with two `Agent` tool calls. Use the `general-purpose` subagent for both.
@@ -42,8 +62,8 @@ Send a single message with two `Agent` tool calls. Use the `general-purpose` sub
 **Standards sub-agent prompt** — include:
 
 - The full diff command and commit list.
-- The list of standards-source files you found in step 3.
-- The brief: "Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words."
+- The list of standards-source files you found in step 3, **plus the smell baseline from step 3** pasted in full — the sub-agent has no other access to it.
+- The brief: "Report — per file/hunk where relevant — (a) every place the diff violates a documented standard: cite the standard (file + the rule); and (b) any baseline smell you spot: name it and quote the hunk. Distinguish hard violations from judgement calls — documented-standard breaches can be hard, but baseline smells are always judgement calls, and a documented repo standard overrides the baseline. Skip anything tooling enforces. Under 400 words."
 
 **Spec sub-agent prompt** — include: