Align the remaining callers and docs pages with grilling's body, which now
says "decision tree".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Research stays a real ticket type — it's a shared blocker downstream
decisions hang on, which the frontier's blocking edges exist to render.
What changes is resolution: because research is AFK, charting doesn't
stop and read. After creating the tickets, the charting session fires a
/research subagent for each research ticket to burn it down in parallel,
capturing findings on a throwaway research/<name> branch with a context
pointer.
Charting's "fire the research subagents" step owns how research is
handled; the Ticket Types bullet just names the resolver, and the
one-ticket-per-session rule carries the research exception.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Before scanning, decide where to look. If the user named a direction, take
it; otherwise read the last ~20 commit messages to bias exploration toward
actively-developed paths. A deepening opportunity in code nobody touches is a
refactor you'll never cash in — leverage only pays off where you keep editing.
Syncs the docs page and adds a changeset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
People kept reading a wayfinder ticket as an ordinary implementation
ticket — a slice of a build to execute — when wayfinder uses them as
decision tickets: questions whose resolution is a decision.
Introduce "decision ticket" as a light leading word: the skill
description and its opening line name it (and say what makes it one),
and the ask-matt / engineering README blurbs and the docs page match,
while "ticket" stays the everyday word once the term is established.
Record "Decision ticket" in CONTEXT.md so the "avoid: ticket" domain
rule no longer contradicts wayfinder's deliberate use of the word.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The final line of to-tickets/SKILL.md carried a stray `</content>`
closing tag with no matching opening tag — a packaging/serialization
artifact from the planning-skills refactor (386d4ff), not valid skill
content. The same stray tag had leaked into the generated landing
docs for to-tickets and to-spec. Strip it from all three.
Fixes#495
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reframe the artifact handling as capturing the prototype somewhere out
of main — a throwaway branch — with a context pointer to it left on the
implementation issue, instead of "disposing" of it. The main branch
still keeps only the validated decision.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rework /setup-matt-pocock-skills to ask fewer, friendlier questions and
align the local-markdown issue tracker with the current spec.
- Triage labels: asked only when the `triage` skill is installed, and then
as a single recommended-yes question ("keep the default triage labels?")
instead of an override interrogation. When triage isn't installed, the
section and docs/agents/triage-labels.md are skipped.
- External PRs as a request surface: no longer a setup question. The
GitHub/GitLab templates still carry the flag, defaulted off; flip it in
docs/agents/issue-tracker.md later.
- Domain docs: default to single-context without asking; multi-context is
only offered when the repo shows monorepo signals.
- Local-markdown tickets: one file per ticket under
.scratch/<feature>/issues/<NN>-<slug>.md, never a single combined
tickets.md. /to-tickets, ask-matt, and the local template now agree, and
the spec file is spec.md (not PRD.md) to match /to-spec.
- Re-sync docs pages for setup-matt-pocock-skills and to-tickets; changeset.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the secondary-source label — the actionable distinction is just
that the prototype is a primary source to retain on a throwaway branch.
Collapse the re-descriptions in LOGIC/UI so they point to SKILL for the
disposal concept and add only branch-specific nuance.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Retain the prototype as a primary source on a throwaway branch linked
from the relevant issue, rather than deleting it, while the distilled
answer remains the secondary source. Keeps prototype scaffolding out of
the main branch without destroying the runnable evidence.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
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>
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>
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>
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>
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>
Add a hard stop so the agent won't enact the plan until the user
confirms shared understanding is reached. Recruit the pretrained
"grill" leading word in the description, and re-sync the docs page
with the new gate behaviour.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A small, model-invoked skill that spins up a background agent to
investigate a question against high-trust primary sources, then leaves a
single cited Markdown file wherever the repo keeps such notes.
Wires it into the plugin set, both READMEs (Model-invoked), a docs page,
and the ask-matt router, per the repo's promoted-skill conventions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Ask Matt was missing five skills that now exist and are user-reachable:
tdd (the red-green engine implement drives), diagnosing-bugs (there was
no route for "something's broken"), domain-modeling and codebase-design
(the two vocabulary references), and grilling (the shared primitive).
- SKILL.md: add a "Something's broken" on-ramp for diagnosing-bugs, a
"Vocabulary underneath" section for domain-modeling/codebase-design,
weave tdd into the main flow, flesh out prototype, broaden the
description from "user-invoked skills" to "the skills".
- docs/engineering/ask-matt.md: re-sync the framing to match.
- CLAUDE.md: add a maintenance rule so any future skill change triggers
an Ask Matt re-check, beside the existing docs-page re-sync rule.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The build chain now ends at code-review. Update every flow doc that draws
the chain so it reads end-to-end:
grill-with-docs → to-prd → to-issues → implement → code-review
- grill-with-docs / to-prd / to-issues: extend the diagram; point the
downstream neighbour at implement (which drives tdd internally).
- tdd: reframe from "final step" to the engine inside implement's step.
- implement: extend the diagram to include the review pass.
- ask-matt: narrate the flow ending in review (docs) and note that
/implement closes out with /code-review (SKILL.md).
- writing-docs guide: refresh the example chain.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rename the in-progress `review` skill to `code-review` and move it from
`skills/in-progress/` into the promoted `skills/engineering/` bucket.
- Add it to `.claude-plugin/plugin.json` and the Model-invoked sections of
the top-level and Engineering READMEs; drop it from the in-progress README.
- Add a docs page at `docs/engineering/code-review.md`.
- Point `/implement` and its docs at `/code-review`.
- Update the smell-baseline changeset reference; add a changeset for the move.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The canonical build chain is grill-with-docs → to-prd → to-issues →
implement, with tdd as the red-green loop implement drives internally
rather than a chain step of its own.
- Update the chain diagram on grill-with-docs, to-prd, to-issues, and tdd.
- Reframe tdd's "Where it fits": it's the engine inside the implement
step, still independently reachable, no longer the terminal.
- Point to-prd and to-issues at implement as the thing that builds the
tickets, giving implement the inbound links it previously lacked.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
misc/ skills are niche — they stay promoted (README + plugin manifest,
so they're installable) but no longer get a public aihero.dev docs
page. Remove the four misc pages and decouple the docs rule from the
promotion rule in CLAUDE.md and the writing-docs guide.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The repeated "The load-bearing constraint:" opener on every page read
as an agent tell. Strip the label across all skill pages and let the
constraint stand as a plain declarative sentence; update the
writing-docs template so it isn't regenerated.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
codebase-design, domain-modeling and grilling are pulled out as
standalone, model-invoked skills precisely so other skills can point
at them and so you can reach them as a reference independently of the
steps any wrapper mandates. Add a "Pulled out on purpose" section to
each that names who leans on it and why it stands alone, and slim the
overlapping "Where it fits" prose to avoid duplication.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds a docs page for every promoted skill that lacked one, following
.agents/writing-docs.md and using docs/engineering/to-prd.md as the
worked exemplar. Covers all of engineering/ (bar to-prd, already done),
productivity/, and misc/.
Each page states its load-bearing constraint, its invocation mode and
trigger boundary, surfaces the skill's leading word, and routes back to
ask-matt so the set forms a connected router with no dead ends.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Replace the inline "watch for the leading words" line with an
optional `## It's working if` section — a short list of observable
signals the skill is doing its job. Keeps observability from being
hammered onto leading words specifically.
- Build out to-prd's "What the PRD includes" with proper casing and a
one-line explainer per section.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reframe docs pages around cognitive-load relief: most skills are
user-invoked, so the human is the index that must remember when to
reach for each one. Each page's job is to make one skill memorable
and situate it in the system.
Template changes (.agents/writing-docs.md):
- Quickstart block: install + `npx skills update`, install-first
- New `## When to reach for it` (invocation mode + trigger boundary)
- New optional `## Prerequisites` (workspace/state, prior setup, tooling)
- Free-form middle with one firm rule: surface the leading word
(also an observability signal in the agent's output)
- `## Where it fits`: role-based, absorbs "Pairs well with", links ask-matt
- No H1; every cross-link absolute
Nest docs under bucket folders (docs/<bucket>/<name>.md); the
published URL stays skills-<name> regardless. Re-sync to-prd as the
worked exemplar.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Relocate this repo's ADRs and invocation.md from docs/ to .agents/,
and update the CLAUDE.md reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Introduced a human-in-the-loop script for bug diagnosis to capture user feedback.
- Created ADR and CONTEXT formats to standardize architectural decision records and domain context documentation.
- Developed a domain modeling skill to refine terminology and maintain a shared language.
- Enhanced the improve-codebase-architecture skill to provide visual reports and deepening opportunities.
- Consolidated grilling and handoff skills for better user interaction and documentation.
- Updated existing skills to improve clarity and consistency in descriptions and functionality.
Engineering skills no longer hard-code GitHub or specific label strings.
A new setup skill scaffolds an `## Agent skills` block in
AGENTS.md/CLAUDE.md plus `docs/agents/` so each repo can declare its own
backlog backend, triage label vocabulary, and domain doc layout. Skills
that need the mapping (to-issues, to-prd, triage) point at the setup
skill; skills that only soften with it (diagnose, tdd,
improve-codebase-architecture, zoom-out) stay vague. ADR-0001 records
the split.
Closes#88, #89.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
