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.

Disciplines

1. 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.

2. 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.

3. 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.

4. 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:

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

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.

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

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.md
• references/doc-types.md
• references/verification.md

Load when applies

• references/audience.md, references/structure.md, references/prose.md
• references/links-and-format.md, references/code-vs-docs.md
• references/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.