diff --git a/README.md b/README.md index ac776cc..e83db64 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,7 @@ It is also the faster path. Breaking the feature into independent PRs lets the m | `reviewing-feature-progress` | Orchestration checkpoints: between fan-out waves, and before the integration PR. | | `testing-a-feature` | Writing tests for any non-trivial change. Decides the assertion shape (black-box against the contract). | | `testing-end-to-end` | A structurally-complete feature introduces a new user- or consumer-visible flow. Decides which flows earn an end-to-end test and what each asserts (golden path, not edge cases). | +| `writing-docs` | A structurally-complete feature changed public-facing docs (README, usage guide, tutorial, API/reference). Writes them to an OSS-grade bar and verifies a reader can use them via a fresh-reader test; defers docstrings, release notes, and specs to their owning skills. | | `opening-a-pull-request` | About to `gh pr create`/`edit`. Draft and ready body templates, issue-linking keywords. | | `maintaining-architectural-coherence` | Work split across PRs/agents/waves must read as one author. Invoked when agreeing conventions before parallel work, and when reviewing the merged union for structural, interface, naming, and vocabulary drift. | | `drafting-a-release` | Standalone (not part of the feature flow). About to cut a release: drafts curated release notes that explain the why, proposes the version, and gates `gh release create` on the user. | diff --git a/skills/developing-a-feature/SKILL.md b/skills/developing-a-feature/SKILL.md index e6d78af..5650e73 100644 --- a/skills/developing-a-feature/SKILL.md +++ b/skills/developing-a-feature/SKILL.md @@ -82,7 +82,7 @@ Record the choice in the state file's frontmatter as `sub_pr_approval: autonomou ### 5. Checkpoint review before opening the final PR -- **Single-PR feature** → the implementation is now structurally complete, so this is the point to add whole-flow coverage. If the change introduced a new user- or consumer-visible flow, write the end-to-end coverage now — **REQUIRED SUB-SKILL:** `feature-dev-workflow:testing-end-to-end` for which flows earn one and what each asserts. Then **REQUIRED SUB-SKILL:** `superpowers:verification-before-completion`. Run the project's test, lint, and (if it has one) typecheck commands. Paste the output. Forbids claiming "done" without evidence. +- **Single-PR feature** → the implementation is now structurally complete, so this is the point to add whole-flow coverage. If the change introduced a new user- or consumer-visible flow, write the end-to-end coverage now — **REQUIRED SUB-SKILL:** `feature-dev-workflow:testing-end-to-end` for which flows earn one and what each asserts. The behavior is settled now, so this is also the point to write or update the public-facing docs the change touches — **REQUIRED SUB-SKILL:** `feature-dev-workflow:writing-docs` for what earns a doc and how to verify a reader can actually use it. Then **REQUIRED SUB-SKILL:** `superpowers:verification-before-completion`. Run the project's test, lint, and (if it has one) typecheck commands. Paste the output. Forbids claiming "done" without evidence. - **Multi-PR feature** → **REQUIRED SUB-SKILL:** `feature-dev-workflow:reviewing-feature-progress`. The orchestrator's checkpoint skill re-reads spec + plan + state, walks every self-merged sub-PR against acceptance criteria, checks state-file integrity, and runs end-to-end verification on the main feature worktree (the feature branch as a whole, not just per-sub-PR CI). Catches drift and integration-only failures before the external-review surface opens. If the checkpoint finds gaps, route back through `feature-dev-workflow:developing-a-feature` Step 4 (follow-up sub-PR) or `feature-dev-workflow:planning-a-feature` Steps 6/7 (plan/issue refinement) before continuing. ### 6. Open the PR diff --git a/skills/reviewing-feature-progress/SKILL.md b/skills/reviewing-feature-progress/SKILL.md index d9e36dc..a6c3ce6 100644 --- a/skills/reviewing-feature-progress/SKILL.md +++ b/skills/reviewing-feature-progress/SKILL.md @@ -71,6 +71,8 @@ If anything is out of sync, fix the state file before continuing — the resumed The structure is now settled — every sub-PR merged, the coherence sweep run. This is the first point at which a whole-flow test is safe to write against real seams rather than interfaces still in motion. If the feature introduced a new user- or consumer-visible flow, write or extend the end-to-end coverage now, before running the suite. **REQUIRED SUB-SKILL:** `feature-dev-workflow:testing-end-to-end` for which flows earn an end-to-end test and what each one asserts. A feature that only extends a flow an existing test already covers may need none. +With the feature whole and its behavior settled, write or update the public-facing docs the feature touches before the integration PR opens — the integration PR is the external-review surface, and its docs are part of the first impression. **REQUIRED SUB-SKILL:** `feature-dev-workflow:writing-docs` for what earns a doc and how to verify a reader can actually use it. + **REQUIRED SUB-SKILL:** `superpowers:verification-before-completion`. Run the project-wide checks on the main feature worktree (which holds the integration state — sub-worktrees only hold their own sub-branch): ``` diff --git a/skills/writing-docs/SKILL.md b/skills/writing-docs/SKILL.md new file mode 100644 index 0000000..021989c --- /dev/null +++ b/skills/writing-docs/SKILL.md @@ -0,0 +1,78 @@ +--- +name: writing-docs +description: + Use when a feature is structurally complete and its public-facing + documentation (README, usage guide, tutorial, public API/reference) must + be written or updated — before assuming the docs are done. +--- + +# writing-docs + +## When to invoke + +When a feature is structurally complete and a consumer of the project would need docs to use, understand, or extend what changed. Especially when: + +- You just finished a feature and are about to call it shippable. +- You are about to write docs from memory and judge them done by re-reading your own draft. +- You are reaching for a diagram and about to hand-draw it in ASCII. + +The scope test, in one question: **is this read by someone consuming the project, rather than an internal record of how it was decided or built?** If yes, and no other skill owns it, it belongs here. + +## Core principle + +**A doc is a set of answers to questions a reader arrives with.** You do not know the doc works until a reader who has *only the doc* can answer those questions. + +You cannot be that reader. You carry the whole feature in your head, so the draft always "reads clearly" to you — that judgment is worthless for finding gaps. The reader who has only the page is the test. Same Iron Law as `superpowers:writing-skills`: **no doc change without a failing reader scenario first.** + +## The loop + +1. **Locate the doc surfaces and their levels.** Before writing, go find where this project's docs actually live and what each is for — a README (entry point: what it is, install, one taste, links out), a `docs/` tree or generated site / homepage (depth: task guides and exhaustive reference), a wiki (often dev-internal). Look, don't assume: check the repo for a `docs/` directory and a docs-site config, and follow the links the README already points to. Decide which surface(s) this change belongs in and at what level, and where a pointer is needed so the surfaces cross-link instead of duplicating. Don't assume the README is the only home, and don't pour reference depth into it — a project with a docs site wants the depth there and only a pointer in the README. + +2. **Name the reader personas and their questions.** Who reads this, and the concrete questions each must answer or tasks each must complete. A doc often serves two at once — a newcomer who needs zero-to-working, and an experienced reader scanning for depth. Name each, per surface where more than one is in play. The personas and their questions are the test. + +3. **RED — run the reader, do not imagine it.** Dispatch a fresh subagent per persona, given *only* the current doc text — no codebase, no outside knowledge, no access to you — and that persona's questions. Record verbatim where it cannot answer, answers wrong, or guesses. "It reads clearly to me" and "a new reader could probably follow this" are not the test; an actual fresh reader failing a question is. If every persona answers everything, the change is not needed — stop. + If you genuinely cannot dispatch a subagent, simulate the reader: answer each question using *only* the words on the page, nothing you know from building the feature. Treat that result as provisional — a real fresh-reader pass is still owed before the docs are called done. "Dispatch is unavailable" is never a license to fall back to judging your own draft. + +4. **GREEN.** Write or update the doc to close exactly those gaps. A fresh subagent per persona, given only the new doc, answers all its questions and completes its task. The novice succeeds from the early sections; the advanced reader finds depth later; the advanced material does not block the novice. That ordering is progressive disclosure — proven by the test, not asserted. + +5. **REFACTOR.** Cut anything that served no persona's question. Length is justified only by a question it answers. "Shorter" is never the goal; "no unearned content" is. + +## Device and depth selection + +A diagram, image, code block, or extra level of detail is never the default and never decoration. Each earns its place only by answering a reader's question better than prose would — and the fresh-reader test proves it did. + +- **Diagram** — when the subject is a structure, flow, or relationship prose forces the reader to reassemble in their head (architecture, state machine, request lifecycle, decision flow). Use **Mermaid**, fenced as a ```` ```mermaid ```` block. It is not a dependency and needs no build step or asset hosting: GitHub, GitLab, and most markdown viewers render it natively from the source, and it diffs as text. **Do not hand-draw ASCII diagrams** — an ASCII box-and-arrow sketch is not a rendered diagram; it misaligns across fonts, rots on edit, and reviews badly. "ASCII renders fine in plain markdown" is the trap: it renders as the literal characters you typed, not as a diagram. If a reader answers the "how does X flow through Y" question from prose alone, the diagram was decoration; cut it. +- **Image** — only when the content is genuinely visual (a real screenshot, a rendered output) that Mermaid cannot express. +- **Code block** — when the reader's question is "how do I actually do this." A copyable, complete, runnable example beats a paragraph describing the call. One excellent example over many fragments. No example for a concept the reader only needs to understand, not invoke. +- **Depth** — calibrate per persona via progressive disclosure: accessible material first, deeper material below, ordered so depth never blocks the newcomer. + +## Quality bar + +The bar is **the documentation of a well-run open-source project**: precise, structured, assumes a competent reader, earns every sentence. No marketing fluff — superlatives ("blazing-fast", "seamless", "powerful"), feature-listing without telling the reader what they can now *do*, and adjectives standing in for an explanation all fail the bar. + +## Out of scope + +These are documentation, but other skills own them. Point there; do not duplicate. + +- **Docstrings / code contracts** → `feature-dev-workflow:testing-a-feature` owns them as the contract its tests verify against. +- **Release notes / changelog "why"** → `feature-dev-workflow:drafting-a-release`. +- **Spec / ADR / plan** → `feature-dev-workflow:planning-a-feature`. These are internal records of how the work was decided and built, not consumer-facing. + +## Anti-patterns + +- **Assuming the README is the only doc home.** Writing without checking where the project's docs live. A project with a docs site or `docs/` tree wants the depth there and a pointer in the README; dumping everything into the README duplicates that content and rots. +- **Calling docs done on the strength of your own read.** You wrote them, so they always read clearly to you; that is the one judgment that cannot find a gap. Until a reader who has only the page passes, you are guessing. +- **A diagram or section that answers no reader question.** Content that survives because it "looks thorough." If no persona's question needs it, the refactor step cuts it. +- **Hand-drawing a diagram in ASCII.** An ASCII sketch is not a rendered diagram — it misaligns and rots. Use Mermaid, or prose if the relationship does not need a picture. +- **Documenting an internal artifact, or re-documenting one another skill owns.** A spec, plan, or docstring written up here as public docs creates a second source of truth. Keep to consumer-facing docs; point at the owning skill for the rest. + +## Red flags + +| Thought | Reality | +|---------|---------| +| "I'll document it in the README" | Check where the docs actually live first. If the project has a docs site or `docs/` tree, the README may warrant only a pointer to the real home. | +| "It reads clearly to me" / "a new reader could probably follow this" | You hold the whole feature in your head. Run an actual fresh reader with only the doc; your read proves nothing. | +| "I'll write the docs from what I just built and check them myself" | Self-check is not the test. The reader who has only the page is. | +| "ASCII renders fine in plain markdown, no Mermaid dependency" | It renders as literal characters, not a diagram. Mermaid is not a dependency — GitHub renders it natively from source. Use a `mermaid` block. | +| "A diagram makes it look thorough" | Decoration fails the test. A diagram is only for a flow/structure prose can't carry. | +| "More detail is safer" | Unearned content buries the answer. Every section maps to a reader question or it's cut. | diff --git a/templates/project-CLAUDE.md b/templates/project-CLAUDE.md index 0eba935..1094bdd 100644 --- a/templates/project-CLAUDE.md +++ b/templates/project-CLAUDE.md @@ -46,6 +46,7 @@ Invoke `feature-dev-workflow:planning-a-feature` at conception. It and the `**RE | The worktree fan-out loop + wave merges | `feature-dev-workflow:fanning-out-with-worktrees` | | Checkpoints between waves & before the integration PR | `feature-dev-workflow:reviewing-feature-progress` | | End-to-end tests for a new user/consumer-visible flow (once structurally complete) | `feature-dev-workflow:testing-end-to-end` | +| Public-facing docs for what the feature changed (once structurally complete) | `feature-dev-workflow:writing-docs` | | Verify-before-done | `superpowers:verification-before-completion` | | Open / flip pull requests | `feature-dev-workflow:opening-a-pull-request` |