best-practices/documentation.md

# Documentation Standards

Every project maintains four core markdown files.

## CLAUDE.md

The primary reference for Claude sessions. Should contain:
- Project overview and architecture
- Repository structure (keep updated as the project evolves)
- Key design decisions with rationale
- Conventions and coding standards
- Environment details (IPs, URLs, credential references — never actual values)
- Common operations / how-to recipes
- Put critical rules at the top — Claude reads sequentially and earlier content has more influence

## MEMORY.md (Tiered Memory System)

Long-running projects accumulate significant context. Use a **tiered memory** structure:

**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Keep it under ~50 lines.

**memory/** contains the actual content, split by topic:
- `memory/project-status.md` — Current milestone, what's next, blockers
- `memory/gotchas-<topic>.md` — Gotchas grouped by technology
- `memory/process-lessons.md` — How-to-work-with-this-repo lessons
- `memory/m<N>-reflection.md` — One file per milestone reflection
- `memory/decisions.md` — Architecture and design decisions

**Principles:**
- Split by topic, not by time
- Index descriptions matter — they're used to decide what to read
- Prune aggressively — stale memory is worse than no memory
- Each file should be self-contained and greppable
- Deduplicate with CLAUDE.md — stable conventions go in CLAUDE.md, learnings and gotchas go in memory

## FUTURE.md

Backlog of improvement ideas, each with:
- **Problem:** What's painful or manual today
- **Idea:** What the improvement looks like
- **Open questions:** Unknowns to research before starting
- **Depends on:** Other items or milestones that should come first

## README.md

Human-readable project documentation:
- Architecture summary
- Quick start / setup instructions
- Milestone table with status
- Scripts section listing every script with purpose and usage

## Extract Reusable Patterns Early

When a reusable pattern emerges during project work (a gotcha that applies to any project using the same tool, a process lesson that generalises), extract it into a best-practices guide immediately rather than waiting for a dedicated distillation pass. The guide pays for itself when used to audit and improve the current project in the same session, and benefits all future projects.

## CONTEXT.md (Active Work Focus)

Tells Claude (and independent agents) what the project is currently working on. Follows the same thin-index pattern as MEMORY.md.

**CONTEXT.md** is a thin index with links to `context/<topic>.md` detail files.

**Principles:**
- Keep it current — remove entries when work is complete
- Orient agents — this is the primary mechanism for pointing independent agents at the right work
- Complement, don't duplicate — CLAUDE.md has conventions, MEMORY.md has learnings, CONTEXT.md has the current focus

## Research-Backed Document Generation

When generating structured documents (contracts, specs, reports) from research, require every assertion or clause to link to a sourced finding file. Use a pipeline: `references/` → `research/[topic]/findings/` → `templates/`, with markdown links from clauses back to findings. A clause or claim without a traceable source is flagged as a gap. This turns document generation into an auditable process — reviewers can trace any statement back to its evidence, and missing support becomes visible rather than invisible.

## Structured Q&A to Fill a CONTEXT Template

For drafting tasks with many unknowns, start from a full section template with every field marked TBD, then resolve iteratively via Q&A with the user. Track a confidence level per section (e.g., High/Medium/Low/TBD) so remaining gaps stay visible. Prevents the common failure of premature drafting on incomplete context — the template surfaces what you don't know before the first sentence is written.

## Sourced-Claim Writing: Match Claims to Sources Exactly

When writing claims backed by sources, the claim must match the source exactly in scope, magnitude, population, units, qualifiers, and attribution. Common failure modes:
- **Population drift** — "82% of organisations" vs source "82% of container users"
- **Unit mismatch** — dollars vs percentage, per-year vs per-month
- **Dropped qualifiers** — "not from X" vs source "not just from X"
- **Year mislabelling** — citing a 2024 figure as 2025
- **Attribution drift** — attributing a blog post to a famous report it merely references

Fix: read the source before writing the sentence, never drop qualifiers when paraphrasing, and verify the attribution label against the finding's Source section. Paraphrasing from memory is the main cause of drift.

## Three-Layer Verification for Sourced Documents

For evidence-backed documents, run a three-layer check before shipping:

1. **Story vs finding file** — every claim in the narrative matches the finding it cites
2. **Finding vs reference file** — every finding accurately represents the underlying source
3. **Structural checks** — every number has a link, every finding has a URL, no unsupported qualifiers

Track verified files by checksum in a `VERIFICATION.md`, enforce via a pre-commit hook.

**Hard rule:** never update a checksum without re-running verification. Structural edits don't change claims but do change the checksum — bumping it without re-verifying silently defeats the control.

Second verification passes routinely catch 10-20+ new issues. Treat verification as iterative, not one-shot.

## Research Workflow: REFERENCES_CONSIDERED Per Topic

When running multi-topic research against a shared reference pool, create a `REFERENCES_CONSIDERED.md` per topic listing every reference and whether it was reviewed through that lens (YES / NO / N-A with a short reason). New topics introduced mid-project miss all previously-processed references unless the gap is made explicit. This file turns "have we checked everything?" into a zero-ambiguity work queue.

Create the file immediately when a topic is created, not retroactively — retroactive creation loses the signal of which references were genuinely reviewed vs. assumed-reviewed.

## Executive Document Structure: Conclusion-First, Glossary Pattern

For documents aimed at senior or executive audiences:

- **Conclusion-first** — put "Bottom Line" and "What We Should Do" ABOVE all evidence. Executive readers are top-down and may not reach the end; evidence becomes supporting detail rather than the main narrative.
- **Glossary pattern** — replace inline concept explanations with a glossary. Each entry has a brief definition, a "Why leadership should care" hook, and a link to the full detail doc. Keeps the main flow readable while preserving depth for those who want it.
- **Separate executive brief for long documents** — for compiled docs over ~60 pages, generate a separate 5-10 page brief containing just Bottom Line + Ask + key evidence summaries. The full document remains for reviewers who need detail; the brief is what actually gets read.