cc-documentation-quality
Documentation Quality
STOP - Documentation Freshness
- Documentation rots faster than code. Stale docs are worse than no docs.
- If code changed, check which docs need updating - README, CLAUDE.md, API docs, comments
- Comments explain WHY, not WHAT - If it repeats the code, delete it
Core Principle
"The purpose of comments is to explain things that aren't obvious from the code." — Ousterhout, APOSD
Good documentation:
- Explains WHY, not WHAT
- Uses different words than the code
- Stays synchronized with implementation
- Describes the non-obvious
Documentation Checklist
1. README Accuracy
- Does README describe current behavior?
- Are setup instructions still valid?
- Do examples still work?
- Are dependencies current?
- Is the feature list accurate?
2. Comment Freshness
- Do comments match the code they describe?
- Are TODOs still relevant or stale?
- Do function comments match signatures?
- Are "temporary" comments actually temporary?
3. API Documentation
- Public interfaces have doc comments?
- Parameters documented with types and constraints?
- Return values documented?
- Exceptions/errors documented?
- Examples provided for complex APIs?
4. Changelog Updates
- Breaking changes documented?
- New features listed?
- Bug fixes noted?
- Migration instructions for breaking changes?
5. Comment Quality (APOSD)
- Comments describe non-obvious things?
- Comments use different words than code?
- Interface comments present (before implementation)?
- Comments explain "why", not "what"?
- No comments that repeat the code?
6. Missing Documentation
- New public APIs documented?
- New configuration options documented?
- New environment variables documented?
- New CLI flags documented?
7. AI Documentation
Check all AI config files that exist in the project:
| File | Tool |
|---|---|
CLAUDE.md |
Claude Code |
.cursorrules / .cursorignore |
Cursor |
.github/copilot-instructions.md |
GitHub Copilot |
AGENTS.md |
Copilot Workspace |
.windsurfrules |
Windsurf |
.aider.conf.yml |
Aider |
.continue/config.json |
Continue.dev |
.clinerules |
Cline |
.roomodes |
Roo Code |
CONVENTIONS.md |
Various |
- AI docs reflect current architecture?
- Agent/skill descriptions accurate?
- File structure documentation up to date?
- All AI config files consistent with each other?
- Version numbers synchronized?
Comment Anti-Patterns
| Anti-Pattern | Example | Problem |
|---|---|---|
| Repeat the code | i++ // increment i |
Zero value |
| State the obvious | // loop through users |
Noise |
| Stale comment | Comment says X, code does Y | Dangerous |
| TODO forever | // TODO: fix this from 2019 |
Clutter |
| Commented-out code | Dead code masquerading as comment | Confusion |
Comment Patterns That Add Value
| Pattern | Example | Value |
|---|---|---|
| Explain rationale | // Use insertion sort: n < 10 always |
Design decision |
| Warn about non-obvious | // Must call before X, else crash |
Prevent bugs |
| Summarize algorithm | // Binary search on sorted timestamps |
Quick understanding |
| Document edge case | // Empty list returns -1, not null |
Clarify behavior |
| Reference external | // Per RFC 7231 section 6.5.4 |
Authority |
Severity Guide
| Finding | Severity |
|---|---|
| README contradicts actual behavior | CRITICAL |
| API doc says wrong return type | CRITICAL |
| Stale comment causes bug risk | CRITICAL |
| CLAUDE.md describes deleted/renamed files | CRITICAL |
| New public API undocumented | IMPORTANT |
| Breaking change not in changelog | IMPORTANT |
| CLAUDE.md missing new features/agents | IMPORTANT |
| AI doc version mismatch | IMPORTANT |
| Stale TODO from distant past | SUGGESTION |
| Could add clarifying comment | SUGGESTION |
| Minor README improvement | SUGGESTION |
Questions to Ask
- "If someone reads only the docs, will they use this correctly?"
- "If the code changes, which docs need updating?"
- "Does this comment tell me something the code doesn't?"
- "Is this TODO actionable or just noise?"
Chain
| After | Next |
|---|---|
| Docs need code changes | Back to implementation |
| Docs verified | Done (pre-commit gate) |
More from ryanthedev/code-foundations
cc-defensive-programming
Use when auditing defensive code, designing barricades, choosing assertion vs error handling, or deciding correctness vs robustness strategy. Triggers on: empty catch blocks, missing input validation, assertions with side effects, wrong exception abstraction level, garbage in garbage out mentality, deadline pressure to skip validation, trusted source rationalization.
27building
Execute whiteboard plans through gated phases with subagent dispatch. Require feature branch. Each phase goes through PRE-GATE (discovery + pseudocode) -> IMPLEMENT -> POST-GATE (reviewer) -> CHECKPOINT. Produce per-phase commits, execution log, and working code with tests. Use after /code-foundations:whiteboarding to implement saved plans. Triggers on: build it, execute plan, implement the whiteboard, run the plan.
1cc-debugging
Guide systematic debugging using scientific method: STABILIZE -> HYPOTHESIZE -> EXPERIMENT -> FIX -> TEST -> SEARCH. Two modes: CHECKER audits debugging approach (outputs status table with violations/warnings), APPLIER guides when stuck (outputs stabilization strategy, hypothesis formation, fix verification). Use when encountering ANY bug, error, test failure, crash, wrong output, flaky behavior, race condition, regression, timeout, hang, or code behavior differing from intent. Triggers on: debug, fix, broken, failing, investigate, figure out why, not working, it doesn't work, something's wrong.
1whiteboarding
Brainstorm and plan features through codebase search, technology research, and 2-3 approach comparison before producing implementation-ready plans. Use when starting features, designing solutions, or planning complex work. Triggers on: whiteboard, let's plan, brainstorm, design this, figure out how to build. Save plans to docs/plans/ for execution via /code-foundations:building.
1prototype
Validate technical feasibility with minimum code before full implementation. Prove ONE atomic question ('Can I X?') through 6-phase workflow: SCOPE, CONTEXT, MINIMUM, EXECUTE, VERIFY, CAPTURE. Use when facing technical uncertainty, unsure if something is possible, or need proof before planning. Triggers on: prototype, POC, prove this works, spike, demo this, can I do X, is it possible, feasibility check. Produce prototype log in docs/prototypes/ with YES/NO/PARTIAL verdict and chain to whiteboarding.
1setup-ast
Configure tree-sitter CLI and language grammars for AST-powered code review. Use when AST extraction fails, tree-sitter not found, grammars missing, or setting up new machine. Triggers on: setup tree-sitter, install grammars, AST not working, tree-sitter not found, setup ast.
1