edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-09-12 18:38:06 +07:00
Code Issues Packages Projects Releases Wiki Activity

Remove "It assumes one writer" section from grill-with-docs docs

Browse Source 
The section's single-writer framing doesn't fit how the skill is actually used across a team; drop it rather than carry a stale caveat.
This commit is contained in:
Remote Box Agent
2026-08-17 07:23:08 +00:00
parent 068b6e0c62
commit 0505536390
1 changed files with 0 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/engineering/grill-with-docs.md
-6
View File
@@ -40,12 +40,6 @@ That third row is the one that catches people out. `CONTEXT.md` is a glossary an
The glossary is the point. Domain language is the thing this skill is actually building — the project's own words, agreed once, so you, the agent and your colleagues stop paying to re-derive them. It is worth saying that not everyone agrees this buys you agent performance: the sharpest public pushback is that a term and its plain-English expansion get the same result from the [model](https://www.aihero.dev/ai-coding-dictionary/model), and that the vocabulary really compresses communication between the humans who share it. That reading still leaves the glossary valuable; it just moves the value. The glossary is the point. Domain language is the thing this skill is actually building — the project's own words, agreed once, so you, the agent and your colleagues stop paying to re-derive them. It is worth saying that not everyone agrees this buys you agent performance: the sharpest public pushback is that a term and its plain-English expansion get the same result from the [model](https://www.aihero.dev/ai-coding-dictionary/model), and that the vocabulary really compresses communication between the humans who share it. That reading still leaves the glossary valuable; it just moves the value.
## It assumes one writer
The stateful outputs assume a single person curating them. A two-developer team running four months in one repo reported state drift on roughly 20% of sampled merged PRs, with ADR citations and README claims the highest-drift surfaces — deliberate, human-curated docs drifted worse than agent memory did. Pruning the stale docs did not hold; the same sweep was stale again within days. What worked was deleting shadow state outright and adding a deterministic citation and link linter to CI.
Related: running the skill repeatedly across unrelated changes in one repo tends to accumulate mixed-topic docs, because nothing separates one session's output from another's. Neither of these is fixed in the skill today.
## Common questions ## Common questions
**Should I use this or `/wayfinder`?** **Should I use this or `/wayfinder`?**