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>
Mirrors how the personal wiki is referenced: read
~/repos/ai/ai-coding-dictionary/dictionary/ where it exists, and fall
back to GitHub where it doesn't.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
writing-docs.md now tells doc authors to prefer the dictionary's word
over an invented synonym, and to link each term's first use on the page.
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>
Removes the five docs-page-only changesets (quickstart drop, grill-me pass,
four-section spine, rewrite-to-standard, writing-for-agents pass) — the
changelog reports on the shipped skills, not on the site pages.
Merges the clusters that describe one change each: ask-matt routing,
the grilling round-by-round rework, prototype, wayfinder, wizard and
writing-for-agents. 27 changesets become 15.
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>
ask-matt still told the agent to 'keep the answer, delete the code',
which prototype-primary-source made false — the prototype is kept on a
prototype/<name> branch and pointed at from the implementation issue.
Both READMEs still called the logic artifact a runnable terminal app;
it is a single shareable HTML file.
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.
An observed question still beats an invented one and the hunt is still
mandatory, but a thin skill may carry a question a reader would plainly
ask. The count stays honest to the evidence rather than padding every
page out to match a richer one.
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>
An audit of all 25 docs pages found the two sections that carry the most
weight are the two the standard treated as optional. Only grill-me has a
Common questions section. Twelve pages have no It's working if, and
several that do use it for compliance checks on the skill's internals
rather than for signals the reader can see.
writing-docs.md now names the four-section spine, gates Common questions
on evidence -- the personal wiki where it exists on the machine, this
repo's issues, and CHANGELOG.md -- and raises the It's working if bar to
"checkable without opening SKILL.md". CLAUDE.md names the four sections
in the pointer.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every docs page opened with a [Source](github.com/...) link, and
.agents/writing-docs.md told agents to add one to each new page.
Remove the line from all 25 pages, rewrite the one inline use in
ask-matt.md, and drop the rule from the page template, the fixed
frame list, and the "Done when" list so the links do not come back.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The page described grill-me as operating on an existing plan and sitting
at the front of the build chain. Both are wrong. It takes a loose idea,
not a plan, and it is a productivity skill rather than an engineering
one: stateless, so it needs no repo and does not assume the subject is
software at all.
Routing now keys on portability rather than on whether a codebase
exists, and Where it fits names it a standalone that runs anywhere on
anything. Handing off to to-spec is presented as an option for when the
idea turns out to be software, not as the purpose of the skill.
The old page explained the mechanism and stopped. It answered none of
the questions people actually ask: which grilling skill to reach for,
how many questions is normal, what to do with a question talking can't
settle, whether to clear context before to-spec.
Keep the mechanism short and spend the page on judgement instead:
three-way sibling routing keyed on what you have in front of you; a
section naming passivity as the main failure mode; grillable vs
ungrillable as the move for questions that need a prototype; an
"It's working if" list; and a "Common questions" section answering the
six highest-volume ones. Say plainly to leave plan mode off.
Sourced from user questions across X, Discord and YouTube.
aihero.dev renders an install widget above every skill page. Each page
then repeated the same commands in its body, and the two copies had
drifted: the widget uses the current `npx skills@latest ...` wording
while the hand-written blocks mostly carried the older bare `npx skills
...`. Pages showed the right command and a stale one together.
Delete the block from all 25 pages and record the rule in
.agents/writing-docs.md: install wording belongs to the site, not the
page. The template no longer carries a Quickstart, and
.agents/install-block.md notes that docs pages are not one of its
consumers.
Moves the skill out of in-progress/ and ships it: bucket README,
top-level README, plugin.json, an ask-matt router entry, and a docs
page at docs/productivity/wait-what.md.
Productivity rather than engineering — it fires in any conversation
with an agent, code or not. The CONTEXT.md clause is an opportunistic
hook, not a prerequisite.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Delete the four skills in deprecated/ — design-an-interface, qa,
request-refactor-plan, ubiquitous-language — each already absorbed by a
promoted skill. The bucket itself stays, now empty: a retired skill is
deleted, and the changeset that removes it names its replacement.
Delete edit-article and obsidian-vault along with the personal/ bucket.
obsidian-vault hardcoded a path to Matt's own vault and was
model-invocable, so any skills.sh user could have had it fire on them.
None of the six was in the plugin, but skills.sh serves every SKILL.md in
the repo, so all six were installable — hence the changeset.
Reframe in-progress/ from scratchpad to beta channel: public on purpose,
feedback wanted, not in the plugin, and installable one skill at a time
through skills.sh. Nothing there is deleted or graduated.
Drop qa from the two live docs that cited it as an issue-tracker skill.
ADR 0002 is left untouched — it records reasoning that was true when
decided.
Resolvesmattpocock/personal-wiki#256
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
"Re-pitch that last message" pinned the correction to one message.
"Re-pitch that" leaves the agent to judge how much of what it said
failed to land — and is shorter.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A three-line, user-invoked skill in in-progress/. Fire it when the
agent's last message doesn't land; it re-pitches that message with
the missing context, in ASD-STE100 Simplified Technical English,
using the ubiquitous language from CONTEXT.md.
The name is the mechanism. Concision skills fail by growing, so this
one is a single precise leading word and nothing else.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
CLAUDE.md is always-loaded, so every word costs on every turn. The
edit had grown it by ~65 words, nearly all of which paid load without
changing behaviour:
- The official-marketplace sentence was exposition — a fact the
pointer target already carries.
- "Never reword an install command" steered by prohibition, which
makes the banned behaviour more available, not less.
- The fallback rationale was a third copy of what install-block.md
owns.
- The paragraph split doubled the surface with no branch behind it.
What remains is the one line that does work — the context pointer,
front-loaded on its trigger — leaving CLAUDE.md 10 words longer than
before rather than 65.
Refs mattpocock/personal-wiki#250
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
