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
@@ -38,7 +38,7 @@ The opposite failure exists as well: if your own global instructions forbid an a
|
||||
|
||||
**Where should the file live — and should I commit it?**
|
||||
|
||||
The skill puts the file where the repo already keeps notes and does not have an opinion beyond that. The community one is fairly settled: ADRs are kept, research files are not. The sharpest version of it, from a Discord thread on exactly this question: "ADRs yes. Everything else archive or delete after done. It otherwise becomes cruft of work and can poison future repo reads if you've drifted away from the spec/research." A research file records what was true on the day it was written, so a stale one is worse than none. Matt's own position is that these artifacts don't really belong in git, and there is no ruling from him on a canonical home — people use Obsidian, a separate knowledge repo, or the issue tracker instead.
|
||||
The skill puts the file where the repo already keeps notes and does not have an opinion beyond that. The community one is fairly settled: ADRs are kept, research files are not. The sharpest version of it, from a Discord thread on exactly this question: "ADRs yes. Everything else archive or delete after done. It otherwise becomes cruft of work and can poison future repo reads if you've drifted away from the spec/research." A research file records what was true on the day it was written, so a stale one is worse than none. On balance these artifacts don't really belong in git, and there is no canonical home for them — people use Obsidian, a separate knowledge repo, or the issue tracker instead.
|
||||
|
||||
**What counts as a "high-trust" primary source, and who decides?**
|
||||
|
||||
@@ -50,7 +50,7 @@ No. Nothing auto-loads a past research file; it is a document sitting in the rep
|
||||
|
||||
**Why not just ask the agent to go read the docs?**
|
||||
|
||||
You can, and Matt did for a long time — his hesitation before shipping this was "I tend to just say that verbatim." Two things the skill buys over the prompt: it runs in the background so your session keeps its [context](https://www.aihero.dev/ai-coding-dictionary/context) clean, and the primary-source constraint and the cited-file output come out the same way every time rather than however you happened to phrase it. Against a [harness](https://www.aihero.dev/ai-coding-dictionary/harness)'s own deep-research mode, the difference is the artifact and the source discipline, not the search. If a two-line prompt gets you what you need on a small question, use the two-line prompt.
|
||||
You can, and a two-line prompt saying exactly that was the practice this skill replaced. Two things the skill buys over the prompt: it runs in the background so your session keeps its [context](https://www.aihero.dev/ai-coding-dictionary/context) clean, and the primary-source constraint and the cited-file output come out the same way every time rather than however you happened to phrase it. Against a [harness](https://www.aihero.dev/ai-coding-dictionary/harness)'s own deep-research mode, the difference is the artifact and the source discipline, not the search. If a two-line prompt gets you what you need on a small question, use the two-line prompt.
|
||||
|
||||
**When does it stop reading?**
|
||||
|
||||
|
||||
Reference in New Issue
Block a user