Diff Driven Docs

Diff-Driven Docs

Stale documentation is worse than no documentation — it actively misleads. This skill treats docs as a deliverable of every code change, not an afterthought. Just as TDD enforces tests accompany code, diff-driven-docs enforces doc updates accompany changes before the workflow closes.

Step 1: Run the impact classifier (BEFORE any doc work)

Read the diff. Classify impact across 3 layers:

| Diff characteristic | Business | Technical | Audit | | --------------------- | -------- | --------- | ----- | | Internal utility / helper / type only | SKIP | CHECK | SKIP | | Test addition, no new pattern | SKIP | SKIP | SKIP | | Style / formatting change | SKIP | SKIP | SKIP | | Dependency version bump (no API change) | SKIP | SKIP | SKIP | | Routine bug fix (existing behavior corrected) | SKIP | CHECK | SKIP | | Simple refactor (behavior unchanged) | SKIP | CHECK if signatures changed | SKIP | | New exported function / hook / component | SKIP | CHECK | CHECK | | New page or route | CHECK | CHECK | CHECK | | Architectural pattern introduced | SKIP | CHECK | CREATE | | Technology choice made | SKIP | CHECK | CREATE | | Breaking change to public API | CHECK | CHECK | CREATE | | Permission or role change | CHECK | CHECK | CHECK | | Security or compliance impact | CHECK | CHECK | CREATE or UPDATE |

SKIP business docs if: no user-facing surface changed; only internal utils/types/tests modified. SKIP audit docs if: routine bug fix, style change, test addition, or simple refactor with no new pattern. ALWAYS check technical docs when hooks/components/migrations/schema/routes/exported APIs changed. CREATE an audit doc if: an architectural decision was made, a new pattern introduced, a non-obvious tradeoff accepted, or a dev six months from now would ask "why did we do it this way?"

If all three layers are SKIP: set IMPACT_LEVEL: none and emit a SKIPPED note immediately without opening any doc files.

Step 2: Write only the needed updates

Business layer

User-facing docs (README, user guide, changelog). Only when the user experience changed.

Technical layer

API references, architecture docs, code comments, CONTRIBUTING. Update when signatures, exports, patterns, or integration points changed.

Audit layer

ADRs (docs/adr/), decision records, postmortems. Create when a decision was made or a tradeoff accepted — the "why" that isn't obvious from the code.

Step 3: Verify the docs match the code

After writing, re-read the changed doc section against the actual diff. A doc that says "X now does Y" when X still does Z is worse than no doc. If you can't verify, flag it rather than guess.

Don't

• Don't write docs for SKIP-classified diffs — that's noise.
• Don't update docs that didn't change — you'll create drift.
• Don't skip the classifier and "just check everything" — that's how docs rot from over-touching.
• Don't leave a ## TODO in the doc — either write it or don't.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: romiluz13
• Source: romiluz13/auto-pi
• License: MIT

Install and usage instructions live in the source repository linked above.