Agent guide: writing docs and extending the glossary #62

New Issue

2026-09-24T19:08:23Z

haylan commented

2026-09-24 19:08:23 +00:00

Part of #55

Question

What rules should an agent follow when writing/updating docs here (source-of-truth line, link don't restate, where things go) and when it meets new or conflicting terminology (how to add/adjust CONTEXT.md)? Lives in docs/agents/, referenced from CLAUDE.md. HITL: /grilling + /writing-for-agents.

Part of #55 ## Question What rules should an agent follow when writing/updating docs here (source-of-truth line, link don't restate, where things go) and when it meets new or conflicting terminology (how to add/adjust CONTEXT.md)? Lives in docs/agents/, referenced from CLAUDE.md. HITL: /grilling + /writing-for-agents.

haylan added the wayfinder:grilling label 2026-09-24 19:08:23 +00:00

haylan added a new dependency 2026-09-24 19:08:34 +00:00

#59 Glossary: pin down domain terms in CONTEXT.md

haylan added a new dependency 2026-09-24 19:08:34 +00:00

#60 Target doc structure

haylan referenced this issue

2026-09-24 19:08:35 +00:00

Docs cleanup: restructure, move code comments into docs, remove image generation #55

haylan self-assigned this 2026-09-24 19:35:32 +00:00

haylan commented

2026-09-24 19:37:27 +00:00

Resolution — agent guide

Placement

New file docs/agents/writing-docs.md.
One pointer line in CLAUDE.md (so AGENTS.md / QWEN.md inherit it):

Writing docs — before editing README.md, docs/, or a comment in docker-compose.yml / .env.example / scripts/, read docs/agents/writing-docs.md.
Glossary rules go into the existing docs/agents/domain.md (single source); the writing guide links there in one line.

writing-docs.md content

Every doc opens with its Source of truth line; name files/services/keys, never restate their values. Doc vs. source disagree → source wins, fix the doc in the same change.
The README index is the doc map — a new doc gets a row there.
Code comments: pointer by default; inline one-liner only for data-loss / security / breakage warnings; update.sh-filled keys keep the "auto-filled — leave blank" marker; ponytail: notes are converted the same way.
A source change updates the doc section its pointer names, in the same change.
docs/research/ is frozen history: new research = new file + index row; superseded = marked in the index, never edited.
Done when: every pointer in touched code resolves to an existing doc section, every touched doc has its source line, no touched doc restates a source value. No lint script.

domain.md addition — term not in CONTEXT.md

Synonym of an existing term → use the canonical term; no edit, no question.
New concept → add it to CONTEXT.md in the same change (term, 1–2 sentence definition, Avoid, no values) and name it in the final message for the user to veto.
Conflicts with an existing definition → stop and ask the user.

## Resolution — agent guide **Placement** - New file `docs/agents/writing-docs.md`. - One pointer line in `CLAUDE.md` (so `AGENTS.md` / `QWEN.md` inherit it): > **Writing docs** — before editing `README.md`, `docs/`, or a comment in `docker-compose.yml` / `.env.example` / `scripts/`, read `docs/agents/writing-docs.md`. - Glossary rules go into the existing `docs/agents/domain.md` (single source); the writing guide links there in one line. **`writing-docs.md` content** 1. Every doc opens with its *Source of truth* line; name files/services/keys, never restate their values. Doc vs. source disagree → source wins, fix the doc in the same change. 2. The README index is the doc map — a new doc gets a row there. 3. Code comments: pointer by default; inline one-liner only for data-loss / security / breakage warnings; `update.sh`-filled keys keep the "auto-filled — leave blank" marker; `ponytail:` notes are converted the same way. 4. A source change updates the doc section its pointer names, in the same change. 5. `docs/research/` is frozen history: new research = new file + index row; superseded = marked in the index, never edited. 6. **Done when:** every pointer in touched code resolves to an existing doc section, every touched doc has its source line, no touched doc restates a source value. No lint script. **`domain.md` addition — term not in `CONTEXT.md`** - Synonym of an existing term → use the canonical term; no edit, no question. - New concept → add it to `CONTEXT.md` in the same change (term, 1–2 sentence definition, _Avoid_, no values) and name it in the final message for the user to veto. - Conflicts with an existing definition → stop and ask the user.

haylan closed this issue

2026-09-24 19:37:28 +00:00

haylan referenced this issue

2026-09-24 19:41:49 +00:00

Execution hand-off checklist #64

haylan referenced this issue from a commit

2026-09-24 19:52:49 +00:00

docs(agents): add writing-docs guide and new-term procedure

haylan referenced this issue

2026-09-24 19:53:03 +00:00

Docs cleanup: restructure, move code comments into docs, remove image generation #65

Sign in to join this conversation.