| name | updating-docs |
| description | Use when user asks to update, add, or modify documentation in `docs/` of this repository, when creating a new feature/architecture/reference/project doc, or when an agent is about to write in `docs/` and has not read `CLAUDE.md` and `.claude/rules/*` in the current session. Triggers on "update docs", "document this", "add a doc for X", "เขียน docs", "อัพเดทเอกสาร". Forces read-first discipline to prevent orphan docs, contradicted stable rules, and broken wiki links. |
Updating Docs
Overview
This skill enforces the read-first, write-second discipline for documentation work. Stable rules live in .claude/rules/, an authoritative tree lives in CLAUDE.md, and the wiki-link convention only works if every doc follows the pattern. Skipping context before writing creates orphan docs that future agents cannot find.
Core principle: Future agents must be able to navigate this repo from docs alone. Every doc is a memory cell — a disconnected doc is a lost memory.
When to Use
- User says "update docs", "document this", "อัพเดทเอกสาร", "เขียน doc", "เพิ่ม doc"
- Creating a new feature/architecture/reference/project/integration/build/testing doc
- Modifying an existing doc and unsure of structure
- Touching
CLAUDE.md Documentation Map
- An agent is about to write in
docs/ and has not read CLAUDE.md in this session
Do NOT use for:
- Inline code comments (use language conventions instead)
CHANGELOG.md entries (use Keep a Changelog format)- Decisions log (
decisions.md has its own format)
- This repo's own governance files (top-level
README, INSTALL, PRINCIPLES, CONTRIBUTING, CHANGELOG, CLAUDE.md) — those follow a different convention and are maintained outside this skill's scope
Required Pre-Reading (MUST do before writing)
Iron Law: no doc written before these are read in this session.
Read CLAUDE.md
Read .claude/rules/stable-rules.md
Read .claude/rules/coding-behavior-rules.md
Read .claude/rules/security-rules.md
Read docs/_index.md
Read the closest existing doc in the same category
If you skip these, your doc will contradict a stable rule within 5 lines. This is not paranoia — it has happened.
The Workflow
digraph doc_workflow {
"User asks to update/add doc" [shape=doublecircle];
"Read CLAUDE.md + .claude/rules/*" [shape=box];
"Read existing sibling doc in same category" [shape=box];
"Pick category" [shape=box];
"Write doc following sibling structure" [shape=box];
"Update docs/_index.md table" [shape=box];
"Update CLAUDE.md Documentation Map" [shape=box];
"Verify cross-links >=2 wiki links per doc" [shape=box];
"User asks to update/add doc" -> "Read CLAUDE.md + .claude/rules/*" [label="RED: must do first"];
"Read CLAUDE.md + .claude/rules/*" -> "Read existing sibling doc in same category";
"Read existing sibling doc in same category" -> "Pick category";
"Pick category" -> "Write doc following sibling structure";
"Write doc following sibling structure" -> "Update docs/_index.md table";
"Update docs/_index.md table" -> "Update CLAUDE.md Documentation Map";
"Update CLAUDE.md Documentation Map" -> "Verify cross-links >=2 wiki links per doc";
}
Doc Category Decision
Where does this doc go? Match the existing repo's category set. The category that already has a similar doc is yours.
| Category | Path | When |
|---|
| Project | docs/project/ | Identity, stack, team roles — read first by every agent |
| Feature workflow | docs/features/ | User-facing behavior, end-to-end business workflow |
| Architecture | docs/architecture/ | Tech choices, schema, infra patterns, subsystem design |
| Reference | docs/reference/ | Config, constants, conventions, design tokens |
| Integration | docs/integrations/ | External tools, libraries, services |
| Build | docs/build/ | Build, packaging, release |
| Testing | docs/testing/ | Test strategy, conventions, fixtures |
If unsure: read docs/_index.md table of contents. The category that already has a similar doc is yours. Do not create empty category folders — every room needs furniture.
Required Doc Structure
Match the template used by existing docs in this repo. A typical structure:
# Title
> One-line description ending with period.
---
## Overview
What is this? 1-2 paragraphs.
## Context Snapshot
Bullets or table of the key facts a reader needs upfront.
## When to Read This
### Trigger
- Symptom or task that signals this doc applies.
### Read With
- `path/to/file.md` [[wiki-link]] — reason
## [Main content sections...]
- Use H2 for major sections, H3 for sub-sections.
- Include code blocks for non-trivial examples.
- Cross-link to related docs with `[[docs/path/file]]` syntax.
## Related
- [[docs/related-1]] — why it's related
- [[docs/related-2]] — why it's related
Length guideline: <500 words for most docs. If you need more, ask whether it should be split.
The 6 Things You MUST Do (Checklist)
After writing the doc, verify ALL of these:
If any item unchecked, the doc is not done. The user will assume you did all 6.
Common Failures and Fixes
| Failure | Why it happens | Fix |
|---|
Doc not findable from _index.md | Agent forgot index step | Always include the index update in your workflow — it is part of "the doc" |
| Doc contradicts a stable rule | Agent skipped pre-reading | Re-read rules — pre-reading is iron law, no exceptions |
Doc uses raw path docs/features/X.md | Agent did not know wiki-link syntax | Use [[docs/features/X]] everywhere — Obsidian-compatible |
| Orphan doc, no related links | Agent stopped after writing the doc | Section "## Related" is mandatory, not optional |
| Doc explains things obvious from code | Agent over-explained | Match sibling doc depth; if sibling has 50 lines, yours should not have 500 |
| One doc per folder regardless of value | Agent over-applied category rule | Categories are rooms, not slots — skip empty rooms |
| Doc duplicates content from CLAUDE.md | Agent did not check the hub first | Link to CLAUDE.md instead of rewriting |
| Doc has 3 paragraphs of "history of how we got here" | Agent wrote narrative | Cut to Overview + Context Snapshot — narrative goes in commits |
Red Flags — STOP and Restart
If you catch yourself doing any of these, delete the doc and start over:
- "I will add the cross-links later" — they will be forgotten
- "The user only asked for the doc, not the index" — index update is part of "the doc"
- "I already know the rules, no need to re-read" — that is exactly when you miss them
- "It is a small doc, does not need structure" — small docs benefit from structure MORE, not less
- "The doc is fine without Related section" — orphan docs are useless docs
- "I will just write it quickly, fix structure after" — you will never fix it after
- "This doc is unrelated to the rules" — every doc is downstream of stable rules
- "Skipping _index.md because it is just navigation" — navigation IS the point
All of these mean: delete what you wrote, re-read the rules, and start over following the workflow.
Quick Reference: Wiki Link Syntax
# GOOD — Obsidian-compatible, clickable in supported editors
[[docs/features/X]]
[[docs/reference/Y]]
[[CLAUDE]]
# BAD — raw path, not a link
[docs/features/X.md](docs/features/X.md)
docs/features/X.md
Quick Reference: When to Read Which Rule
| Rule file | Read before docs that touch... |
|---|
stable-rules.md | Always |
coding-behavior-rules.md | Docs about coding workflow, TDD, surgical changes |
security-rules.md | Docs about auth, sessions, file uploads, secrets, admin routes |
Real Example: Adding a New Feature Doc
User: "Document the new feature X"
Step 1 — Read (RED phase):
Read CLAUDE.md
Read .claude/rules/stable-rules.md
Read docs/_index.md
Read docs/features/closest-sibling.md
Step 2 — Decide category: Feature → docs/features/X.md
Step 3 — Write following the sibling's template.
Step 4 — Update both maps:
docs/_index.md → add row in "Features" tableCLAUDE.md → add row in Documentation Map "Features" section
Step 5 — Cross-link: [[docs/features/closest-sibling]], [[docs/architecture/tech-stack]]
Step 6 — Verify: Run through the 6-item checklist above.
Related
- [[CLAUDE]] — Project hub, has the directory tree and Documentation Map
- [[.claude/rules/stable-rules]] — Non-negotiable rules every doc must respect
- [[docs/_index]] — Documentation index you must update when adding a doc
TEMPLATES/* in this repo (if present) — doc structure templates; match your new doc to the closest existing siblingdocs/features/<closest-sibling> — the most similar existing doc in the same category; match its style
