docs: add METHOD.md and rewrite the README around it #61

Merged

crenshawdev merged 4 commits from docs/method into main

2026-07-27 18:57:23 +00:00

crenshawdev commented

2026-07-27 18:00:29 +00:00

(Migrated from github.com)

The README documented the /cad-* surface and nothing else. The engineering method lived in agents/ and cadence-core/workflows/, which a reader never opens, and there was no home for it: DESIGN.md is a design-plan artifact, INTERNALS.md is architecture, MANIFESTO.md is positioning.

METHOD.md is that home. Once it existed, the README could stop being a spec sheet.

METHOD.md

Framed as how Cadence works under the hood, keyed to the commands and agents, with review as its own large section. Covers:

Planning's goal-backward derivation (goal → truths → artifacts → wiring → tasks), skeleton-first ordering, the three-field task anatomy, scope reduction as a lint, and the plan checker deriving truths independently before it may open the plan
Prediction-first execution, the trivial/structural deviation split with its three-attempt circuit breaker, the never-auto-fix rule for failed package installs, commit protocol, worktree safety
The parallel gate: file-list overlap is arithmetic rather than judgment, an undeclared file list forces sequential because a plan declaring nothing cannot be proven independent, and why phase_diff exists
The four-level verification ladder (exists, substantive, wired, behaves), UNCERTAIN counting toward neither side, the named failure modes of verification itself, the anti-pattern scan
The coverage definition and what follows from it
The review subsystem in depth: one procedure, the trigger/gate/mode matrix, blind merging of reviewers, the refute stance, adjudication, decision review's three-way ruling and mandatory grounding, the calibrated risk pre-filter, no self-review, why consult is not review, and what was deliberately not built
"Nothing silently passes" as the connecting thread
Traceability, debugging, the git model including the two-tier branch model and auto_close, state conventions, and the self-lint
A closing table mapping each practice to the file that enforces it

README

Rewritten, 2832 -> 2069 words.

The old one described an architecture by listing its symptoms: twenty bullets under "What's inside," six more under "What it enforces," and a reader who finished it still could not say in one sentence what they got.

It now opens on the problem it prevents, generated code that is present, plausible, and wired to nothing, then states what it costs you before what it does. The cost section sorts by stakes rather than by who the reader is, which matters because ClaudePluginHub scrapes the opening and the Discord is a mixed room. The architecture is the second beat, four consequences in prose rather than a feature list. GSD moves from paragraph three to the final section, where it belongs once the reader knows what this is.

Both bullet lists are gone. Every item in them was already covered by METHOD.md or INTERNALS.md except the parallel gate and the two-tier branch model, which went into METHOD.md in this PR rather than being dropped.

Two stale claims fixed

"22 skills" is now 23
The cross-model claim named only OpenAI and Gemini, while DeepSeek shipped in v1.2.0 and has both an adapter in review-provider.mjs and a block in templates/config.json. The paragraph above it was already correct, so the README contradicted itself.

Worth noting neither is catchable by the existing tooling: self-verify and /cad-docs-verify catch claims that are wrong, not claims that are true but incomplete. "OpenAI and Gemini" names two things that genuinely exist.

Lint wiring

METHOD.md is added to self-verify's live-prose list so it gets the same config-key, invocation and path checks as README and INTERNALS. Verified failing-capable: a bogus review.does_not_exist turns it red with {kind:'unknown-config-key', file:'METHOD.md'}.

Deliberately not extended to the INTERNALS 3b repo-path citation check, because that heuristic treats any backticked token containing a slash as a repo path and would flag METHOD.md's slash commands as missing files. All 17 real repo-path citations were verified by hand instead.

Verification

338 tests pass, 0 fail
self-verify green, and specifically no inert-config-key: all seven config keys the old README named are referenced by at least two other live surfaces, so cutting them orphaned nothing
tsc -p tsconfig.ci.json clean

The README documented the `/cad-*` surface and nothing else. The engineering method lived in `agents/` and `cadence-core/workflows/`, which a reader never opens, and there was no home for it: `DESIGN.md` is a design-plan artifact, `INTERNALS.md` is architecture, `MANIFESTO.md` is positioning. METHOD.md is that home. Once it existed, the README could stop being a spec sheet. ### METHOD.md Framed as how Cadence works under the hood, keyed to the commands and agents, with review as its own large section. Covers: - Planning's goal-backward derivation (goal → truths → artifacts → wiring → tasks), skeleton-first ordering, the three-field task anatomy, scope reduction as a lint, and the plan checker deriving truths independently *before* it may open the plan - Prediction-first execution, the trivial/structural deviation split with its three-attempt circuit breaker, the never-auto-fix rule for failed package installs, commit protocol, worktree safety - The parallel gate: file-list overlap is arithmetic rather than judgment, an undeclared file list forces sequential because a plan declaring nothing cannot be proven independent, and why `phase_diff` exists - The four-level verification ladder (exists, substantive, wired, behaves), UNCERTAIN counting toward neither side, the named failure modes of verification itself, the anti-pattern scan - The coverage definition and what follows from it - The review subsystem in depth: one procedure, the trigger/gate/mode matrix, blind merging of reviewers, the refute stance, adjudication, decision review's three-way ruling and mandatory grounding, the calibrated risk pre-filter, no self-review, why consult is not review, and what was deliberately not built - "Nothing silently passes" as the connecting thread - Traceability, debugging, the git model including the two-tier branch model and `auto_close`, state conventions, and the self-lint - A closing table mapping each practice to the file that enforces it ### README Rewritten, 2832 -> 2069 words. The old one described an architecture by listing its symptoms: twenty bullets under "What's inside," six more under "What it enforces," and a reader who finished it still could not say in one sentence what they got. It now opens on the problem it prevents, generated code that is present, plausible, and wired to nothing, then states what it costs you before what it does. The cost section sorts by stakes rather than by who the reader is, which matters because ClaudePluginHub scrapes the opening and the Discord is a mixed room. The architecture is the second beat, four consequences in prose rather than a feature list. GSD moves from paragraph three to the final section, where it belongs once the reader knows what this is. Both bullet lists are gone. Every item in them was already covered by METHOD.md or INTERNALS.md except the parallel gate and the two-tier branch model, which went into METHOD.md in this PR rather than being dropped. ### Two stale claims fixed - "22 skills" is now 23 - The cross-model claim named only OpenAI and Gemini, while DeepSeek shipped in v1.2.0 and has both an adapter in `review-provider.mjs` and a block in `templates/config.json`. The paragraph above it was already correct, so the README contradicted itself. Worth noting neither is catchable by the existing tooling: `self-verify` and `/cad-docs-verify` catch claims that are wrong, not claims that are true but incomplete. "OpenAI and Gemini" names two things that genuinely exist. ### Lint wiring METHOD.md is added to `self-verify`'s live-prose list so it gets the same config-key, invocation and path checks as README and INTERNALS. Verified failing-capable: a bogus `review.does_not_exist` turns it red with `{kind:'unknown-config-key', file:'METHOD.md'}`. Deliberately *not* extended to the INTERNALS 3b repo-path citation check, because that heuristic treats any backticked token containing a slash as a repo path and would flag METHOD.md's slash commands as missing files. All 17 real repo-path citations were verified by hand instead. ### Verification - 338 tests pass, 0 fail - `self-verify` green, and specifically no `inert-config-key`: all seven config keys the old README named are referenced by at least two other live surfaces, so cutting them orphaned nothing - `tsc -p tsconfig.ci.json` clean