---
type: skill
domain: general
---

# DOC_QUALITY
> **ROLE:** Documentation quality enforcer
> **TRIGGER:** Writing docs, READMEs, API docs, or changelogs

## Core Directive
Write documentation that agents and humans can parse quickly. Structure over prose. Examples over explanations. If an agent can't extract actionable info in 5 seconds, the doc failed.

## Step-by-Step Protocol
1. **Lead with usage:** First section is always "Quick Start" or "Usage" with a copy-paste command.
2. **Structure with headers:** Every section has an H2/H3 header. No walls of text. Agents scan headers first.
3. **Show, don't tell:** Every concept gets a code example. "Configure X" → show the config file.
4. **Document the WHY:** Comments explain WHY, not WHAT. "# Atomic write prevents race condition" not "# Write to file".
5. **Keep it current:** If code changes, docs change in the same commit. Stale docs are worse than no docs.

## Metrics & Thresholds
- README must have: purpose (1 sentence), quick start (copy-paste), architecture (diagram or list)
- API docs: every public function has docstring with Args, Returns, Raises
- Max paragraph length: 3 sentences. If longer, use bullet points.
- Every CLI tool: `--help` output that covers all flags
- Changelog: follows Keep a Changelog format (Added/Changed/Fixed/Removed)

## Examples

### Good: Agent-parseable docstring
```python
def atomic_update_json(filepath, updater, default=None):
    """Atomically update a JSON file under file lock.

    Args:
        filepath: Path to JSON file
        updater: Callable(data) -> data, transforms the loaded JSON
        default: Default value if file doesn't exist (list or dict)

    Returns:
        The updated data after write.

    Raises:
        json.JSONDecodeError: If file contains invalid JSON
    """
```

### Bad: Useless documentation
```python
def update(f, u, d=None):
    """Updates the file."""  # WHAT file? HOW? WHAT happens on error?
```

## Anti-Patterns
- "See code for details" — useless for agents, defeats the purpose of docs
- Documenting obvious code (`x = x + 1  # increment x`)
- README with no usage example (forces reader to read source code)
- Stale docs that describe old behavior (actively harmful, worse than none)

## Tools to Use
- `brain_query.py --query "documentation patterns"` — Check existing standards
- `pulse_save.py --learnings "doc pattern: ..."` — Save good doc patterns for reuse

## Verification
- [ ] README has: purpose, quick start, architecture overview
- [ ] Every public function has docstring with Args/Returns
- [ ] No paragraph exceeds 3 sentences
- [ ] All CLI tools have `--help` with complete flag descriptions
