button-up-documentation
Tidies a repo's documentation. By default collapses the design docs in docs/architecture/ into ADRs in docs/adrs/ (one decision per ADR, in the repo's own ADR format), deletes docs that are stale, duplicated, or leftover working notes, repoints links, and tightens the prose that stays with Strunk & White's rules. A tidy-only mode cleans prose and removes dead docs without touching ADRs. Then offers the same cleanup for README.md, CONTRIBUTING.md, and other docs. A bundled script inventories the docs and checks links; the skill shows a plan and waits for approval before it edits or deletes anything. Use when the user says /jbb-skills:button-up-documentation, asks to button up, clean up, consolidate, prune, or tidy docs, wants architecture or design docs turned into ADRs, asks which docs are stale or redundant, or wants a README or CONTRIBUTING tightened, even if they don't say 'ADR'.
- Version
- 1.0.0
Pinned to revision 7a3741bdc38f, so it is the text this page describes rather than whatever the author pushed since.
Files
- skills/button-up-documentation/SKILL.md
- skills/button-up-documentation/evals/_fixture/CONTRIBUTING.md
- skills/button-up-documentation/evals/_fixture/README.md
- skills/button-up-documentation/evals/_fixture/docs/adrs/ADR-001-store-jobs-in-sqlite.md
- skills/button-up-documentation/evals/_fixture/docs/adrs/ADR-002-accept-jobs-as-json-over-http.md
- skills/button-up-documentation/evals/_fixture/docs/architecture/diagram.mmd
- skills/button-up-documentation/evals/_fixture/docs/architecture/overview.md
- skills/button-up-documentation/evals/_fixture/docs/architecture/queue/design.md
- skills/button-up-documentation/evals/_fixture/docs/architecture/queue/handoff.md
- skills/button-up-documentation/evals/_fixture/docs/architecture/storage-notes.md
- skills/button-up-documentation/evals/_fixture/src/relayd/__init__.py
- skills/button-up-documentation/evals/_fixture/src/relayd/api.py
- skills/button-up-documentation/evals/_fixture/src/relayd/queue.py
- skills/button-up-documentation/evals/_fixture/src/relayd/store.py
- skills/button-up-documentation/evals/apply-approved/case.yaml
- skills/button-up-documentation/evals/apply-approved/graders/01-docsadrs-holds-two-new-files-named.md
- skills/button-up-documentation/evals/apply-approved/graders/02-each-new-adr-follows-the-existing.md
- skills/button-up-documentation/evals/apply-approved/graders/03-the-new-adrs-are-dated-20260314.md
- skills/button-up-documentation/evals/apply-approved/graders/04-the-polling-adr-names-inprocess-notification.md
- skills/button-up-documentation/evals/apply-approved/graders/05-docsarchitecturequeuedesignmd-docsarchitecturequeuehandoffmd-and-docsarchitecturestoragenotesmd-no-longer.md
- skills/button-up-documentation/evals/apply-approved/graders/06-docsarchitectureoverviewmd-and-docsarchitecturediagrammmd-still-exist-and.md
- skills/button-up-documentation/evals/apply-approved/graders/07-adr001-and-adr002-have-the-same.md
- skills/button-up-documentation/evals/apply-approved/graders/08-no-markdown-file-in-the-repo.md
- skills/button-up-documentation/evals/apply-approved/graders/09-readmemd-has-fewer-words-than-before.md
- skills/button-up-documentation/evals/apply-approved/graders/10-contributingmd-has-fewer-words-than-before.md
- skills/button-up-documentation/evals/apply-approved/graders/11-the-poll-interval-is-recorded-as.md
- skills/button-up-documentation/evals/apply-approved/graders/12-the-final-reply-lists-where-each.md
- skills/button-up-documentation/evals/apply-approved/place-files.sh
- skills/button-up-documentation/evals/apply-approved/prompt.md
- skills/button-up-documentation/evals/plan-then-stop/case.yaml
- skills/button-up-documentation/evals/plan-then-stop/graders/01-no-tracked-file-in-the-repo.md
- skills/button-up-documentation/evals/plan-then-stop/graders/02-the-plan-proposes-two-separate-new.md
- skills/button-up-documentation/evals/plan-then-stop/graders/03-the-plan-marks-docsarchitecturequeuehandoffmd-for-deletion.md
- skills/button-up-documentation/evals/plan-then-stop/graders/04-the-plan-marks-docsarchitecturestoragenotesmd-for-deletion.md
- skills/button-up-documentation/evals/plan-then-stop/graders/05-the-plan-keeps-docsarchitectureoverviewmd-and-does.md
- skills/button-up-documentation/evals/plan-then-stop/graders/06-the-reply-offers-to-clean-up.md
- skills/button-up-documentation/evals/plan-then-stop/graders/07-the-reply-ends-by-asking-the.md
- skills/button-up-documentation/evals/plan-then-stop/graders/08-the-reply-says-that-designmd-gives.md
- skills/button-up-documentation/evals/plan-then-stop/place-files.sh
- skills/button-up-documentation/evals/plan-then-stop/prompt.md
- skills/button-up-documentation/evals/tidy-only-readme/case.yaml
- skills/button-up-documentation/evals/tidy-only-readme/graders/01-every-file-under-docs-is-byte.md
- skills/button-up-documentation/evals/tidy-only-readme/graders/02-readmemd-has-at-least-25-fewer.md
- skills/button-up-documentation/evals/tidy-only-readme/graders/03-readmemd-still-holds-both-code-blocks.md
- skills/button-up-documentation/evals/tidy-only-readme/graders/04-readmemd-still-links-to-docsarchitectureoverviewmd-docsarchitecturequeuedesignmd.md
- skills/button-up-documentation/evals/tidy-only-readme/graders/05-readmemd-no-longer-contains-it-should.md
- skills/button-up-documentation/evals/tidy-only-readme/graders/06-contributingmd-is-shorter-and-still-holds.md
- skills/button-up-documentation/evals/tidy-only-readme/graders/07-the-reply-covers-the-two-files.md
- skills/button-up-documentation/evals/tidy-only-readme/place-files.sh
- skills/button-up-documentation/evals/tidy-only-readme/prompt.md
- skills/button-up-documentation/references/adr-format.md
- skills/button-up-documentation/references/feature-files.md
- skills/button-up-documentation/references/style.md
- skills/button-up-documentation/scripts/docs_inventory.py
Every link opens the file at its source, pinned to the revision this page describes.