docs-audit

Audit one section of apps/docs/content against the source, and report every claim that no longer holds.

apps/docs/content/docs-contract.test.ts already pins the claims with exactly one authoritative source — env tables, webhook events, core Plugin names, field limits, internal links, heading anchors. Assume those are green and do not re-check them. Your job is everything that needs judgement, above all the ~150 bolded UI labels across building-with-platypus/, which nothing can see.

Never answer from memory. Every verdict cites a file and a line in the code. A claim you did not open the source for is a claim you did not check.

Step 1 — Pick the section and build the suspect pool

Audit one section per run — one top-level directory of the docs content. List what is actually there rather than working from a remembered set, so a section added since cannot be the one you never audit. Ask the user which if they did not say.

Find when the section was last touched, then list what changed in the code since:

git log -1 --format=%H -- apps/docs/content/<section>
git log <that-sha>..HEAD --oneline -- apps/backend apps/frontend packages/schemas

Drift concentrates where code moved and docs did not, so read that commit list before you read the pages — it tells you which claims to distrust.

Done when: you have the section, the last-touch SHA, and the commit list.

Step 2 — List every claim

Read each page in the section in full. Then write out every falsifiable claim it makes, each with its file:line.

A claim is anything a reader could act on and find wrong: a UI label, a field name, a menu path, a default, a limit, an ordering, a behaviour, a "this requires that", a "you cannot do X".

List every claim, not a sample. Coverage has to be a property of the procedure, because it will not be a property of your attention. A page with sixty claims produces sixty rows.

Done when: every page in the section has been read end to end and every claim is on the list with a line number.

Step 3 — Verify each claim against source

For each claim, open the code that decides it and record the verdict as doc file:line vs code file:line.

Where to look:

• UI labels, fields, menu paths → apps/frontend/app/**, apps/frontend/components/**
• limits, enums, required fields → packages/schemas/index.ts
• endpoints, status codes, errors → apps/backend/src/routes/**
• run behaviour, steps, timeouts → apps/backend/src/runs/**
• plugins, Sandboxes, tool sets → apps/backend/src/plugins/**
• deployment, env, first boot → .example.env, compose*.yaml, apps/backend/index.ts

Check exhaustive lists in both directions: everything the code has appears in the doc, and everything the doc lists exists in the code. A missing row is invisible to a reader — they cannot miss what they were never shown.

Done when: every claim has a verdict and a code citation.

Step 4 — Classify

Step 5 — Report

Rank by reader cost: what breaks a deployment first, then what wastes an hour, then what merely reads badly. Not by page order, and not by how easy the fix is.

For each finding give the doc file:line, the code file:line, what the page says, what the code does, and the proposed edit.

FRAGILE defaults to deletion, not correction. Correcting an anchorless claim resets the clock; deleting it stops the bleeding. Keep it only when it earns its maintenance — say why in the finding. Otherwise the audit's own output becomes next year's backlog.

Close with the claim count, how many you verified, and what you could not check — a claim you could not resolve is a finding, not a silence.

The honest limit

This skill is user-invoked only, so its value is bounded entirely by someone remembering to type it. Nothing schedules it and nothing reminds you. Pair it with a release checklist or /loop, or accept that the contract test is the only thing actually running.