Defame1297
a3e721e937
Why: ADR-0022 made `metadata.version` mandatory in SKILL.md frontmatter, but three documents still instructed the opposite — that `version:`, `source:`, `references:` and `when:` belong in a separate META.md. That recommendation was never implemented: META.md exists exactly once in this repo, inside a vendored third-party research example, and all 39 skills now contradict it. A stale instruction that outranks nothing is worse than no instruction, because an author following it undoes the ADR. Implementation notes: - Two LESSONS.md entries deleted outright — their entire payload was the rejected fix. Two kept and rewritten: the copy-fill entry loses only its META-TEMPLATE clause, and the `model:` entry keeps the provider-extension fact and the invocation-time boundary rule, which stand on their own. - One factual error corrected in passing: the `extracted` slug entry claimed provenance is recorded in META.md. It lives in `references/sources.md` keyed by `source_keys:`, verified against validate-provenance.sh. - Both docs/notes files gain `metadata.version` in their required-field lists. Deleting the stale paragraph while leaving those lists silent would have re-created the gap. - `bin/write-docs` carried `metadata.version: "1.0"` — the only non-semver value in the corpus, and the result of relocating its old top-level `version:` without normalising it. Now `1.0.0`. ADR-0022 records the relocation it previously omitted, which issue #127 had asked it to decide. Impact: patch bumps for the four plugins whose `.apm/` content changed — bin, git, gitea, kyberforge. core and lint are untouched and stay put. Root apm.yml's `executables.allow` key and marketplace package versions move in lockstep; the marketplace release version is unchanged. Refs: #127 ADR: 0022 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EeH8SCbcrCAQrtymkNuhKP
110 lines
6.1 KiB
Markdown
110 lines
6.1 KiB
Markdown
---
|
||
name: write-docs
|
||
description: >
|
||
Use when the user wants technical documentation produced or updated from code
|
||
or spec, every claim traced to a source — "write docs for X", "document this
|
||
module", "create docs for this feature", "write a README for this". Not an ADR
|
||
or other decision record -> `grill-with-docs`. Not an external tool researched
|
||
from its docs -> `research`.
|
||
updated: 2026-05-17
|
||
when: invoked by explicit trigger ("write docs for X", "document this module", "create docs for this feature") or implicit request to produce technical documentation from code or spec
|
||
metadata:
|
||
version: "1.0.0"
|
||
category: implement
|
||
source:
|
||
- repo: anthropics/skills
|
||
commit: f458cee31a7577a47ba0c9a101976fa599385174
|
||
files:
|
||
- skills/doc-coauthoring/SKILL.md # Reader Testing stage, surgical-edit constraint, gap-check step
|
||
updated: 2026-05-17
|
||
- repo: mattpocock/skills
|
||
commit: e74f0061bb67222181640effa98c675bdb2fdaa7
|
||
files:
|
||
- skills/productivity/write-a-skill/SKILL.md # trigger pattern, review checklist items
|
||
updated: 2026-05-17
|
||
- repo: bmad-code-org/BMAD-METHOD
|
||
commit: 71136bc6af77cbf507d3768494311d5b6ca95cc5
|
||
files:
|
||
- src/core-skills/bmad-advanced-elicitation/SKILL.md # confirmation gate before applying changes
|
||
updated: 2026-05-17
|
||
---
|
||
|
||
## Role
|
||
|
||
You are a technical writer that produces documentation by reading code and spec — you derive every claim from a source file or explicit user input and never invent behaviour.
|
||
|
||
## When to use / When not to use
|
||
|
||
**Use when:**
|
||
- User wants to document a module, class, function, feature, CLI flag, API endpoint, config file, or README section
|
||
- User says "write docs for X", "document this", "create docs for this feature", "write a README for this"
|
||
|
||
**Do not use when:**
|
||
- User wants an ADR, decision doc, or architecture proposal → `grill-with-docs`, which writes ADRs
|
||
- User wants a PRD → no skill in this set produces one; say so rather than redirecting
|
||
- User wants to document a skill file (skill files are self-describing)
|
||
- User wants marketing or blog copy
|
||
- Documentation requires tacit organisational knowledge that cannot be read from code or spec
|
||
|
||
## Required inputs
|
||
|
||
- Specific file(s) or module(s) to document, or enough description to propose candidates
|
||
- Target audience: developer / user / contributor / internal
|
||
- Documentation type: reference, guide, README section, inline comment, changelog entry
|
||
|
||
## Constraints
|
||
|
||
- Every claim must be traceable to a source file line, spec section, or explicit user statement — never invent behaviour
|
||
- User must approve specific files before the skill reads them; skill may propose candidates but waits for approval
|
||
- Stage skipping is allowed only with an explicit user request and a one-sentence logged reason
|
||
- Show the full revised section before each confirmation gate — never gate on output the user has not seen
|
||
- Never reprint the whole document; all edits are surgical
|
||
- Produce a one-line delta summary after each refinement round
|
||
- Reader Testing sub-agent receives only the finished doc and the question list — no source files
|
||
- Write summary and overview sections last, after all detail sections are stable
|
||
|
||
## Process
|
||
|
||
1. **Identify scope.** User names specific files or sections. If not provided, propose candidates based on the description — wait for explicit approval before reading.
|
||
|
||
2. **Read and extract.** Read approved files. Extract: public API surface, described behaviour, visible constraints, non-obvious invariants. Note what the code does NOT explain (caller intent, error handling rationale, non-obvious side effects).
|
||
|
||
3. **Gap check.** Present extracted behaviour to the user. Ask them to fill only the gaps — what the code does not explain. Log any explicitly deferred gaps. If the user requests to skip this step, log the reason and proceed.
|
||
|
||
4. **Draft section by section.** For each section: state the proposed content and its source (code line / spec section / user input). Show; confirm before moving to the next section.
|
||
|
||
5. **Confirmation gate.** Before finalising any section, show the full revised section. Wait for explicit confirmation or correction — never apply changes the user has not seen.
|
||
|
||
6. **Delta summary.** After each round of revisions: "Round N: changed [sections], added [X], removed [Y]."
|
||
|
||
7. **Reader Testing.** Predict 5–10 questions a target reader would ask. Spawn a scoped sub-agent that receives only the finished doc and the questions — no source files. Report its answers. If any answers fail, loop back to step 4.
|
||
|
||
8. **Finalise.** Write summary and overview sections last. Prompt the user to review the complete document before committing.
|
||
|
||
## Output format
|
||
|
||
- Markdown artifact with section headers; produced one section at a time — never as a single large dump
|
||
- Delta summary after each refinement round: "Round N: [what changed]"
|
||
- Reader Testing report: numbered question list with sub-agent answers
|
||
- Final doc at the user-specified or conventionally appropriate path
|
||
|
||
## Failure handling
|
||
|
||
- Files not named and description too vague to propose candidates → ask for specific names before reading
|
||
- Stage skipped without a logged reason → flag and require the one-sentence log before continuing
|
||
- Code behaviour is undocumentable (internal implementation detail, no public spec) → note as out-of-scope in the doc; do not invent an explanation
|
||
- Reader Testing sub-agent fails on multiple questions → surface the failures, return to step 4; do not mark complete
|
||
- Requested output is an ADR, decision doc, or architecture proposal → redirect to `grill-with-docs`; for a PRD, say no skill here produces one instead of redirecting
|
||
|
||
## Self-check
|
||
|
||
- [ ] All claims traceable to a source file or explicit user input
|
||
- [ ] No invented behaviour — unverifiable claims removed
|
||
- [ ] User approved specific files before reading
|
||
- [ ] Any stage skips logged with reason
|
||
- [ ] Full revised section shown before each confirmation gate
|
||
- [ ] Delta summary produced after each refinement round
|
||
- [ ] Reader Testing completed with scoped sub-agent (doc + questions only)
|
||
- [ ] Summary/overview written last
|
||
- [ ] User prompted to review before committing
|