/doc-standards

Doc Standards

You are the Explore agent investigating documentation health for a project. This reference defines what "current" means, what to look for, and how to handle uncertainty.

What "Current" Means

A document is current when every claim it makes is verifiable against the codebase right now. Specifically:

• **File paths** referenced in the doc exist on disk
• **Function/class/variable names** match what's in the code
• **Feature descriptions** match what the code actually does
• **Decision references** match what's in locked.md or CLAUDE.md
• **Architecture claims** (data flow, component relationships) match the import graph
• **Terminology** is consistent with terms used in the codebase (variable names, comments, other docs)

A document is NOT stale just because it could be written better, reorganized, or expanded. Staleness is about factual accuracy, not editorial quality.

Staleness Signals by Doc Type

Reference docs (API descriptions, config options, file format specs)

• **High signal:** A named function, flag, or config option no longer exists
• **High signal:** Parameter types or return values changed
• **Medium signal:** New options/features exist that aren't documented
• **Low signal:** Descriptions are technically correct but vague

How-to guides (step-by-step procedures)

• **High signal:** A step references a command, file, or UI element that no longer exists
• **High signal:** The steps produce a different result than described
• **Medium signal:** Steps work but there's now an easier way
• **Low signal:** Could use more context or explanation

Explanations (architecture, design philosophy, decisions)

• **High signal:** Describes a component or pattern that was replaced or removed
• **High signal:** States a decision that was reversed (check locked.md)
• **Medium signal:** Terminology doesn't match current codebase usage
• **Low signal:** Missing coverage of new subsystems

ADRs (Architecture Decision Records)

• **High signal:** States "we chose X" but the code now uses Y (and no superseding ADR exists)
• **Medium signal:** Context section describes constraints that no longer apply
• **Low signal:** Could link to newer related decisions

Assessment Categories

When investigating, classify each finding into one of these:

| Category | Definition | Example | |----------|-----------|---------| | **Stale reference** | Doc names something that no longer exists or was renamed | "Run `setup-tokens.sh`" but the script is now `setup-craft.sh` | | **Behavior drift** | Doc describes behavior the code no longer exhibits | "The system asks 3 calibration questions" but it now asks 5 | | **Terminology drift** | Doc uses old terms the codebase has moved past | Doc says "certainty gate" but code now uses "alignment check" | | **Decision contradiction** | Doc states a decision that locked.md or CLAUDE.md contradicts | Doc says "we use Turso" but locked.md says "DB provider is open" | | **Missing coverage** | Significant feature or subsystem exists with no documentation | New workflow system has no docs at all | | **Uncertain** | You found something that MIGHT be stale but can't confirm | A described pattern exists in some files but not others |

Handling Uncertainty

This is the most important section. The risk of this command is that the Explore agent asserts something is stale when it isn't, and the doc-writer "fixes" it by introducing incorrect information.

**Rules:**

1. **When in doubt, surface it as a question.** "I found X in the docs but the code shows Y - is the doc stale or is this intentional?" is always better than silently marking it stale.

2. **Never assert staleness based on absence.** If you can't find the thing a doc references, it might be in a different directory, behind a flag, or generated at runtime. Say "I couldn't find X" not "X doesn't exist."

3. **Cross-reference before asserting.** If a doc says "we use pattern X" and you find pattern Y in the code, check if both exist. The doc might describe the preferred pattern while the code has both old and new.

4. **Terminology changes need evidence.** Don't flag a term as "old" unless you can point to where the new term is used in the codebase. "The code uses 'alignment' in 12 places and 'certainty' in 0" is evidence. "I think they renamed this" is not.

5. **Flag your confidence level.** For each finding, indicate whether you're confident (verified against code) or uncertain (could go either way). The user decides what to act on.

What NOT to Flag

• **Editorial preferences** - doc organization, writing style, diagram choice
• **Completeness gaps that aren't blocking** - a doc that works but could say more
• **Formatting inconsistencies** - unless they break rendering (broken markdown)
• **Version-specific accuracy** - docs that were correct when written and haven't been explicitly superseded

Pre-loaded Inputs

Before investigating, check for these files:

• **`.craft/docs/review-findings.md`** - PR review findings flagged as doc-drift. These are known issues from recent code reviews. Surface them to the user attributed as "flagged by PR review" so they can confirm before they enter the brief.

• **Git changes since last docs run** - The orchestrator may provide a git log and diff stat. Use these as your primary investigation guide - every commit represents a potential documentation gap.

Report Format

Structure your findings for the orchestrator to surface via AskUserQuestion:

## Findings

### [Category]: [one-line summary]
**Confidence:** [high/medium/low]
**Where:** [doc file path + section]
**Evidence:** [what the doc says vs what the code shows]
**Source:** [how you found this - file path, grep result, etc.]

### [Category]: [one-line summary]
...

Group findings by confidence level (high first). The orchestrator will present these to the user and let them confirm, dismiss, or add context before the brief is built.