| name | scribe |
| description | Documentation craft skill for project docs that match the code and read well. Use when writing, auditing, syncing, or extracting documentation: READMEs, API references, tutorials, how-to guides, explanations, architecture notes, changelogs, runbooks, and in-code API docs. Enforces evidence-level claims (no fabricated flags, endpoints, params, defaults, or return types), Diátaxis-aligned structure, audience fit, drift detection, and prose that earns its length. |
| version | 0.3.1 |
Scribe
Read the code before writing about it. Every claim traces to evidence or is labeled with its evidence level. No exceptions.
Glossary
One canonical term per concept. Use only these terms in all output.
| Term | Meaning |
|---|
| claim | A factual statement the doc makes about behavior, API surface, defaults, or constraints |
| evidence level | How a claim is grounded: observed, derived, stated, or absent |
| doc type | The kind of document: tutorial, how-to, reference, explanation, README, ADR, changelog, runbook, in-code API docs |
| mode | The Diátaxis mode governing structure: learning, task, information, understanding (or a non-Diátaxis mode) |
| audience | The primary reader: new user, integrator, contributor, operator, or decision-maker |
| ledger | The claim-by-claim evidence table built before drafting |
| gate | A binary (yes/no) check before handoff. Any no triggers a fix loop |
| drift | A doc claim that no longer matches the code |
| outline | The heading tree and per-section length budget drafted before prose |
Disciplines
-
No fabricated facts. Do not invent flags, routes, signatures, defaults, error codes, versions, performance numbers, or roadmap promises. Use real code, an explicit placeholder, or omit.
-
Every claim carries an evidence level. Trace claims to source lines or command output. Label the evidence level. A confident wrong sentence is worse than a missing one.
-
One doc, one job. A tutorial is not a reference. A how-to is not an explanation. Pick the mode, hold it. Mixing modes on one page is the most common documentation failure.
-
Docs are a contract. Once readers see a documented command, signature, or guarantee, they depend on it. When code changes, the doc is drift until reconciled.
Decision trace
Every run follows this sequence. This example is the gold template.
Request: "document the search CLI for pipeline integrators"
→ Inventory: read cmd/, --help, config.go; found 8 commands, SEARCH_ env prefix, exit 0/1/2
→ Picks: doc-type=how-to · audience=integrator · mode=task
→ Ledger:
--json flag exists | observed | cmd/root.go L40 | step 2 command flag
default timeout 30s | observed | config.go L18 | inline note in step 3
retries on 5xx | derived | client.go L72-88 | troubleshooting note
supports Postgres 14+ | stated | README badge | prerequisite, flagged for confirm
--format flag | absent | grep found nothing | omitted from doc
→ Draft: outline, then prose, holding task mode throughout
→ Truth-check: --help vs doc table (pass), defaults vs code (pass), links resolve (pass)
→ Gates: claims-sourced=yes, outline-holds-mode=yes, snippets-honest=yes,
defaults-match=yes, no-fabricated=yes, links-resolve=yes
→ Handoff: files changed, claims verified, drift fixed, unverified flagged
Doc flow
0. Inventory
Read the thing you are documenting before writing about it. Read references/source-evidence.md. Read references/doc-types.md.
Collect:
- Subject: what code, API, command, or system the doc describes
- Public surface: flags, commands, routes, RPCs, exported symbols, config keys, env vars, exit codes
- Real defaults and behavior: confirmed from source, not assumed
- Existing docs: what is written, what is stale, what is worth keeping
- Doc tooling: Markdown only, or a generator (Sphinx, Docusaurus, MkDocs, rustdoc, godoc, JSDoc)
- Convention source:
scribe.md, style guide, existing tone
Resolve doc type using the reader's question:
| Reader's question | Doc type | Mode | Skips |
|---|
| "Teach me by doing." | Tutorial | learning | Exhaustive options, edge cases |
| "How do I accomplish X?" | How-to | task | Teaching basics, full enumeration |
| "What exactly does this do?" | Reference | information | Narrative, opinion |
| "Why is it this way?" | Explanation | understanding | Step lists, exhaustive params |
| "What is this, should I use it?" | README | orientation | Deep API detail (link out) |
| "How is it built, why these choices?" | Architecture/ADR | decision record | Step-by-step usage |
| "What changed, what must I do?" | Changelog | versioned diff | Conceptual teaching |
| "It's on fire, what do I run?" | Runbook | operational procedure | Background theory |
| "What does this symbol do?" | In-code API docs | docstring | Tutorials, prose essays |
Identify the audience (new user, integrator, contributor, operator, or decision-maker). Read references/audience.md when the choice is unclear or shapes structure. Ambiguous request: ask once, tersely.
If scribe.md exists, read it as convention data. It overrides defaults.
Emit a compact inventory with citations before proceeding.
1. Picks
Emit before proceeding: Picks: doc-type=<x> · audience=<y> · mode=<z>. Do not change picks mid-run without re-stating them.
2. Ledger
Build the ledger before drafting. Read references/source-evidence.md.
Columns: claim | evidence level | source | in doc as
| Evidence level | Meaning | Assign when |
|---|
observed | You read the source or ran the command and saw the behavior | The exact flag, default, or route is in source |
derived | You inferred it from code patterns (a retry loop implies retries) | A code pattern implies the behavior |
stated | Someone else wrote it (README, comment) and you did not verify | A claim in docs or comments is unverified |
absent | You looked and found nothing | Nothing found after searching the relevant code |
absent claims: flag, placeholder, or cut. stated claims: mark for confirmation.
3. Draft
Write to the ledger, the audience, and the mode. Read references/prose.md. Read references/links-and-format.md.
Outline first. Draft the heading tree and length budget per section before writing sentences. Read references/structure.md. Match length to the reader's task: prose where understanding is the goal, terse tables and code blocks where lookup is the goal. Headings, ordering, and progressive disclosure are navigation, not decoration. Hold the chosen mode throughout. If the outline starts teaching inside a reference or enumerating options inside a tutorial, fix the outline.
Explore for subjective prose only. Audience, doc type, and mode already fix structure. Exploration is for the axes they do not fix: the opening hook, the central analogy, the worked-example domain. Generate 2-3 candidates on one such axis, select with a one-line rationale, then write. If the picks already determine the choice, skip it. Do not re-litigate an upstream pick.
Candidates (worked-example domain for an explanation of rate limiting):
(1) coffee shop with a fixed number of cups
(2) highway on-ramp metering light
(3) nightclub bouncer enforcing capacity
Selected: 2. Closest to the real mechanism: tokens refill over time.
Skip exploration for reference tables, flag lists, exit-code tables, changelogs, and any section with a deterministic correct shape.
Then write:
- Examples are real. Every snippet copy-pastes and works, or is a clearly marked placeholder.
- Show expected output when the reader needs to distinguish success from failure.
- Front-load. First sentence of every section answers the section's question. One canonical place per fact; link, don't duplicate.
- One mode per page. Need another mode? Link to a separate page.
State the file plan before editing.
4. Truth-check
Verify the doc against reality. Read references/verification.md.
Record: check | command/evidence | result | notes
Checks: documented flags exist (--help vs doc table), defaults match code, snippets run (when feasible), links resolve, signatures match. Snippet execution is optional and repo-dependent. Never claim a snippet works if you did not run it.
5. Gates
Apply before handoff. Any no triggers a fix. Do not hand off with a failing gate.
| Gate | Check |
|---|
claims-sourced | Every claim has an evidence level in the ledger |
outline-holds-mode | The doc stays in its declared mode throughout |
snippets-honest | No snippet is presented as working unless run or compiled |
defaults-match | Every default in the doc matches source code |
no-fabricated | No invented flags, routes, signatures, defaults, or error codes |
links-resolve | Every internal link and anchor resolves |
Fix loop: gate fails → fix the cause → re-run that gate → confirm yes. Repeat until all gates pass. The six gates summarize the per-type checks in references/slop-test.md; consult that file for the doc type in play.
6. Handoff
Include in final response: what changed (files, sections), claims corrected or verified, verification commands and results, unverified claims flagged with reason, gate results (all yes). Do not bury accuracy corrections under prose. If you fixed drift, say so plainly.
BAD/GOOD pairs
Three highest-frequency failures. Study before drafting. Read references/anti-patterns.md for the full list.
Fabricated facts:
BAD:
Use `--retry-count` to set the number of retries (default: 3).
(No --retry-count flag exists in the code.)
GOOD:
The client retries on transient errors. Retry behavior is in `client.go` L72-88.
No user-facing flag is exposed.
Mode-mixing:
BAD:
## How to configure auth
Authentication uses OAuth 2.0 with PKCE, which was designed to protect public clients
from authorization code interception attacks. To configure it:
1. Run `app auth init`
GOOD:
## How to configure auth
1. Run `app auth init`
2. Paste the client ID from your provider dashboard
3. Run `app auth verify` to confirm the token works
For background on OAuth 2.0 + PKCE, see [Authentication concepts](./concepts/auth.md).
Prose where a table fits:
BAD:
The `search` command supports several output formats. Use `--format json` for JSON,
`--format csv` for CSV, or `--format table` for a human-readable table. Default is `table`.
GOOD:
| Flag | Output | Default |
| --- | --- | --- |
| `--format json` | JSON | |
| `--format csv` | CSV | |
| `--format table` | Human-readable table | ✓ |
Invocations
| Invocation | What it does |
|---|
| (default) | Write or update one document for one audience. Follow the doc flow. |
scribe audit <doc> | Read-only audit. Do not edit. Read references/verbs/audit.md. |
scribe sync <doc> | Reconcile doc against current code: find drift, fix claims, preserve truth. Read references/verbs/sync.md. |
scribe extract <source> | Generate doc scaffolding from code, API surface, --help, OpenAPI, or proto. Read references/verbs/extract.md. |
One run = one document for one audience unless the user explicitly names more.
Audit output format
Emit findings as a severity-labeled punch list:
severity | location | what is wrong | evidence | fix
P0 | README L14 | --format flag missing | grep cmd/ found nothing | Remove row or add flag
P1 | API.md §Auth | token endpoint stale | routes.go L88: /v2/token | Update URL
P2 | README L40 | "blazing fast" no bench | no evidence found | Cut or add benchmark
P0 = factually wrong (drift, fabrication). P1 = structurally broken (wrong mode, missing critical section). P2 = quality (prose, formatting, style).
Convention artifacts
scribe.md (voice, structure, link conventions): opt-in, read references/scribe-md.md. Once present, house style wins over defaults. Drift ledger emitted in handoff or persisted at .scribe/drift.md. Per-type templates live under docs/.
Reference loading
Always load
Read these at the start of every run:
references/source-evidence.mdreferences/doc-types.mdreferences/verification.md
Load when applies
references/audience.md, references/structure.md, references/prose.mdreferences/links-and-format.md, references/code-vs-docs.mdreferences/drift-ledger.md (sync), references/scribe-md.md (conventions)references/anti-patterns.md (before drafting), references/slop-test.md (after drafting)references/verbs/audit.md, references/verbs/sync.md, references/verbs/extract.md
Never load at runtime
references/philosophy.md (human-only design rationale)examples/ (human-only, not auto-loaded)
Scope
In scope: all nine doc types, evidence-level claims, drift detection, single-doc single-audience work, optional snippet execution, Markdown and common generators. Deferred: marketing copy, blog posts, legal text, slide decks, full-site generation, cross-site IA migrations, localization, bespoke pipelines.
