git:20260806.146d8e8 to git:20260903.fa4f54c

99 added, 135 removed. Audit A to A.

---

name: ops-docs

- description: "Aggressively align, restructure, and rewrite project docs to a clean, right-sized, single-source-of-truth set — including file/folder moves, merges, deletions, and the missing docs. Concise by default; comprehensive only where earned; heavyweight/old-school types only on request."

+ description: "Align, restructure, and rewrite repository docs, or create one self-contained handoff, technical report, or whitepaper when explicitly requested. Handles moves, merges, deletions, and missing docs. Evidence-first and concise by default."

---

## OBJECTIVE

- **MAKE THE DOCS WORTH READING — AND KEEP THEM TRUE.** A newcomer should grasp the project in minutes; an expert should trust it as reference; nothing should contradict the code. Most repo docs fail all three: stale, dense, fluffy, duplicated, or mixing four jobs in one page.

- This command is **aggressive and structural by default**. It does not file a polite report, tweak a few sentences, and call clean docs "leave". It reads the repo and the code, decides the *right* doc set and layout, then **rewrites prose, cuts dead weight, splits mixed pages, merges duplicates, deletes legacy, renames/moves files and folders, and writes the missing docs** — bound only by evidence. Default run = a concrete plan you approve; `--write` executes it.

- Two non-negotiables the timid pass forgets:

- - **Alignment is the job, not a bonus.** Reconciling every doc to the current code/CLI/config/manifests is the baseline. Stale docs are worse than none — they actively mislead and erode trust. Drift is the **highest-severity defect**.

- - **Structure is in scope.** File/folder moves, merges, deletions, renames, and new files are expected outputs — not edge cases. "Only edit inside existing files" is the wrong altitude.

- The bar: **clean, clear, true, one home per fact.** Concise by default; comprehensive only where complexity earns it. Every page a human can read in the time it deserves — and not one paragraph longer.

+ Make documentation true, usable, and proportionate to its audience.

- ## THE PRIME DEFECT: DRIFT (align first)

+ Choose the mode from the user's requested outcome:

- Before style, fix truth. For **every** doc, reconcile each factual claim against the evidence — manifests, entrypoints, CLI `--help`, config keys, schemas, tests, `git log`. A claim that contradicts the code is fixed or deleted, never left. "No defect found" is only valid **after** the code cross-check — a doc you did not verify against the code is *unverified*, not *clean*.

+ - **Repository mode** maintains the canonical documentation set: align claims, remove drift and duplication, restructure files, and write missing docs.

+ - **Standalone mode** produces one self-contained handoff, technical report, whitepaper, or project dossier that can be read outside the repository.

- **Single source of truth (SSOT):** each fact lives in exactly one authoritative home; everywhere else **links**. Duplication is debt and a drift generator (the copies rot independently). The most common violation: a front-door/README that **re-hosts** the CLI table, API reference, env-var list, or full source tree that a reference doc already owns — inline reference in a README is a defect; link to the canonical home instead.

+ An explicit request to create, write, produce, hand off, or publish a document authorizes drafting the artifact now. Do not return only a plan or outline unless the user asked for one. For an ambiguous repository-wide cleanup, propose the concrete plan first; `--write` or `--apply` executes it.

- ## THE MAP — Diátaxis (classify before you write)

+ ## CORE RULES

- Four kinds of docs, four reader needs. **Never mix them in one page** — blurring them is the single biggest cause of unreadable docs. Diátaxis is a *compass, not a cage*: apply with sense, not ceremony.

+ 1. **Truth before style.** Verify claims against code, manifests, entrypoints, CLI help, schemas, tests, artifacts, and accepted decisions.

+ 2. **One canonical home per repository fact.** Link instead of maintaining competing reference tables or procedures.

+ 3. **A standalone document is a dated derivative.** It may restate the facts an outside reader needs, but it names its source revision and evidence cutoff rather than becoming a second evolving source of truth.

+ 4. **Self-contained means sufficient, not maximal.** Include what the reader needs to understand, decide, integrate, or operate; omit ceremonial and empty sections.

+ 5. **Never invent completeness.** Mark material unknowns with their impact and needed owner or evidence. Keep the artifact in draft when an unresolved fact blocks its purpose.

+ 6. **Structure is in scope.** Move, merge, rename, create, or delete files when that is the smallest clear solution. Preserve the only copy of every still-true fact.

+ 7. **Heavyweight paperwork is opt-in.** Do not create an SRS, PRD, BRD, MRD, SDD, ICD, formal V&V plan, or enterprise catalog unless requested or externally required.

- |---|---|---|---|

+ ## REPOSITORY MODE

- Diagnose by asking *which need does this paragraph serve* — then move it to the page that owns that need.

+ ### 1. Reconstruct Reality

- ## THE HOUSE STYLE — clean and clear, less is more

+ Inspect the repository type, maturity, file tree, manifests, real entrypoints, existing docs, tests, and recent history. Skim broadly, then deep-read only documents being changed or claims requiring verification.

- - **Lede first (inverted pyramid).** First 1–3 lines answer what it is / why it matters / how to start. Same rule per section and paragraph. A 100-word run-on opener is a buried lede even if it's line 1.

- - **One idea per paragraph. One job per page.** Short paragraphs, lists, scannable headings that summarize (not "Overview").

- - **Cut, don't pad.** No "Welcome", "In this section we will", "simply", "as you can see", hedging, or restating the heading. Say it in 5 words, not 20.

- - **Imperative + present tense.** "Run X." not "You can run X." No first person.

- - **Show, don't tell.** A copy-paste command that runs beats a paragraph describing it. Every command/code block must actually work.

- - **Tables for matrices only.** Compare N things across M dimensions. Never table prose; never inline a reference table the canonical doc owns — link it.

- - **One canonical home.** Each fact in one place; link, don't copy.

+ ### 2. Diagnose in Order

- **Comprehensive ≠ verbose.** Comprehensive docs are *complete and sectioned*, not padded. Depth where decisions live; brevity everywhere else.

+ 1. Drift and contradictions.

+ 2. Duplicate or competing sources of truth.

+ 3. Missing, dead, or misplaced documentation.

+ 4. Mixed reader needs and poor information architecture.

+ 5. Buried conclusions, padding, and unclear language.

- ## CONCISION BUDGETS (so "concise" is measurable)

+ Classify reader needs with Diataxis as a compass:

- | Doc | Target | Read time |

+ | Mode | Reader need | Content |

|---|---|---|

- | README | ≤ ~150 lines; value + quickstart in the first screen | ~2 min scan |

- | How-to / tutorial | one task, ~1 screen | minutes |

- | CONTRIBUTING / dev loop | the actual loop, ≤ ~1 screen | ~2 min |

- | CHANGELOG | one entry per release, newest first | lookup |

- | Reference (CLI/API/config) | as long as the surface; tabular, zero padding | lookup |

- | Architecture / design | comprehensive, but every section ledes | ~10 min |

- | Roadmap | comprehensive, phased, checkable | ~5 min |

- | ADR | ~1 page, one decision | ~2 min |

- Over budget is a smell: cut, split by Diátaxis mode, or push detail down a level. Reference and the comprehensive set may run long **only** if dense and non-padded.

- ## DECIDE THE DOC SET — three classes, named types

- Do **not** propose a generic enterprise catalog. Derive the *minimal sufficient* set from what the repo actually is (library / CLI / service / compiler / monorepo) and its maturity. Classify each candidate into one of three classes:

- **A. Concise by default** — front-line docs, kept tight:

- - `README.md` (front door: what, why, install, first run, where to go next — links to the reference, never re-hosts it)

- - how-tos / tutorials for the project's main jobs · `CONTRIBUTING.md` / dev-loop · `CHANGELOG.md` (keepachangelog + semver) · per-component `README`s next to code.

- **B. Comprehensive by nature** — earn their length; sectioned, every section ledes:

- - `docs/architecture.md` (arc42/C4 shape: drivers, context, components + boundaries, data, interfaces, decisions, risks, source-tree ownership) · `docs/roadmap.md` · `docs/data-model.md` · `docs/api-contract.md` (OpenAPI/GraphQL/proto) · ADRs under `docs/decisions/` (MADR, one decision/file) · threat model · runbook.

- - Add one only when real complexity/risk justifies it. A pre-production prototype does not need a runbook.

- **C. Heavyweight / "old-school" — ON REQUEST ONLY.** Do **not** auto-generate these; add only when the user explicitly asks, or a named external driver requires it (regulated industry, government/defense contract, formal audit, contractual deliverable). Name them, don't fabricate them:

- - `SRS` (IEEE 830) · `PRD` / `BRD` / `MRD` · `SDD` / `SDS` (IEEE 1016) · `ICD` · `SPMP` · formal `RFC` process · formal test plan / `V&V` plan.

- - Rationale: in lean/agile contexts these add overhead without proportional value; requirements/design increasingly live as ADRs, OpenAPI, and code. Offer them; don't impose them.

- Introduce Diátaxis folders (`docs/how-to/`, `docs/reference/`, …) only once the set is large enough to need them; a small repo keeps a flat `docs/`.

- ## THE EXTERNAL, SELF-CONTAINED REPORT (the all-in-one "presents outside the codebase" doc)

- Sometimes the project must present itself to readers **outside the repo** — a paper appendix, a library dossier for adopters, an external technical review. That artifact is **not** a Diátaxis in-repo page, **not** an OKR (an OKR is a goals/objectives-and-key-results planning artifact — different job), and **not** a design doc (internal; it gets *reframed* for outside readers). Name it by intent:

+ | Tutorial | Learn | Guided first success |

+ | How-to | Complete a task | Direct executable steps |

+ | Reference | Look up facts | Neutral, complete, structured facts |

+ | Explanation | Understand | Context, design, decisions, and tradeoffs |

- - **Technical Report** — objective, academic/engineering tone; informs and documents; no persuasion. Fits research repos and results write-ups.

- - **Whitepaper** — authoritative but persuasive; builds confidence for technical decision-makers; ~5–20 pages.

+ Do not force four folders onto a small project. Use the smallest document set and layout that keeps each page coherent.

- Treat it as a **DERIVED, published, self-contained artifact**, synthesized from the canonical in-repo set (architecture + concept + interfaces + results) — **never a second source of truth** (that would re-introduce the drift SSOT forbids). Rules:

+ ### 3. Plan or Execute

- - **Self-contained:** inline what an outside reader needs; **no repo-relative links** that break outside the tree; define terms it uses.

- - **Derived + dated + provenance:** state it is generated from the canonical docs at a commit/date; regenerate rather than hand-maintain in parallel.

- - **On request:** produce it only when external presentation is actually needed; keep the in-repo canonical docs as the SSOT it is rendered from.

+ Default repository-wide output is a concrete file-level plan. Execute when the user asks to edit, rewrite, apply, or write. When a path is named, keep mutations scoped to that path except for necessary inbound-link repairs.

- ## PROTOCOL

+ During execution:

- ### 1. Recon (cheap, evidence-first)

+ - align claims before polishing prose;

+ - relocate live facts before deleting obsolete files;

+ - update inbound links after moves or renames;

+ - preserve unrelated user changes and useful authorial voice;

+ - add comprehensive architecture, contract, roadmap, threat-model, or runbook documents only when the project actually earns them.

- Read, don't guess: manifests, the file tree + real entrypoints, every existing `*.md`, `git log -15`, tests. Determine repo type, maturity, public surface, audiences. Token-thrifty: skim tree + ledes; deep-read the docs you will touch. Subagents may fan out, but their "clean" verdict is a hint — you still reconcile against code before trusting it.

+ ### 4. Verify

- ### 2. Diagnose (truth → structure → style)

+ - Reconcile every changed factual claim to evidence.

+ - Run documented commands or mark them illustrative.

+ - Check links across the affected documentation set.

+ - Confirm moved facts have one authoritative home.

+ - Confirm there are no orphaned files, stale references, or unresolved placeholders.

- Per doc, in order:

+ ## STANDALONE MODE

- - **Drift/misalignment** (top severity) — claims vs code/CLI/config/manifests/tests. Verify, don't assume.

- - **Structural** — duplication across files (name the canonical home), legacy/dead docs (removed features, all-boxes-checked, superseded), name collisions, mixed-mode pages, wrong location (belongs next to code / in another doc), missing Tier-A/B docs, wrong class (heavyweight doc nothing references).

- - **Style** — buried lede, fluff/over-budget, prose-as-table, inlined reference that should link.

- Then decide the **set + layout**: the smallest set of files/folders that is clean, true, and complete.

+ Use standalone mode when the requested result is a product or engineering handoff, ownership transfer, project dossier, technical report, whitepaper, or other one-for-all document intended to travel without the repository.

- ### 3. Plan (default output)

+ Before drafting, resolve from the request or evidence:

- Emit the plan and stop (unless `--write`). Group moves by class (below). Lead with what matters most — usually the front door and the worst drift.

+ - document type and intended audience;

+ - the decision, transfer, or question it must support;

+ - scope, non-goals, status, and confidentiality;

+ - source revision, artifact versions, and evidence cutoff;

+ - output path and format when specified.

- ### 4. Execute (`--write` / `--apply`)

+ Ask one focused question only when a missing answer materially changes scope, authority, disclosure, or the document's central argument. Otherwise produce the best complete draft and label the gap.

- Apply the moves. Rewrite from evidence — every claim traces to a file, command, or config value; gaps get `[TODO: needs <owner/input>]`, never invention. **Relocate before deleting** — never destroy the only copy of a true fact. On any move/rename, **update every inbound link** and remove emptied folders. Preserve correct content and the author's voice; edit for clarity, not for its own sake.

+ ### Shared Core

- ### 5. Verify

+ Every standalone artifact contains, in a reader-appropriate order:

- Reconcile changed claims to code. Links resolve (scan the whole set). Every command/code block runs (or is marked illustrative). Each doc within budget and single-mode. No orphaned files or dangling links from moves. Report read-times before→after.

+ 1. Title, purpose, audience, status, date/evidence cutoff, and source baseline.

+ 2. Executive summary or abstract that stands on its own.

+ 3. Context, terminology, scope, and non-goals.

+ 4. Current capability or subject, with the architecture, flow, interfaces, or examples needed to understand it.

+ 5. Evidence, verification, and the boundary of what was actually proven.

+ 6. Limitations, risks, unresolved decisions, and material tradeoffs.

+ 7. Provenance and references that remain usable outside the repository.

- ## THE MOVES (what "aggressive + structural" does)

+ Add only the modules required by the document's job:

- **In-file:** hoist the lede · cut fluff · tighten (20→5 words; passive→imperative) · un-mix (split multi-mode pages) · de-stale (reconcile or delete every drifted claim) · show (command + output over description) · de-table / tableize.

+ | Type | Add |

+ |---|---|

+ | Product or engineering handoff | Delivered artifacts, setup/integration workflow, acceptance criteria and evidence, owners, support boundary, change control, next actions |

+ | Technical report | Research question, method, environment/data, results, analysis, reproducibility |

+ | Whitepaper | Decision context, problem, proposed approach, alternatives, adoption implications, recommendation |

+ | Project dossier | User value, capabilities, architecture, interfaces, operating model, evidence, roadmap boundary |

- **Structural (file/folder):**

+ Do not create companion documents unless requested. Do not leave essential context behind repo-relative links, private shorthand, undefined acronyms, or undocumented conversations. External artifacts may remain separate when the document gives their immutable identifier or version, owner, access path, purpose, and verification method.

- - **Merge** true duplicates into one canonical doc. Do **not** merge *complementary* docs that serve different Diátaxis needs (e.g. a policy doc and a runtime-config doc) — dedupe their overlapping sections via link instead.

- - **Dedupe → link:** collapse repeated content to one home + links (the SSOT fix; the usual README/reference offender).

- - **Delete** legacy/dead/superseded docs (relocate any surviving true fact first).

- - **Rename/move** to kill name collisions, put per-component docs next to code, and flatten needless single-file folders — fixing inbound links.

- - **Create** the missing docs the repo needs (front door, dev loop, an absent architecture for a non-trivial system), in the right mode and budget.

+ ### Standalone Verification

- ## THE COMPREHENSIVE SET (curate, don't merely tidy)

+ Evaluate the finished artifact as if the repository and prior conversation were unavailable:

- These prevent re-deriving decisions; keep them complete, every section leded, scannable. Hand *authoring* to the specialist commands; this command is the **curator/editor** — and curating still means aggressive de-staling, deduping, splitting, and restructuring. "Curate" is not "leave alone."

+ - Can the intended reader understand the project and the document's conclusion?

+ - Can the receiver perform the stated integration, acceptance, or next action?

+ - Does every material claim have nearby evidence or a named source?

+ - Do commands, links, citations, figures, captions, and cross-references work outside the repository?

+ - Are readiness, ownership, support, security, and limitations stated without overclaiming?

+ - Is sensitive material omitted or redacted without hiding its effect on the conclusion?

- - **architecture** (arc42/C4) · **roadmap** · **domain/data and interface contracts** · **ADRs** (MADR). Author/refresh via arch-roadmap / arch-contract / arch-diagram; reconcile and integrate here.

+ The standalone artifact itself is the primary output. Do not substitute a documentation plan, section checklist, or narration about what the document should contain.

- ## EXECUTION RULES

+ ## WRITING STANDARD

- 1. **Aggressive, structural, bounded.** Rewrite hard and move files; never invent facts, never delete the only copy of a true fact (relocate + link), never flatten a comprehensive doc into a stub.

- 2. **Align first.** Reconcile every touched doc to the code; treat drift as the top defect. "Leave" requires proof: in-budget **and** reconciled **and** single-mode **and** non-duplicative.

- 3. **One canonical home.** Deduplicate to a single source + links; a front door links to the reference, never re-hosts it.

- 4. **Decide the set + layout.** Propose the minimal set and the file/folder structure the repo needs; refuse premature/enterprise docs nothing references.

- 5. **Right mode, right budget.** One Diátaxis job per page; honor budgets; comprehensive only where earned.

- 6. **Heavyweight types on request only.** SRS/PRD/BRD/MRD/SDD/ICD/SPMP/formal-RFC — named, offered, never auto-generated.

- 7. **The external report is derived.** A self-contained Technical Report / Whitepaper is rendered from the canonical set on request, not maintained as a parallel truth.

- 8. **Test the instructions.** Run the commands you document; if it doesn't run, it isn't done.

- 9. **Default is plan; `--write` executes.** `--audit` reports hygiene only. Scope to one doc/path with `ops-docs <path>`.

+ - Lead with the outcome or operative fact.

+ - Use one idea per paragraph and scannable headings.

+ - Prefer imperative present tense for procedures.

+ - Use commands, examples, tables, and diagrams only when they carry information.

+ - Define a term once and use it consistently.

+ - Put dense supporting material in appendices only when it is necessary.

+ - Keep front-door docs short; let reference and standalone artifacts be as long as their verified subject requires.

## OUTPUT

- **Plan (default):**

+ For a repository plan, report exact files to align, rewrite, merge, move, create, delete, or leave, with evidence and the reason for each action.

- ```markdown

- # DOCS PLAN: {project} · type: {library|cli|service|…} · maturity: {…}

- ## Align (drift — do first)

- - docs/x.md — CLI table lists 6 cmds; code has 8 (build-calibration-gold, …) → reconcile to `bfm --help`.

- ## Rewrite / Split

- - README.md — buried 100-word lede + re-hosts CLI+env reference tables (owned by interfaces.md) → cut to front door (~90ln), link canonical.

- ## Structural (files/folders)

- - Merge: docs/a.md + docs/b.md (true dup) → docs/a.md.

- - Rename: docs/diagrams/architecture.md → docs/diagrams.md (name collision); fix 2 inbound links; drop empty folder.

- - Delete: docs/legacy-gp.md (superseded); relocate its one live fact to architecture.md.

- - Create: CONTRIBUTING.md (missing dev loop).

- ## External report (on request)

- - Technical Report — derived from architecture + concept + results; self-contained; only if presenting outside the repo.

- ## Leave (proven: in-budget, reconciled, single-mode, non-dup)

- - docs/reference/*.md.

- ```

+ After repository edits, report changed files, verified claims, commands and links checked, unresolved evidence gaps, and structural moves.

- **After `--write`:** per file — moves applied, read-time before→after, claims reconciled, links/commands checked, any `[TODO]`, files created/renamed/deleted with inbound links fixed.

+ For standalone mode, write one finished artifact at the requested path. When no path is given, choose a clear repository-local filename and report it. State its source baseline, evidence cutoff, status, and any blocking unknowns inside the artifact, not only in chat.

## RELATED

- - arch-roadmap · arch-contract · arch-diagram — author the comprehensive set this command curates.

- - ops-clean — repo-wide hygiene beyond docs. · ops-doctor — source/registry/generated health. · boot-concept — when the *concept* is missing, not just the docs.

+ - `arch-roadmap`, `arch-contract`, and `arch-diagram` author specialized architecture material that this skill may integrate.

+ - `ops-clean` handles repository debt beyond documentation.

+ - `ops-doctor` checks source, registry, and generated health.

+ - `boot-concept` establishes a missing product concept before documentation claims it.

## NON-GOALS

- - Not a generator of enterprise paperwork nothing reads: SRS/PRD/BRD/MRD/SDD/ICD/SPMP/formal-RFC are **on request only**.

- - Not a content fabricator — writes from evidence, marks gaps.

- - Not a timid pass — it does not leave drifted or duplicated docs in place, and it does not restrict itself to in-file edits when the layout is the problem.

- - Not a style linter — it rewrites for clarity; leave mechanical lint to linters.

+ - No invented facts, results, owners, acceptance, compatibility, or readiness.

+ - No document-count targets or formatting theater.

+ - No forced enterprise template when a short complete artifact is enough.

+ - No silent conversion of a repository cleanup into a handoff or publication.

+ - No standalone artifact maintained as an unversioned competing source of truth.