laurigates 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:
- Move the findings into
docs/at a canonical path (e.g.docs/research/<topic>.md, or directly intodocs/format-spec/<name>.mdif the research is the spec). - If the research produced a decision, file an ADR. ADRs without a decision record are a code smell — revert to research notes.
- Update the feature-tracker entry with the
docs/path in its evidence field (blueprint-plugin:feature-trackinghandles the mechanical edit). - Only then flip the tracker status from
in_progresstodone.
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-upcommits 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 ruleblueprint-plugin:blueprint-curate-docs— mechanics of producing curated rule entriesblueprint-plugin:blueprint-sync— drift detection for generated docsblueprint-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.