mirror of
https://github.com/mattpocock/skills.git
synced 2026-09-12 10:28:06 +07:00
docs: write the pages in neutral third person
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>
This commit is contained in:
co-authored by
Claude Opus 5
parent
0986ebaf5d
commit
86b07d15da
@@ -18,7 +18,7 @@ Reach for it at the start of a change, in a repo, when the plan is still fuzzy a
|
||||
| A repo with no domain docs at all, and no particular feature in mind | `grill-with-docs`, aimed at the repo rather than a change |
|
||||
| A decision blocked on knowledge in someone else's head | [to-questionnaire](https://aihero.dev/skills-to-questionnaire) |
|
||||
|
||||
Matt's own line on the wayfinder split: "Use /grill-with-docs for single-session planning. Use /wayfinder for multi-session planning."
|
||||
The wayfinder split comes down to session count: `/grill-with-docs` for single-session planning, `/wayfinder` for multi-session planning.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -61,13 +61,13 @@ That is the skill failing to load its two dependencies. Because `SKILL.md` is a
|
||||
Into the conversation only. This is the most substantive open complaint about the skill: the glossary is not a spec, most answers do not earn an ADR, and there is no ledger tying each resolved answer through to a spec, a ticket and a test. Precise answers — ordering guarantees, negative requirements, numeric defaults — get softened into weaker prose downstream, and the result can look complete while missing the thing you actually decided. The mitigation available today is to keep the session and feed it straight to [to-spec](https://aihero.dev/skills-to-spec), and to re-read the spec against your own answers rather than assuming it captured them.
|
||||
|
||||
**Can I point it at an existing repo that has no docs at all?**
|
||||
Yes. Matt's advice for a codebase with no ADRs, no domain language and no design principles is this skill — "just say 'help me document my repo'." The community pattern pairs it with [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) for building or repairing a `CONTEXT.md`. Expect to steer it: it will read code and ask you about what it finds, and you are the one who says which of the words already in the codebase are the right ones.
|
||||
Yes. This is the right skill for a codebase with no ADRs, no domain language and no design principles — invoke it and say "help me document my repo". The community pattern pairs it with [improve-codebase-architecture](https://aihero.dev/skills-improve-codebase-architecture) for building or repairing a `CONTEXT.md`. Expect to steer it: it will read code and ask you about what it finds, and you are the one who says which of the words already in the codebase are the right ones.
|
||||
|
||||
**What should I do when the session ends?**
|
||||
The skill's closing message tends to be open-ended, which is a known rough edge. In the main flow the answer is [to-spec](https://aihero.dev/skills-to-spec), in the same conversation. If the change is small enough to build immediately, go straight to [implement](https://aihero.dev/skills-implement) instead.
|
||||
|
||||
**Why is it called that?**
|
||||
Nobody is happy with the name, Matt included — he has called it a bad one publicly, and there is an open suggestion to rename it `grill-domain-model`, which describes the behaviour more honestly. Nothing has moved on it. If a rename ever lands, the docs page moves with it and the URL changes.
|
||||
Nobody is happy with the name. There is an open suggestion to rename it `grill-domain-model`, which describes the behaviour more honestly. Nothing has moved on it. If a rename ever lands, the docs page moves with it and the URL changes.
|
||||
|
||||
## It's working if
|
||||
|
||||
|
||||
Reference in New Issue
Block a user