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 curated .claude/rules/ entry 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 curated rule entries
• 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.