laurigates/blueprint-docs-currency

Blueprint Docs Currency

Same-commit discipline for code and documentation. This skill is the reusable version of claude-plugins' .claude/rules/docs-currency.md, refined for blueprint-driven projects.

When to Use This Skill

| Use this skill when… | Skip when… | |---------------------|------------| | Committing code that changes a public API, format spec, or error enum | Refactoring internal helpers with no external surface change | | Promoting research findings from tmp/ to docs/ | Scratch work that will not ship | | Landing an architectural decision | Implementation detail with no branching trade-off | | Advancing a tracker entry past "in progress" | Small task completion that does not cross a phase gate | | A reviewer flags missing documentation | Typo fixes or whitespace changes |

The Rule

Code + its docs land in the same commit. Research promotes to docs/ before the feature advances past "in progress." ADR-worthy decisions land with a new or updated ADR in the same commit.

Same-commit scope

| Change kind | Doc target | |-------------|-----------| | Public API / exported type | Inline docstring + reference doc under docs/api/ (or tool-appropriate) | | File-format spec | docs/format-spec/<name>.md (hand-written prose, not generated) | | Error enum / protocol code | docs/errors/<name>.md or the protocol reference | | Milestone / phase status | Feature-tracker entry + docs/PLAN.md if the phase advanced | | Architectural decision | New ADR under docs/adrs/NNNN-<title>.md | | New CLI flag or subcommand | README + relevant docs/cli/ page |

Forward-reference blueprint-plugin:blueprint-curate-docs for how to produce the prose that goes into docs/ai_docs/ when the code change surfaces an AI-context gotcha worth capturing.

Research promotion workflow

Research findings arrive in tmp/ (gitignored). Before the dependent feature advances past "in progress" in the blueprint feature tracker:

1. Move the findings into docs/ at a canonical path (e.g. docs/research/<topic>.md, or directly into docs/format-spec/<name>.md if the research is the spec).
2. If the research produced a decision, file an ADR. ADRs without a decision record are a code smell — revert to research notes.
3. Update the feature-tracker entry with the docs/ path in its evidence field (blueprint-plugin:feature-tracking handles the mechanical edit).
4. Only then flip the tracker status from in_progress to done.

See blueprint-plugin:blueprint-curate-docs for the prose-production mechanics; see blueprint-plugin:blueprint-sync for the drift detection that catches stale generated content drifting from source PRDs.

Sidecars are not documentation

| Layer | Lives at | Authoritative? | |-------|----------|----------------| | TODO.md, feature tracker JSON | Repo root or docs/blueprint/ | No — sidecar | | docs/PLAN.md, docs/roadmap.md | docs/ | Yes | | docs/format-spec/, docs/api/ | docs/ | Yes | | ADRs in docs/adrs/ | docs/adrs/ | Yes | | tmp/research/… | gitignored | No — scratch |

Sidecars record priority, status, and notes for humans. If a reader needs the information to port, debug, or onboard, it belongs in docs/, not the sidecar.

Pre-commit checklist

Before git commit, ask:

• [ ] Does this change the public API, file format, error enum, or milestone status?
• [ ] Same commit touches the corresponding docs/ file?
• [ ] Decision made → new / updated ADR in the same commit?
• [ ] tmp/research/ either empty or intentionally scratch for this change?
• [ ] Feature tracker entry's evidence field cites the new docs/ path?

If any box is unchecked, the commit is not ready. Pattern-match on what the code changed, then fix the doc gap in place.

Pre-merge checklist

Before a PR's final review:

• [ ] git log main..HEAD — each commit that touches a scoped surface has a same-commit doc edit
• [ ] find tmp -type f — empty, or the contents are scratch that should not ship
• [ ] No docs: follow-up commits planned for after merge

Deferred doc follow-ups are the failure mode this skill exists to prevent. "I'll write the spec after the code is in" is the signal to stop and write the spec now.

Quick Reference

| Signal | Action | |--------|--------| | Adding a new exported function | Same commit: update the reference doc | | Changing a binary format header | Same commit: update docs/format-spec/<name>.md | | Adding an error code | Same commit: update error enum docs | | Choosing library A over library B | Same commit: file an ADR | | Promoting tmp/research/foo.md → feature | Move to docs/ first, advance tracker second |

Related

• .claude/rules/docs-currency.md — claude-plugins' dogfood version of this rule
• blueprint-plugin:blueprint-curate-docs — mechanics of producing ai_docs prose
• blueprint-plugin:blueprint-sync — drift detection for generated docs
• blueprint-plugin:feature-tracking — tracker entry mechanics
• .claude/rules/conventional-commits.md — commit types that co-evolve with docs

Evidence: research landed without a same-commit docs/ update — the spec had to be reconstructed in a follow-up PR. The inverse pattern (same-commit code + spec) survived grep-based re-investigation months later without loss.