Wire up a remote before writing a hosted tracker (#1201), offer to git mv
legacy CONTEXT.md (#1176), comment-then-close (#873), read PR body (#1138),
Blocking in Conventions with native gh flags (#855), name the open-blocker
read (#1118), GitLab -O json and frontier command (#1143).
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* teach: anchor workspace paths to the workspace root
SKILL.md used `./` both for its bundled format docs and for workspace
paths (lessons/, reference/, learning-records/, assets/), so agents
resolved the workspace paths against the skill folder and wrote courses
into ~/.claude/skills. Name the workspace root once, drop the bare `./`
from workspace paths, and re-sync the docs page.
Closes#377.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(teach): trim #377 fix to a one-line workspace-root rule
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* teach: vary the correct quiz answer's position
Closes#611.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
* wayfinder: no triage labels, no placeholder refs, no research PRs
Three things wayfinder published to the tracker went wrong in real
sessions:
- Maps and tickets picked up a triage-state label (ready-for-agent),
which reads as "ready to implement" (#518).
- Drafted tickets numbered T1-T8 were cross-referenced as #1-#8 in
published bodies, auto-linking to old unrelated issues (#507).
- Research subagents opened a draft PR from their throwaway
research/<name> branch (#576).
Say each rule where the step happens. The research docs page drops the
#576 known-problem note.
Closes#518Closes#507Closes#576
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* changeset: credit the wayfinder issue reporters
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* wayfinder: tighten #518/#507/#576 fix wording
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* wayfinder: resolve each ticket as its label's type (#625)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
implement still said "use /tdd" and "use /code-review", the bare
/skill-style prose that #878 replaced everywhere else with an explicit
Skill tool call (the convention in .agents/invocation.md). Both targets
are model-invoked, so the call is allowed.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
to-tickets said only "use the native sub-issue relationship", and the
GitHub tracker template never gave a command for it, so tickets cut from
a spec issue landed as top-level issues. The template now carries a
concrete sub-issue operation (gh issue create --parent / gh issue edit
--add-sub-issue, with a gh api fallback), referenced by wayfinder's child
ticket step; GitLab gets its Part-of equivalent. to-tickets attaches
each ticket to its source issue.
The issue template's "Blocked by" section is now omitted when blockers
were set as native edges, so they are no longer recorded twice (raised
on #262).
Fixes#554.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
SKILL.md only said to save to the OS temp directory, so agents took several attempts on Windows and wrote to a different place on each run on macOS. Reuse improve-codebase-architecture's wording ($TMPDIR, falling back to /tmp or %TEMP%) and tell the user the absolute path. Re-sync the docs page.
Closes#272.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The GitHub tracker template asked `gh pr list --json` for
authorAssociation, which gh does not expose, so the command always
failed. List open PRs with `gh api repos/{owner}/{repo}/pulls` instead
and drop OWNER/MEMBER/COLLABORATOR rather than allow-listing
first-contribution values, so FIRST_TIMER authors are kept.
Fixes#468.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- SCOPE.md: the two-part bar (observed failure + fits the philosophy),
frozen misc/, no new skills, links to every .out-of-scope file
- .out-of-scope: native-question-tool, harness-name-collisions,
new-skills, frozen-misc-skills; tracker rule now names GitHub, GitLab
and local markdown explicitly and rejects Jira (#258, #1137)
- docs/agents/triage-labels.md + Agent skills block in CLAUDE.md
- .github/ISSUE_TEMPLATE: bug and idea forms, blank issues off,
questions routed to Discussions
- README + install block: plugin updates lag the official marketplace
pin; add a "stuck on an old version?" escape hatch
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Apply the unslop rules (cursor/plugins pstack) to all 28 pages under docs/.
Headings, links, leading words and dictionary links are unchanged.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
diagnosing-bugs' Phase 6 post-mortem (the hand-off to
improve-codebase-architecture) was removed in 1dab982, but ask-matt and
the diagnosing-bugs docs page still described it. Point ask-matt at
/retro for "what would have prevented this bug?" instead, and keep the
post-mortem out of the skill itself.
Fixes#1117.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Conflicts in improve-codebase-architecture and writing-for-agents docs
kept this branch's retro wording, with CONTEXT.md renamed. Also carries
the rename into pr (graduated here) and the unreleased wait-what
changeset, and drops the rename changeset's em-dashes.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
ask-matt routes /retro as step 4 of the main flow instead of under
codebase health. Chain diagrams across the docs gain '→ retro', and
neighbouring pages (code-review, to-tickets, writing-for-agents,
improve-codebase-architecture, implement, pr) now name retro, pr and
implement-spec where they connect.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Add implement-spec as the parallel alternative to per-ticket implement,
pr as the PR-body close-out, and retro under codebase health. Re-sync the
docs page: drop the removed merge-conflict standalone and fix the
user-invoked count.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
No longer needed. Drop the skill, its docs page, and its entries in the
READMEs, plugin.json and ask-matt.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The prior commit renamed only this repo's own root glossary. This
commit does the thing actually asked for: repoint every skill and doc
that reads/writes the domain-doc convention in consumer repos —
domain-modeling, grill-with-docs, improve-codebase-architecture,
setup-matt-pocock-skills, triage, tdd, diagnosing-bugs, ask-matt,
codebase-design, wait-what — plus their docs pages, .agents/ notes,
and the top-level README. CONTEXT-FORMAT.md is renamed to
GLOSSARY-FORMAT.md alongside it.
Left untouched on purpose: CHANGELOG.md and the one still-unreleased
CONTEXT.md-era changeset, both historical records of what shipped
under the old name; and the README's pinned course-video-manager
link, which points at a real file that is still literally named
CONTEXT.md at that commit in another repo.
Co-Authored-By: Claude <noreply@anthropic.com>
Rebasing onto main picked up PR #904's new sentence in docs/productivity/wait-what.md,
which used an em-dash. Rewrote it with parentheses per the no-em-dash rule in CLAUDE.md.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Every em-dash across docs, skill files, scripts, and JSON/YAML metadata
was rewritten by hand (commas, colons, periods, parentheses, conjunctions)
rather than mechanically substituted, so sentences still read naturally.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The skill only knew to reach for a root CONTEXT.md, so it went silent
on multi-context repos that index their contexts through
CONTEXT-MAP.md instead.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The catalog row now reads "Align on an idea before committing to it."
The page's opening carried the same metaphor — "until it has real
decisions in it" — so it now says "until you can commit to it".
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Telling the agent not to give minutes, in a template that has no
minutes, pays load to say nothing — and naming the banned behaviour
makes it more available, not less. The absence does the work.
- SKILL.md: drop the "never give a time estimate" paragraph and the
"stage takes no duration" note; the example stage already shows it.
- template.sh: drop the two comments about not printing minutes.
- docs: drop the sentence about there being no estimate.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The wizard always told the human how many minutes the procedure would
take and how many were left. The number was invented at authoring time
and never true, so it is gone.
- template.sh: drop TOTAL_MINUTES and _MINUTES_ELAPSED, the "about N
minutes" banner line, and the "(~N min left)" stage suffix. stage()
takes a name only; progress is a stage count.
- SKILL.md: state the rule — no minutes in the script, in stage
headers, or in what the agent tells the user.
- docs: the Stages section counts stages, not minutes.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The docs pages carried 36 attributed opinions — "Matt's own answer",
"his position is", quoted replies from the author. A page is a
technical document about a skill, so the substance of each finding
stays and the attribution goes: "the fix is a direct instruction: …",
"the split comes down to session count".
Quotes from *users* stay, anonymous as they already were — those are
evidence about the skill in the wild rather than the author's view.
Records the rule in .agents/writing-docs.md so new pages don't
reintroduce it.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every docs page now links the first occurrence of each AI Coding
Dictionary term to its entry on aihero.dev. 202 links across 25 pages,
one link per term per page. Prose is unchanged — only links added.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The intro spent a paragraph arguing when not to use the skill. Replace it
with what the skill actually is: the agent writes the script, you run it.
Cut the agent-browser question and the closing guard for the same reason,
and plain up the densest sentences.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The agent can now reach for wizard the moment it hits a step only a
human can perform, instead of writing numbered instructions into the
chat. Typing /wizard is unaffected — model-invocation only adds the
agent's reach.
The description is rewritten as the pointer that decides when it fires:
a short statement of the artifact, four trigger branches, and an
explicit non-trigger for steps the agent can perform itself.
Behaviour is unchanged — same name, same template.sh, same four process
steps, same stage-list confirmation, which now doubles as the proposal
when the agent fires it mid-build.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ask-matt is written last, against the final state of the other 21 pages.
It stays a node rather than redrawing the graph the skill itself holds.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Coherence pass over the rewritten docs set. The recurring defect was a
refactor whose removals landed and whose replacements did not.
- tdd: restore the pointer to /codebase-design that the v1.0 changelog
and ask-matt both claim exists. The inline deep-module notes were
deleted then; nothing replaced them.
- ask-matt: /grilling and /resolving-merge-conflicts were missing from
the router entirely. Split grill-me from grill-with-docs on the
working directory rather than on whether the subject is code.
- READMEs: wayfinder maps decision tickets, not investigation tickets;
the diagnosing-bugs loop starts by building a loop that goes red;
improve-codebase-architecture is a survey, not a rescue; grilling
resolves a design tree and is the primitive behind five skills.
- Drop the /implement reliability claim from the implement and tdd
pages.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
One agent per page, each rewriting from its SKILL.md up and running its
own evidence hunt across the wiki, the issue tracker and the unreleased
changesets. Question counts track the evidence: wayfinder earns ten,
resolving-merge-conflicts earns three.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Encode a new rule in writing-docs.md: a multi-way branch goes in a table
or a list, never a paragraph the reader has to read in full.
- to-spec: trigger becomes a table; stop implying the tracker must be
remote, since local markdown is supported out of the box.
- prototype: wayfinder is the largest consumer (prototype is one of its
four decision-ticket types); the ask-matt handoff round trip is
demoted to one line.
- handoff: trigger becomes a table; dead prose throughout.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The old page read as session resumption, which is why people skip the
skill. Leads with portability rather than compression, names branching
as the use that gets missed, and is honest that /compact wins most
phase boundaries. Nine observed questions, compact-vs-clear-vs-handoff
first.
The old page still said the prototype gets deleted and the logic branch
builds a terminal app; both changed. Leads with throwaway-as-a-writing-
constraint, carries the primary-source branch rule, and answers the two
behaviour changes plus the recommend-by-name failure (#384).
Leads with the defining constraint — it synthesises, it does not
interview — and carries nine observed questions: the to-prd rename, the
ready-for-agent rough edge (#606), why not skip the spec, what to feed
it after a wayfinder map, and the refactor-shaped-work limitation.
grill-with-docs is a shim that runs grilling using domain-modeling, so
the two are one route, not two.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Rewrite the extinguisher/sprinkler framing as plain prose across the
docs page, the changeset and the ask-matt router line.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
