mirror of
https://github.com/mattpocock/skills.git
synced 2026-09-13 02:48: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
@@ -52,7 +52,7 @@ The limit is worth knowing. It cross-references **code** and the committed `CONT
|
||||
## Common questions
|
||||
|
||||
**My `CONTEXT.md` is 500 lines. 1,000. 3,000. What do I do?**
|
||||
The size is a symptom, not the disease — the file has absorbed implementation detail and decisions that were never glossary material. Matt's fix is a direct instruction: `/grill-with-docs make my CONTEXT.md more concise and remove any implementation details from it`. Run it against a bloated file and most of it goes. Only reach for a `CONTEXT-MAP.md` split once the file is genuinely lean and still covers two domains that a reader would not want to hold at once; splitting a bloated file just gives you several bloated files. The skill's guidance here is not yet strong enough to prevent the growth in the first place, and the issue tracking that is still open.
|
||||
The size is a symptom, not the disease — the file has absorbed implementation detail and decisions that were never glossary material. The fix is a direct instruction: `/grill-with-docs make my CONTEXT.md more concise and remove any implementation details from it`. Run it against a bloated file and most of it goes. Only reach for a `CONTEXT-MAP.md` split once the file is genuinely lean and still covers two domains that a reader would not want to hold at once; splitting a bloated file just gives you several bloated files. The skill's guidance here is not yet strong enough to prevent the growth in the first place, and the issue tracking that is still open.
|
||||
|
||||
**Why is it `CONTEXT.md` and not `GLOSSARY.md`?**
|
||||
This is the most-argued naming question in the whole skill set and it has no settled answer. The case against the current name is good: if it is "a glossary and nothing else", `GLOSSARY.md` says so, and — as one reader put it — "with ai agents everything is [context](https://www.aihero.dev/ai-coding-dictionary/context)". The case for it is the map: `CONTEXT-MAP.md` pointing at several `CONTEXT.md` files reads naturally in a way `GLOSSARY-MAP.md` does not, and `context` is the standing DDD word for a bounded area of the model. At least one person maintains a local fork purely to rename the file. You can do the same, but every other skill in the set looks for `CONTEXT.md`, so a rename means patching all of them.
|
||||
@@ -67,10 +67,10 @@ Ask for it explicitly rather than waiting for it to accumulate. `/grill-with-doc
|
||||
Not cleanly today. The glossary half and the ADR half ship in one skill, so a team with an established ADR convention — different template, different location, different naming — gets instructions that conflict with its house style. The current options are to copy the skill locally and edit it, or to override the ADR conventions in your repo's own agent docs. Splitting the two apart is [an open request](https://github.com/mattpocock/skills/issues/557).
|
||||
|
||||
**Does a glossary actually earn its keep? It is one more artifact to review, and it can go stale.**
|
||||
Sometimes it does not, and it is worth being honest about where. Matt's own position is that DDD "gets less useful the closer it gets to the implementation" — the payoff is upstream, in naming and concept alignment, not in aggregates and layer ceremony. Synonym control matters at naming boundaries: module names, table names, status enums, issue titles, CLI commands. It matters much less in ordinary prose. There is also a live objection that domain terms compress communication *between humans* who already share them, and that an agent responds the same way to the plain-English description — on that reading, the glossary's value is keeping you and your reviewers aligned with what the agent is doing, not making the agent better. On a one-day build, skip it. And an unreviewed, agent-authored glossary is worse than none: it becomes confident-sounding lore that later sessions treat as truth.
|
||||
Sometimes it does not, and it is worth being honest about where. DDD gets less useful the closer it gets to the implementation — the payoff is upstream, in naming and concept alignment, not in aggregates and layer ceremony. Synonym control matters at naming boundaries: module names, table names, status enums, issue titles, CLI commands. It matters much less in ordinary prose. There is also a live objection that domain terms compress communication *between humans* who already share them, and that an agent responds the same way to the plain-English description — on that reading, the glossary's value is keeping you and your reviewers aligned with what the agent is doing, not making the agent better. On a one-day build, skip it. And an unreviewed, agent-authored glossary is worse than none: it becomes confident-sounding lore that later sessions treat as truth.
|
||||
|
||||
**Can it turn my vague prompts into domain language for me?**
|
||||
No, and there is no plan for a skill that does. Matt's answer to that request was flat: *"if you don't understand the domain language itself, it becomes meaningless drivel."* This skill enforces precision once you have the understanding — it does not manufacture vocabulary you do not have. The related trap is using domain words without doing the modelling: right nouns over the wrong conceptual structure produce output that reads correct and is not.
|
||||
No, and there is no plan for a skill that does. A domain language you do not understand yourself becomes meaningless drivel once written down. This skill enforces precision once you have the understanding — it does not manufacture vocabulary you do not have. The related trap is using domain words without doing the modelling: right nouns over the wrong conceptual structure produce output that reads correct and is not.
|
||||
|
||||
## It's working if
|
||||
|
||||
|
||||
Reference in New Issue
Block a user