| name | document-feature |
| description | Write ONE feature doc from docs/features/INVENTORY.md, verified against the code, and open a small PR for it. Use when asked to "document <feature>", "fill in the feature doc for X", "do the next feature doc", "backfill feature docs", or when a remote agent is started with a feature name to document. |
Document Feature
Write exactly one feature doc per run, verified against the code, shipped as its own
small PR. The doc system's spec lives in docs/features/README.md; this skill is the
workflow for filling it in, one inventory row at a time.
Input
- An inventory row name (
saved-messages, concepts/race-safe-writes, etc.), or free
text describing the feature.
- No argument: open
docs/features/INVENTORY.md and pick the first undocumented row,
preferring the backfill order suggested under "Open questions".
Process
1. Load the spec and an exemplar
- Read
docs/features/README.md in full: the three buckets, frontmatter schemas,
document structure, and altitude rules. It is authoritative; this skill doesn't
restate it.
- Read one existing doc in the target bucket as the exemplar, for its register and
altitude, not just its headings:
public/configurable-sidebar.md, concepts/subscribe-then-bootstrap.md, or
architecture/sync-engine.md.
2. Verify against code (this is the whole point)
- The inventory one-liner and its "where to look" pointers are hints, not facts. The
sweep that produced them has already been wrong at least once.
docs/plans/* describes the feature we wanted, not the feature we have. Never source
a claim from a plan.- Explore the real implementation. A good cheap path: spawn an Explore agent asking for
(a) current behavior with file:line citations and (b) an explicit list of what is
absent or half-wired: TODO/FIXME markers, commented-out branches, sections that render
but are never populated, flags that nothing sets.
- Decide
status honestly. shipped only if it's fully wired end to end; building if
anything user-visible is stubbed or backend-unbacked. If the user has said a feature is
unfinished, that is authoritative over any code sweep.
public_site: true only when the doc is in public/ AND status is shipped. Building
features stay off the marketing site.
3. Write the doc
- Path:
docs/features/<bucket>/<name>.md. Frontmatter must match the README schema for
that bucket exactly (concepts get no entry_points; architecture docs get
kind: subsystem, concepts kind: concept).
- Structure per the README. Architecture docs read colleague-first: the gist, how it
works, then a "Details worth knowing" reference layer, with an explicit "you can stop
here" off-ramp. Concept docs state the principle at a level that would survive a
rewrite. Public docs: what it does, how a user experiences it, boundaries.
- A Boundaries/Status section states plainly what does NOT exist. Honest gaps beat
smooth overclaims; an unfinished edge described accurately is a feature of the doc.
- Tone: plain, casual, clear. Apply the deslopify skill's rules; at minimum
grep -c '—' <file> must return 0, and no hype words or rhetorical flourishes.
- Register: explain how it works, don't pitch it. These docs are for engineers and
agents picking the feature up (and for you later), not customers being sold to,
and that holds for
public/ docs too. Describe the machine: lead with the data
model or core mechanism, then the behavior, the way configurable-sidebar opens
on "an ordered list of sections, saved per workspace" and sync-engine on "the
engine writes server state into IndexedDB." State structure, then behavior. The
recurring failure (it took three passes on ai-companions) is the product-tour
register: a "what you get" capabilities list ("can search the web, read URLs,
run…"), benefit phrasing ("for plain capture"), imperative how-to steps, and cute
personification of an agent ("she keeps up"). All factually correct, still wrong.
Name the surface and how it behaves instead.
- Watch markdown footguns: a
+ or - that wraps to line start becomes a list bullet
and prettier will lock that in. Re-read after the pre-commit hook rewrites the file.
4. Wire it in
INVENTORY.md: link the row's name to the new doc and append ✅ (plus
"(building)" when applicable).- Cross-link
related: in both directions when a concept/subsystem/public pairing
exists.
- If verification contradicted another feature doc or the inventory, fix that in the
same PR and call it out. Drift discoveries are a deliverable, not a distraction.
5. Ship a small PR
- One doc per PR. Branch from a freshly fetched main:
git fetch origin main && git checkout -b docs/feature-<name> origin/main.
- Commit as
docs(features): add <bucket>/<name>, push, and open the PR with the
create-pr skill. If gh is unavailable (web/remote session), fall back to the
github-api-web skill.
- PR body, written to be read on a phone: what was verified and how, the status call and
why, any drift discovered, and what was deliberately left out of scope.
Guardrails
- Docs only. If verification surfaces a product bug, flag it in the PR body; don't fix
code in this PR.
- One doc per run. If the chosen row turns out to be two docs (see the granularity
notes in INVENTORY's open questions), write the narrower one and record the call in
the PR body.
- Don't rewrite an existing doc unless verification proves it wrong; when it does, say
exactly what was wrong and how you know.
