From superpowers-docs
Manages the full documentation lifecycle: auditing, writing, revising, and maintaining docs across genres (user guides, tutorials, READMEs, brochures). Activates on any documentation task.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-docs:documentationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A doc is a set of **claims about reality**, written for a **named reader in
references/audit.mdreferences/brochure-design.mdreferences/dictionary.mdreferences/elements-of-style.mdreferences/incremental.mdreferences/marketing.mdreferences/new-docs.mdreferences/portfolio.mdreferences/single-doc.mdreferences/user-docs.mdreferences/voice.mdreferences/write-path.mdscripts/__pycache__/docmaint_test.cpython-314-pytest-9.0.3.pycscripts/__pycache__/docmaintcpython-314.pycscripts/docmaintscripts/docmaint_test.pytemplates/BROCHURE-template.mdtemplates/DICTIONARY-template.mdtemplates/INDEX-template.mdA doc is a set of claims about reality, written for a named reader in a named moment. This skill is a project's documentation department in one loop — study the project and its readers, decide the portfolio with the human, write with the genre's craft, verify adversarially, maintain as the code moves; maintenance is the same loop re-entered with a diff. The same law binds every flow: classify first, auto-fix only the determinate, route the ambiguous to the human, never rewrite a historical record, never let an uncashed claim ship. Violating the letter of these rules is violating the spirit of them. "I was bringing the docs up to date" is exactly how design docs get their history erased.
Study first, scaled to the request (next section), then the row:
| Situation | You MUST read | Study |
|---|---|---|
| No index / no docs / "set up docs" / "what docs does this project need?" | references/portfolio.md, then the genre flows | full |
| Full audit: "docs are out of date", pre-release, untrusted doc set | references/audit.md | full |
| Routine re-check of previously audited docs | references/incremental.md | micro |
| Just finished code work; update the docs that ride along | references/write-path.md | micro |
| "Document this term X"; create/extend the dictionary; term disputes; exceptions | references/dictionary.md | micro |
| "Validate and revise " — one named doc | references/single-doc.md | micro, escalates |
| Writing a brand-new engineering/contributor doc; "where does this doc go?" | references/new-docs.md | standard |
| User-facing docs: getting started, tutorial, how-to, user reference | references/user-docs.md | standard; set redesign: full |
| Adopter-facing: BROCHURE.md, the brochure site, README intro, positioning | references/marketing.md | full |
These are hard gates: do not start a flow from memory of this table. Flows add process; the law below binds all of them and is never restated in flow files.
Precedence: "validate and revise X" always enters through
single-doc.md, which reads X's Reader cell first; user and adopter docs
escalate to their genre flow and its study level — the cheap path never
skips a genre's craft law. Universal gate: no confirmed index → no
editing flow runs; bootstrap via portfolio.md / audit Phase 0 first.
Study is proportional to the request — fixed-cost front-loading is the ceremony this skill exists to avoid.
references/portfolio.md): real
readers × real moments, existing docs mapped, gaps/excess/mis-addresses
named, confirmed with the human as one batch — the genre's cast and
voice confirms ride the same gate.The single biggest failure is rewriting a dated design/plan/spec to "match the code." A spec from three months ago describing how something should work is not wrong when the code later diverged — editing it to match destroys the record.
docs/specs|plans|…). Contract: true as of its date. Drift vs.
current code is expected. Never rewrite to match code; at most add a
supersede banner or as-of date.README) → treat
the whole doc as interview-only.Classify the doc set first, at the group level (folder globs + named
exceptions), and confirm with the human before editing anything.
Precedence: a point-in-time signal (dated filename, point-in-time directory)
beats an evergreen name like README. Do not decide this per-doc by
gut as you go — surface it as one decision.
The classification confirmation is the one gate you never skip — not
under time pressure, not under authority, not under "just be decisive, don't
kick it back to me." A one-line confirm costs seconds; skipping it is what
turns an audit into an erased design record. And when classification is
genuinely ambiguous (e.g. a reference-looking file inside a specs/ folder
that also holds design docs), resolve to the safe side — treat it as
point-in-time and confirm — because a body rewrite is irreversible to the
record. Disclosing your assumption in a footnote after you've rewritten the
body is too late.
The confirmed classification persists in the doc index (Class column —
see Artifacts). Editing flows gate on it: no index → run audit Phase 0 first.
Never classify by gut mid-flow.
Default target: README, top-level *.md, docs/**, CLAUDE.md. Always
exclude: git-ignored paths, .claude/, .private-journal/, worktrees;
generated / foreign-owned docs (any "do not edit" / "generated by"
sentinel — editing them is futile, the next regeneration wipes it);
non-markdown. The dictionary (docs/DICTIONARY.md) is excluded from its own
terminology sweep.
Auto-fix a claim only when ALL hold:
git log -S, --follow, blame) before you conclude anything.Dictionary clause. In evergreen prose only, a deprecated synonym may be auto-fixed when ALL hold: the synonym maps to exactly one dictionary entry (whose heading is the replacement); the match is whole-word; no exception covers it; and the replacement leaves the surrounding sentence true. The determinant is the dictionary instead of a code counterpart — conditions 1, 4 and 5 still apply. Code identifiers, UI strings: never auto-fixed — findings only (rename / add entry / add exception). Commit messages: dictionary terms in new ones; history is never flagged.
Always interview — never auto-fix — regardless of category:
file.go:120-130) — they drift on every
edit. Recommend rewriting to file:symbol; never silently renumber.Confirming that the thing a doc names exists is not confirming the claim about it. A claim of the form "X is validated / X happens when Y / X is done by Z / X is configured as W" is verified only by the code path that enacts it — the validator that rejects, the handler that closes the stream, the function that computes the value, the line that loads the asset — not by X's mere existence. Check the verb, not just the noun.
runner" → find the
rejection in the validator, or the claim is false.internal/document" → find the call there, not just
the function's definition.<script src>, not that
Tailwind is used.This is the most common false-matches: the noun checks out, so the verifier
waves the verb through. State the mechanism, and point the citation at the
code that does the thing claimed.
The performer rule. A surface cashes a claim for a reader only if that reader is the one who performs it: operator plumbing cannot cash a user-path claim. When the addressed reader's real surface lives in another repo (a client, a plugin), cite that named external surface — and only if it exists today; otherwise the claim is roadmap.
references/marketing.md).references/elements-of-style.md is required reading before
drafting, no availability escape. Writing happens in the resolved
project voice (references/voice.md: the project's ## Voice
dictionary section, else a preset — the publication writer for
adopter artifacts, the engineer everywhere else). The independent
verifier checks voice exactly as it checks claims.The skill maintains exactly two artifacts per project, plus inline stamps. Never a third metadata file.
docs/DICTIONARY.md — normative terminology for docs, code
identifiers, commit messages, and UI strings; divergences live in its
Exceptions section, scoped by path globs only. An optional ## Voice
section (inert to docmaint's parser) carries the project voice —
references/voice.md. Template: templates/DICTIONARY-template.md;
grammar and lifecycle: references/dictionary.md. Evergreen, stamped,
and the canonical owner of terminology.<!-- doc-index:begin/end -->)
in docs/README.md, or standalone docs/INDEX.md where no README exists.
Columns: Doc | What | Reader | Class | Owns. Reader is the addressed
reader (user, operator, contributor, adopter, +-joined for
sectioned docs, — for point-in-time rows) — agent judgment, no
tooling: the cell records the addressed reader; whether the doc's
surfaces are ones that reader performs is checked by agents (the
performer rule). Class is the persisted classify-and-confirm output;
Owns is machine-readable path globs (what docmaint stale diffs). A
Decided gaps HTML comment below the fence records confirmed
won't-write decisions so future studies don't re-litigate them.
Template: templates/INDEX-template.md. (Legacy 4-column indexes from
the predecessor skill parse fine — docmaint reads column positions from
the header — and gain Reader at their next full study.)docmaint (scan | stamp | stale, --help for usage) does the
mechanical work. It never edits docs; agents do, under the rubric. It
ships in this skill's scripts/ directory — invoke it as
${CLAUDE_SKILL_DIR}/scripts/docmaint (the documented skill-content
substitution; for plugin skills it resolves to the skill's subdirectory
within the plugin), and pass --root <target-repo> unless your cwd is
already the target repo root (--root defaults to cwd). Flow files
write bare docmaint <subcommand>; this resolution rule applies
everywhere.Evergreen docs carry one idempotent block at EOF (docmaint stamp maintains
it; sentinel <!-- doc-audit:last-reviewed -->):
---
<!-- doc-audit:last-reviewed -->
_Last reviewed: 2026-06-09 · commit `abc1234` · verified against code (2 claims deferred to review)._
The SHA is provenance and the incremental cursor — a deliberate change
from the predecessor skill. Incremental re-audits are triage, not
soundness: deferred claims keep a doc on the worklist regardless of SHA;
claims with ground truth outside the repo are cleared only by full audits;
terminology never depends on stamps (docmaint scan full-sweeps every run).
Stamping precondition (all flows): no stamp without independent
verification of the applied edits — full audits use two or more competing
verifiers (Phase 3); diff- or worklist-bounded flows use at least one
independent verifier. Don't stamp point-in-time docs. Stamp only what you
verified — and any evergreen claim you could not verify this pass,
including claims whose ground truth lives outside the repo, counts toward
--deferred N. Never let an unverified claim ride under a clean stamp.
Regeneration rule. The brochure site (docs/index.html) is rendered
from docs/BROCHURE.md and carries a first-line sentinel naming
BROCHURE.md's stamp SHA. Any flow that restamps BROCHURE.md —
write-path, incremental, and audit included — compares the site's
sentinel SHA to the new stamp SHA and re-renders on mismatch
(references/marketing.md, references/brochure-design.md). One skill
owns both artifacts; a restamp without the re-render check is a defect,
not an accepted cost.
file:line citation. → Convert to file:symbol
via interview.[permanent] exception, or a [temporary] one on scan
evidence alone. → Permanent: never. Temporary: confirm via git history
first (a grep miss is not resolution).Class column. → Run
audit Phase 0 first.BROCHURE.md
behind it. → The render inherits; it never originates (marketing.md).| Excuse | Reality |
|---|---|
| "The spec says X but the code says Y, so the spec is wrong." | Only if the spec is evergreen. A point-in-time design doc is allowed to differ — classify first. |
| "It's obviously a reference doc, I'll just fix it." | Per-doc gut calls are how design docs get their history rewritten. Confirm the classification with the human. |
| "They said be decisive and not to kick decisions back — so I'll classify and rewrite myself." | The classification confirm is the one gate you never skip; it's the difference between fixing a doc and erasing a design record. A one-line confirm costs seconds. |
| "Nothing in it reads as a dated design narrative, so it's evergreen." | Absence of obvious design language isn't proof of evergreen, especially in a mixed folder like specs/. Ambiguous + destructive edit → treat as point-in-time and confirm. |
| "I disclosed my assumption at the end." | A footnote after you've rewritten the body is too late — the record is already changed. Confirm before editing, not after. |
| "The line number moved, I'll update it." | Line numbers drift on every edit; re-pinning re-breaks it. Convert to file:symbol. |
| "I'll bring the example up to the new schema." | Structural example rewrites change meaning → interview, don't auto-fix. |
| "The grep found nothing, the feature's gone." | A grep miss is not proof of removal. Check git history; it may be renamed. |
| "37 vs. ~40 is close, I'll just write the real number." | Counts have no canonical convention — hand it to the human. |
| "The symbol/route/field exists, so the claim checks out." | Existence ≠ the claim. Verify the code path that enacts it (the validator/handler/call site), not just that the noun exists. |
| "Every doc verified clean, so the docs are good." | Per-doc accuracy ≠ a healthy set. Duplication, missing docs, and cross-doc contradictions only surface at the corpus level (audit Phase 4). |
| "Scan found zero hits, the exception is resolved." | A grep miss is not resolution — confirm via git log -S first; [permanent] exceptions are never removed on scan evidence. |
| "It's a tiny doc edit, stamping without a verifier is fine." | The stamp means independently verified. No verifier, no stamp. |
| "The docs feel incomplete, I'll add a doc for each gap." | Gaps are findings. A doc with no reader is debt, not coverage. |
| "It's a brochure — the HTML is the artifact, I'll write it directly." | The render inherits from governed BROCHURE.md; claims live where stamps reach. No source doc, no render. |
| "The work is verified, so I'll commit it." | Verified ≠ reviewed. Every flow leaves the tree uncommitted for the human. |
| "While I'm in here, I'll also write the CLAUDE.md / fill the gaps." | Gaps are findings; a doc no one asked to read is debt. New docs get the born-doc gate. |
| "Getting started obviously means: clone the repo." | That's the contributor's first success. Name the primary reader; order paths by their journey. |
| "The docs are in shape — every claim verifies." | Per-doc truth ≠ the right portfolio. Study asks who reads, what's missing, what's mis-addressed. |
| "The page needs to be compelling, so the language has to lift." | A concrete benefit carries its own excitement (voice law). Uncashed lift is the slop this skill bans. |
stale output as proof of cleanliness — it is triage; soundness
comes from full audits.Provides UI/UX resources: 50+ styles, color palettes, font pairings, guidelines, charts for web/mobile across React, Next.js, Vue, Svelte, Tailwind, React Native, Flutter. Aids planning, building, reviewing interfaces.
Fetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
npx claudepluginhub prime-radiant-inc/superpowers-docs