Compare commits

..
14 Commits
Author SHA1 Message Date
Matt PocockandClaude Opus 4.8 d6e21b661d docs: list implement in the README's engineering user-invoked skills
implement is the central Main Flow step but was missing from the
public Reference list. Add it after to-tickets.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 0557d57579 docs: settle wayfinder as a situational on-ramp, not the main entry flow
The grill-led idea→ship chain stays the documented front door; wayfinder
is a situational on-ramp (greenfield / huge feature build), reserving
"new default spine" for a potential v2.

- ask-matt router: name wayfinder's concrete triggers
- grill-me / grill-with-docs: signpost up to wayfinder as the
  too-big-for-one-session on-ramp

Resolves the main-flow decision on the Skills v1.1 wayfinder map (#120).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 639df6e738 Graduate wayfinder to engineering; unify changesets for v1.1
Graduate `wayfinder` out of in-progress into the engineering bucket
(plugin.json, top-level + Engineering READMEs under User-invoked, docs
page, ask-matt on-ramp, disable-model-invocation).

Consolidate the 22 pending changesets into 10 coherent v1.1 entries:
one `wayfinder` (rename from decision-mapping + full reframe +
graduation), one `grilling`, one `code-review`, one `tdd`; fold the
superseded to-issues changeset into unify-to-tickets and drop its stray
`</content>` tag. Highest bump is minor → 1.0.1 becomes 1.1.0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 d29732e49f refactor(to-tickets): cut the two-readings explainer from SKILL.md
It documented what the skill does rather than steering the agent — the
publish mechanics it described are already Step 5's instructions, and the
conceptual framing already lives in ask-matt and the docs page.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 09a72ba465 refactor(to-tickets): prune no-ops from the two-readings intro
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 386d4ff719 refactor: unify planning skills into /to-spec + /to-tickets
Executes the `unify-to-tickets` decision (personal-wiki #23), reworking
this PR from "add /to-plan" into the full planning-skills unification.

- Rename /to-prd → /to-spec. "spec" is now the single through-line term
  (the skill still opens with "you may know this document as a PRD" for
  discoverability).
- Merge /to-plan + /to-issues into one /to-tickets skill; delete
  /to-issues. /to-tickets emits a set of tickets, each declaring its
  blocking edges — one medium-agnostic artifact that reads as a
  sequential plan (local `tickets.md`, edges as text) or a parallelizable
  DAG (real tracker, native blocking links). The edges live in the ticket
  either way; the medium only decides whether anything acts on them in
  parallel.
- ask-matt now routes idea → /to-spec → /to-tickets → /implement.
- Sweep every cross-reference (docs pages, chain diagrams, CONTEXT.md,
  ADRs, .agents, setup templates) to the new names and vocabulary.
- Rewrite the changeset to describe the unification.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:18:36 +01:00
Matt PocockandClaude Opus 4.8 c5a4a8c2e9 refactor(to-plan,to-issues): prune no-ops in vertical-slice framing
Fold the redundant 'thin vertical slice cuts through all layers, NOT
horizontal' intro sentence into vertical-slice-rules bullet 1 (it was
duplicating the bullet), and cut to-plan's 'no parallelism / top-to-bottom'
restatement — 'sequential' is already anchored as the leading word. Keeps
the shared core identical across the two sibling skills.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:13:21 +01:00
Matt PocockandClaude Opus 4.8 93f73198e3 feat(to-plan): add sequential plan skill
Add a user-invoked `to-plan` skill — the sequential, HITL sibling of
`to-issues`. Both slice work into tracer-bullet vertical slices, but
`to-plan` produces one ordered sequence you drive by hand, one phase per
fresh context, rather than parallel independently-grabbable issues.

It publishes to the tracker `/setup-matt-pocock-skills` configured, shaped
to it: a single sequential `plan.md` for a local tracker, or a parent
issue with ordered sub-issues (native sub-issues where supported) for a
real one.

Registers the skill everywhere CLAUDE.md requires (plugin.json, top-level
and bucket READMEs, docs page), updates the `ask-matt` router's main-flow
fork to offer both to-issues and to-plan, and adds a changeset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 14:11:05 +01:00
Matt PocockandGitHub 896f14d9c2 Merge pull request #472 from mattpocock/fix/wayfinder-tracker-indirection
fix(wayfinder): resolve issue-tracker doc via the CLAUDE.md pointer, not a hardcoded path
2026-07-08 11:18:12 +01:00
Matt PocockandClaude Opus 4.8 d869d45afc fix(wayfinder): resolve issue-tracker doc via the CLAUDE.md pointer, not a hardcoded path
Wayfinder pinned the literal docs/agents/issue-tracker.md, breaking the
indirection to-issues/to-prd/triage rely on: they resolve the tracker
through the ### Issue tracker block setup writes into CLAUDE.md / AGENTS.md.
In repos that keep agent docs elsewhere, wayfinder silently fell back to
local-markdown. It now follows the same pointer and reads the doc's
"Wayfinding operations" section by name.

Closes #471

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-08 11:17:29 +01:00
Matt PocockandGitHub 8515a080a7 Merge pull request #469 from mattpocock/to-issues/wide-refactor-expand-contract
to-issues: slice wide refactors by expand–contract
2026-07-07 16:37:10 +01:00
Matt PocockandClaude Opus 4.8 f219e66379 to-issues: wrap issue template in XML tags
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 16:35:57 +01:00
Matt PocockandClaude Opus 4.8 aa591116bf to-issues: split into Process + Reference tiers
Revert the description change and keep the wide-refactor material in
one place. Reshape the skill into a lean Process (steps) and a
Reference section holding the vertical-slice rules, the wide-refactor
expand–contract rules, and the issue body template as co-located
blocks the steps point to.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 16:35:39 +01:00
Matt PocockandClaude Opus 4.8 a0329ba957 to-issues: slice wide refactors by expand–contract
Add a wide-refactor exception to the tracer-bullet rule: a single
mechanical change whose blast radius fans across the codebase can't
land as one green vertical slice. Seed "wide refactor" / "blast radius"
across the description, the explore step (detection), and the drafting
step (strategy), and give the expand–contract sequence in prose.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-07 16:32:47 +01:00
6 changed files with 20 additions and 1 deletions
+5
View File
@@ -0,0 +1,5 @@
---
"mattpocock-skills": minor
---
Split the **`to-issues`** skill into a lean **Process** and a **Reference** section, and teach it to handle a **wide refactor** — a single mechanical change (like renaming a column) whose **blast radius** fans across the whole codebase, breaking thousands of call sites at once so no vertical slice can land green. The drafting step now points at two co-located reference blocks: the **Vertical slice rules** for ordinary tracer bullets, and **Wide refactors**, which slices the change by **expandcontract** (expand the new form beside the old, migrate call sites in batches sized by blast radius, then contract the old form away) so CI stays green batch to batch — or, when it can't, only at a final integrate-and-verify issue. The issue body template moves into Reference too.
@@ -0,0 +1,7 @@
---
"mattpocock-skills": patch
---
Fix **`wayfinder`** hardcoding the issue-tracker doc path, which broke the indirection the rest of the suite relies on.
`to-issues`, `to-prd`, and `triage` never name a path — they resolve the tracker through the `### Issue tracker` block that `setup-matt-pocock-skills` writes into `CLAUDE.md` / `AGENTS.md`, which points at the tracker doc wherever it lives. Wayfinder instead pinned the literal `docs/agents/issue-tracker.md`, so in a repo that keeps its agent docs elsewhere it silently fell back to the local-markdown tracker — even one whose `CLAUDE.md` clearly declares GitHub issues. It now resolves the doc via that same pointer and reads its "Wayfinding operations" section by name, keeping the indirection consistent across the suite.
+1
View File
@@ -156,6 +156,7 @@ Skills I use daily for code work.
- **[setup-matt-pocock-skills](./skills/engineering/setup-matt-pocock-skills/SKILL.md)** — Configure this repo for the engineering skills (issue tracker, triage labels, domain doc layout). Run once per repo before using the other engineering skills.
- **[to-spec](./skills/engineering/to-spec/SKILL.md)** — Turn the current conversation into a spec and publish it to the issue tracker. No interview — just synthesizes what you've already discussed.
- **[to-tickets](./skills/engineering/to-tickets/SKILL.md)** — Break any plan, spec, or conversation into a set of tracer-bullet tickets, each declaring its blocking edges — written as text in a local file, or as native blocking links on a real tracker.
- **[implement](./skills/engineering/implement/SKILL.md)** — Build the work described by a spec or set of tickets, driving `/tdd` at pre-agreed seams and closing out with `/code-review` before committing.
- **[wayfinder](./skills/engineering/wayfinder/SKILL.md)** — Plan a huge chunk of work, more than one agent session can hold, as a shared map of investigation tickets on the issue tracker — resolve them one at a time until the way to the destination is clear.
**Model-invoked**
+4
View File
@@ -41,6 +41,10 @@ The whole skill turns on one distinction. A **horizontal** slice ships one layer
Before slicing, `to-tickets` looks for prefactoring — "make the change easy, then make the easy change" — and orders that work first. It then quizzes you on the breakdown (granularity, blocking edges, what to merge or split) before publishing anything, and publishes blockers first so each ticket's "Blocked by" can reference a real ticket.
## The wide-refactor exception
One shape breaks the tracer-bullet rule: a **wide refactor** — a single mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so one edit breaks thousands of call sites at once and no vertical slice can land green. `to-tickets` slices it as **expandcontract** instead: expand (add the new form beside the old so nothing breaks), migrate (move call sites over in batches sized by blast radius, one ticket per batch, CI green throughout because the old form still exists), then contract (delete the old form once no caller remains). When even the batches can't stay green alone, they share an integration branch that all block a final integrate-and-verify ticket, and green is promised only there.
## Where it fits
`to-tickets` is a step in the main build chain:
+2
View File
@@ -37,6 +37,8 @@ Break the work into **tracer bullet** tickets.
Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expandcontract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
### 4. Quiz the user
Present the proposed breakdown as a numbered list. For each ticket, show:
+1 -1
View File
@@ -22,7 +22,7 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** Consult `docs/agents/issue-tracker.md` (the "Wayfinding operations" section) for how _this_ repo expresses them. If that doc is absent, default to the local-markdown tracker.
**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
### The map body