Not "implement directly" — the point is the journey fits one session and
doesn't justify a map. Stop and ask the user how to proceed.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Bring back the "skip the map when there's no fog" branch that was
collateral-deleted with the Handoff section. Co-located in Chart the
map step 2, where the fog/no-fog outcome is determined: if breadth-first
grilling surfaces no fog, offer to skip the map and implement directly.
The offer (ask, don't auto-skip) is preserved from the original.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two minimal edits to the to-issues skill:
- The "What to build" template now points explicitly at the `/prototype`
skill's code as the source of an inlined decision snippet, rather than
gesturing at "a prototype".
- Publishing now prefers the tracker's native sub-issues (parent → slice)
and native blocking edges (Blocked by) where supported — mechanics
already documented in the issue-tracker doc — keeping the `## Parent`
and `## Blocked by` body sections as the fallback.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Out of scope section: drop embedded 'however sharply you can see it'
duplicate; the 'Scope, not sharpness, lands it here' punchline carries
the claim once.
- Work-through step 5: delegate close+one-line mechanics to the Out of
scope section via the 'rule it out of scope' leading phrase instead of
restating them.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
QA follow-up: the Fog of war section was teaching both concepts, which
muddies the leading word — fog should point only *toward* the
destination. Now Fog of war teaches only the not-yet-specified bucket
(with the two-way fog-or-ticket sharpness test restored), and a new
Out of scope section owns the scope axis: beyond the destination,
closed not graduating, kept out of Decisions so far.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Following review: the map-body headings a cold reader sees should be
self-evident without having read the skill, so drop the metaphor from
the headings — `## Not yet specified` (in-scope, unripe) and
`## Out of scope` (beyond the destination). Keep **fog of war** as the
leading word: it still titles the explanatory section and drives the
"clears the fog" / "graduate the fog" behavior in the prose.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fog is the undiscovered frontier *toward* the destination — in scope,
just not yet sharp — so it graduates into tickets as the frontier
advances. Work ruled out of *this* effort's scope was being parked in
Fog too, where it read as takeable frontier (an unblocked, unclaimed
ticket is indistinguishable from a live one).
Add a dedicated `## Deferred` section for beyond-the-destination work:
it never graduates (the frontier stops at the destination) and returns
only as a fresh effort if the destination is redrawn. The "Fog or
ticket?" test becomes "Fog, ticket, or deferred?", gated on scope as
well as sharpness, and both charting and working-the-map now defer a
mis-scoped ticket (close it, one line in Deferred) rather than leaving
it on the frontier or logging it in Decisions so far.
Builds on #455 (destination as the leading word / destination fixes
scope).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wayfinding finds the way to a destination rather than building it. The
destination varies per effort and is named first, since it shapes every
ticket. Adds a Destination map-body field, makes it triage step 1, and
unifies the stray "goal" mentions onto "destination".
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A session now claims a ticket by assigning it to the dev driving the
map, rather than setting a `wayfinder:claimed` label. The assignee is
the claim; an open, unassigned ticket is unclaimed. Reads more naturally
in the tracker's own UI and frees the label vocabulary to
`wayfinder:<type>` alone.
Updates the GitHub and GitLab tracker-operations docs to the assignee
mechanism (`--add-assignee @me` / `--assignee @me`). The local-markdown
tracker keeps its `Status: claimed` line — a file store has no assignee.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Concision pass on the blocking rule (fold the "wherever the tracker has
one" clause into the fallback sentence; drop restatements). Bring the
GitHub and GitLab issue-tracker templates up to the same standard: the
GitHub template now carries the native issue-dependencies recipe and
frontier query; the GitLab template names the native /blocked_by link
(Premium/Ultimate) with the body-convention fallback.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The blocking rule now leads with the tracker's native dependency
relationship and encodes the rationale: native rendering makes the
frontier visible in the tracker's own UI, so the human sees what's
takeable without opening the map. Notes the body-convention fallback
for trackers that lack native blocking (GitHub has it; GitLab only on
paid tiers).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The tdd skill pointed at a `review` skill that no longer exists; the
review skill is now named `code-review`. Update the reference.
Fixes#432
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>
The description does the skill's invocation work, so lead with the trigger
that actually reaches for Wayfinder — a huge chunk of work, more than one
agent session can hold — instead of the softer "chart a route through a
foggy problem". Skill body and fog-of-war mechanic unchanged.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Every session ended with a Handoff that queried the frontier and emitted
per-ticket copy-paste commands — real token cost each session. Cut it
entirely and let the natural flow carry continuation: the next
/wayfinder session already loads the map and picks the next frontier
ticket, so nothing is lost, just deferred to re-invocation.
Reconciles the references left behind: the one-ticket-per-session rule
and "charting is one session's work" constraint survive as plain lines;
the Refer-by-name paragraph drops its Handoff mentions.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
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>
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>
