Cut the "(trailing name orients you; it's ignored on paste)" gloss —
a # comment is self-evident. Replace the arbitrary "Briefing pipeline"
map name and specific ticket names with <map name>/<ticket name>
placeholders, consistent with the surrounding <map-url>/<issue-url>
style so nothing reads as a real referent.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
"id stays the identity" duplicated the Tickets section's "issue id is
its identity" — single source of truth belongs there (co-located with
the wiring/blocking mechanics that depend on ids). Reword to state the
pasteable-handle exception (link target, Handoff URL) without
re-defining identity. Trim redundant rationale wording.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a "Refer by name" convention so Wayfinder surfaces maps and
tickets by their human-friendly title in everything the human reads
(narration, Decisions-so-far, Handoff) rather than bare ids, numbers,
or slugs — a wall of #42, #43, #44 is illegible; names read at a
glance. The id/URL stays the identity and pasteable handle, riding
inside the name's link.
Update the Handoff example to demonstrate it: name the map in the
header and annotate each parallel command with its ticket name.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
User-invoked skill mirroring handoff, but hands the conversation summary
to a fresh background agent via `claude --bg` instead of saving a
markdown document.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The word "branch" in the Invocation section primes git-aware agents
(Sonnet, GPT-5.5) to create git branches when running the skill,
littering established environments with per-session branches that then
have to be merged. Nothing here refers to git — the two "branches" are
the two invocation modes (chart the map / work through it). Rename to
"modes" to remove the false cue.
Fixes#418
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
State the no-duplication contract up front with a leading word: the map
indexes decisions and points at the tickets that hold them; a decision
lives in exactly one place — its ticket — so the map only gists and links.
Also close a fog-vs-ticket duplication: graduating fog into a ticket now
clears the graduated patch from the Fog.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the "one-liner" constraint — fog entries can be as loose or full as
the view allows. Point the map template's Fog comment at the Fog-of-war
section instead of restating it, and remove the duplicated "not a ticket"
now that the keep-out clause covers it.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The Fog-of-war section explained the loop but not the content. Add
explicit inclusion/exclusion guidance: dim decisions/investigations
coming but not yet specifiable, as rough one-liners — not what's already
decided (Decisions so far) or actionable now (a ticket).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Show the map body (Notes / Decisions so far / Fog) and the ticket body
(Question) as literal markdown templates instead of describing them in
prose, so a charting session reproduces the same shape every run. The
template carries the structure; surrounding prose trimmed to avoid
restating the zone list.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Single-source the frontier and fog definitions. The Tickets section owns
"frontier"; Fog-of-war owns the loop and terminal condition. Remove the
frontier re-definition and fog-nature restatement from Fog-of-war, the
duplicated frontier criteria from the work sequence, the repeated "way to
the goal is clear" from the intro, the "low resolution" restatement, and
the clear-context prose that its own example already shows.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Drop the "shared artifact, not a private file" sentence and the "one URL
the whole team reads" restatement (no-ops the agent obeys by default).
Fold Chart step 4 into step 3 — "don't chart what you can't see" already
lives in the Fog of war section (single source of truth).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Move the map off a local Markdown file and onto the repo's configured
issue tracker. The map is a single wayfinder:map issue whose tickets are
its child issues — one shared URL the team can watch and comment on.
Blocking, claiming (wayfinder:claimed), and the frontier query use native
tracker semantics; a session loads the map at low resolution (Notes +
per-closed-ticket context pointers + Fog prose) and zooms into tickets on
demand. Per-tracker mechanics live behind the docs/agents/issue-tracker.md
pointer, so setup-matt-pocock-skills seeds a "Wayfinding operations"
section for GitHub, GitLab, and local-markdown; absent that doc, Wayfinder
defaults to local-markdown.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the "You are the Wayfinder" second-person persona from the intro,
description, and README so the agent doesn't adopt a persona. Keep the
leading-word frame (chart / fog / frontier / map); wayfinder stays only as
the skill/invocation name.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The persona is the Wayfinder; the invocation should match. Rename the
folder and skill name to wayfinder and update the invocation examples,
README link, and changeset. "wayfinding" stays only as the activity noun.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Reframe the planning skill around the Wayfinder persona — chart a route
through a foggy problem, resolving tickets one at a time until the way to
the goal is clear. "Decision map" was jargony and inaccurate (only 1 of 4
ticket types is a decision).
Rename the folder and skill name, rewrite the description and framing, and
prune: unify node->ticket, bind "frontier" to the unblocked set, drop the
duplicated "one question at a time" (owned by /grilling), trim intro no-ops.
Co-Authored-By: Claude Opus 4.8 <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>
misc/ skills are no longer installable via the plugin or listed in the
top-level README — they join personal/ as kept-but-unshipped. Only
engineering/ and productivity/ are promoted now.
- Drop the Misc section from the top-level README.
- Reclassify misc/ as non-promoted in CLAUDE.md (README/plugin rule,
bucket-README grouping rule, docs-page rule) and the writing-docs guide.
- Note the non-promoted status in the misc bucket README.
plugin.json already omitted misc, so no manifest change was needed.
No SKILL.md context pointer referenced a misc skill, so nothing else
had to move.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
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>
- Revert Sketch back to Prototype to mesh with the /prototype skill and
existing vocabulary, keeping the generalized function-first definition.
- Move the `## Notes` block from the top of the map to the end.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Decouple the skill from engineering so it plans any domain (e.g. course
content) without specializing toward it. Domain specifics live in the map,
not the skill body.
- Add an optional `## Notes` block to the map: declares the domain + skills
to consult, plus freeform standing preferences. Loaded into every session,
honored by every session, accrues as it emerges.
- Rename the Prototype ticket type to Sketch and define it by function —
raise the fidelity of the discussion with a cheap concrete artifact to
react to (/prototype is one medium among outline/rough-take/stub).
- Note that validation is the thread through all three types, not a type.
- Resolve step now consults skills named in Notes.
The session machinery (one ticket per session, claiming, parallelism,
handoff) is unchanged — it follows from the AI agent's smart/dumb zones, not
the domain.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Each smell now reads what-it-is → how-to-fix, telegraphic style — the fix
is the actionable half a reviewer needs, kept to a clause.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Folds Refactoring ch.3 "Bad Smells in Code" into the in-progress `review`
skill. The skill stays two-axis: smells layer into the Standards axis as a
fixed, always-on baseline alongside a repo's documented standards, rather
than a third axis.
Because the baseline is needed on every run it lives inline in SKILL.md.
Each smell is one line — its name carries the definition (the names are
strong leading words) plus a diff-specific cue. Curated to ~12 high-signal
smells; vague ones (Comments, Loops) and tooling-caught ones (Long
Parameter List) are deliberately dropped.
Two rules bind the baseline: a documented repo standard always overrides
it, and every smell is reported as a judgement call, never a hard
violation. The Standards sub-agent prompt now carries the baseline and
these rules.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Refactoring belongs to the review stage, not the implementation loop.
Remove the refactor rule and the now-orphaned refactoring.md (its home is
the review skill), and point the loop's rule at the review skill so it
isn't re-added.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The red → green → refactor loop is anchored by leading words the model
already holds, so the step-by-step Workflow mostly restated the loop and
duplicated the horizontal-slicing anti-pattern. Drop the Workflow and
per-cycle checklist; fold their durable idea (vertical slices / tracer
bullets) into Anti-patterns and a short Rules-of-the-loop list.
Introduce **seam** as the leading word for where tests go, collapsing the
old Philosophy "public interfaces" prose and the Planning "confirm
interface / behaviors" handshake into one rule: test only at pre-agreed
seams, confirmed with the user before any test is written.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tests whose assertion is recomputed the way the code computes it pass by
construction and give zero confidence. Add it as a peer of the existing
implementation-coupling anti-pattern: a Philosophy principle, a per-cycle
checklist gate, and a BAD/GOOD example pair in tests.md. Includes a patch
changeset.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Replace numeric ticket ids (#1, #2…) with short, token-efficient
dash-case slugs (e.g. relational-db) that read as mini-titles. Update
the Structure example, the next-ticket selection rule (lowest-numbered →
first in document order), the optional-arg wording, and the Handoff
copy-paste examples accordingly.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
