Specification Quality Framework

This skill defines the minimum thinking floor for plans and specifications. The sections below represent what every plan must address. They are not a ceiling — if the problem demands additional analysis, add it. But these areas must not be skipped.

Where this applies at each level: for a feature-implementation parent, the queue-phase feature-summary note stays lean by design (goal, findings→tasks table, dependency edges, a pointer to non-goals — target under 2k chars) and does not carry the full disciplines below. The disciplines below apply in full to each child's task-scope note (or to specification/ diagnosis notes on schemas without a parent/child split) — that is where alternatives, blast radius, risk flags, and test strategy must actually be worked through.

The value of a spec is entirely in the thinking it forces before code is written. If a section doesn't change how you'd approach implementation, it isn't earning its place. Every sentence should either prevent a mistake or force a decision.

Specification Disciplines

These are the required areas of analysis. Each one exists because skipping it leads to a specific, recurring class of failure.

Alternatives Considered

Evaluate at least two real approaches. "Do nothing" always counts as one. For each alternative, state what it would look like and the specific trade-off that led to its rejection. If you can only think of one approach, you haven't explored the solution space — step back and look for a fundamentally different angle.

The point is not to document alternatives for posterity. It's to catch yourself before committing to an approach that has a better option sitting next to it.

Anti-pattern: strawman alternatives. "Alternative: rewrite everything from scratch. Rejected: too much work." This doesn't force any real thinking.

Open Decisions

If the spec lists open decisions, naming alternatives, or "options under consideration," resolve every one before materializing MCP work items or dispatching implementation. A spec with unresolved choices left in it is not ready to dispatch.

Mid-implementation pivots cost 5-10× the time of a pre-dispatch user round-trip. Once an agent is in a worktree, a naming change or interface change requires unwinding partial code, retracting commits, re-spec'ing the work, and re-dispatching. Resolving the same question before dispatch is a single short conversation.

The orchestrator should pause for a user round-trip rather than dispatch with ambiguity. A short pause now is cheaper than a partial implementation later.

If a decision genuinely cannot be resolved at planning time (e.g., depends on a measurement only available post-implementation), it isn't an "open decision" — it's a deliberate two-phase approach. Document it as such, scope the first phase explicitly, and create a separate work item for the second phase. Don't leave the choice latent in the spec.

Cite Contracts, Don't Restate Them

When a spec prescribes call sequences, API semantics, or any fact owned by another artifact (a tool description, a source file, another spec), cite the authoritative location and direct the implementer to verify against it before relying on it. A restated copy drifts from its source — and a spec's confident restatement reads as authority to the agent that implements it faithfully.

If the spec claims something was verified, name exactly what was checked. "Verified against source" that checked one path while prescribing another is how a partially verified claim ships a defect (two sessions of evidence: task-scope facts contradicting target files, 2026-07-27; a design prescribing advance trigger sequences that gate-block, 2026-07-31).

This discipline applies to the plan artifact as much as to spec notes. Specification notes are generated from the plan and inherit its errors silently, so plan-mode output that names a file path, tool contract, or call sequence must cite the authoritative location and be verified against it before any child item inherits it. The rule above was first installed for spec notes only (2026-07-31); the next occurrence (retro 6d562acb, 2026-08-04) originated one artifact upstream — the approved plan asserted a dispatch surface at ralph-iteration.md when the live file was skills/ralph/iteration-prompt.md, and a child's specification note and its first review verdict both inherited the wrong path. If a further occurrence still originates in a plan, treat that as evidence that prose rules cannot carry this load and add a mechanical check (every path a plan names must resolve on disk).

Semantic claims carry a file:line. Any sentence that states nullability, redaction, ownership, or an honest limit (what a guard does NOT cover) cites the file:line that establishes it. This holds for spec notes and for everything written from them — a CHANGELOG bullet, an API doc line, a hook or KDoc header comment. Historical worked case (2026-09-29, #384, a 3.x file that no longer exists): the spec and a hook header said note attribution is shown only when the caller is ADMIN and the flag is false; the code redacted only when redactNoteAttribution && !isAdmin, so it was shown when ADMIN OR the flag was false. The 4.0 rule lives at interfaces/api/v1/ops/OpsAccess.kt:22 (attributionVisible = !redactNoteAttribution || ADMIN). The error survived from spec to header because the sentence was written from intent and no line was opened. For a NEW-SURFACE claim with no code yet, cite the spec decision that fixes the behavior and mark the claim for the reviewer to confirm in the diff. Prose that is not a semantic claim needs no citation — this is not a blanket citation rule.

Verification Commands

Before writing a verification command into a spec, plan, or skill, run it twice: once on the target platform against known-good input (it must succeed) and once against known-bad input (it must fail). A command that has not been shown to fail on bad input has not been shown to verify anything — a check that silently always passes is worse than no check, because it is trusted. Record the command in the form actually executed, not a reconstruction.

Non-Goals

Name what someone might reasonably expect this work to include but that is deliberately excluded. If you cannot name a single non-goal, the scope is not tight enough.

Non-goals prevent scope creep during implementation. Without them, agents tend to gold-plate — adding adjacent improvements that weren't asked for and that introduce unplanned risk.

Blast Radius

Identify every module, file, and interface affected by the change. Trace downstream consumers — if you change a repository method signature, what tools call it? If you change a domain model default, what tests assume the old value?

This analysis exists to catch "I didn't realize changing X breaks Y" before it happens. Read references/project-concerns.md for cross-cutting constraints specific to this codebase that frequently expand blast radius in non-obvious ways.

If the blast radius touches a surface with an automated budget, ceiling, or quota test (e.g. ToolSurfaceGuardsTest), measure current headroom while writing the spec and record both the measured values and the predicted post-change values. Do not defer the measurement to implementation — by then the scope decision is already made.

Negative and exhaustive claims must name their sweep. Any claim that something does not exist or that a list is complete ("zero callers", "no stubs", "nothing depends on this", "none found", "all sites") must be written as the command that produced it plus its scope and result count — for example grep -rn "createSuspend" current/src → 0 hits (src/main + src/test). A negative claim with no named sweep is not a finding; write "not checked" instead. A sweep that covered only part of the surface states the part it covered, and the reader treats the remainder as unchecked, not as clear. The defect-class-siblings field of /implement's planning seat return template is this rule's special case for a bug's root-cause pattern.

Risk Flags

Call out the one or two things most likely to go wrong. These might be areas of tight coupling, migration complexity, concurrency concerns, or simply parts of the codebase you don't fully understand yet.

The purpose is to focus review attention where it matters and to make uncertainty explicit rather than hidden.

Test Strategy

Every plan must include a concrete test strategy. This is not "add tests" — it's a specific accounting of what will be verified and how.

Required coverage areas:

• Happy paths — the primary use cases the change enables. These confirm the feature works as intended under normal conditions.
• Failure paths — what happens when inputs are invalid, dependencies are missing, or operations fail. These confirm the system fails gracefully rather than silently corrupting state or throwing unhandled exceptions.
• Edge cases — boundary conditions specific to the change. Examples: empty collections, null/optional fields, maximum depth limits, circular references, concurrent access. Think about what a user or caller could do that you didn't explicitly design for.

For each area, name the specific scenarios you'll test. "Test edge cases" is not a strategy. "Test that circular parent references are detected and rejected with a clear error" is.

If the change modifies shared interfaces (domain models, repository contracts, tool parameters), note which existing tests may break and how you'll handle that — update them, or confirm they still pass with the new behavior.

Give every scenario a stable numbered id and an oracle source. Number scenarios sequentially (S1, S2, S3…) across all three coverage areas, and for each one record the oracle source the expected result comes from — a spec clause, a stated algorithm, or an external reference. Never "what the code returns," and never just the ticket's worked example restated as if it were independent confirmation. Stable ids let downstream artifacts map coverage back to this spec without duplicating it — most directly the needs-test-author trait's test-plan and test-manifest notes, which reference these same ids; cite the trait by name rather than restating its note schema here.

State matrix (user-visible runtime changes). Required when the change alters behaviour observed in a running session or server process: plugin hooks, hook-injected context or skill text, output styles, mod modules, server startup, config load or hot-reload, transport or REST behaviour. Otherwise the spec carries one line, State matrix: n/a - <reason> (docs-only, test-only, pure refactor, domain logic fully unit-tested, agent-read process prose). A missing line is an omission, not a decision.

• Rows (minimum set): fresh session (no prior markers or state); configured; unconfigured, one row per fallback the change reads, each with that fallback removed alone (for example no project.rootId, empty API URL, no config.yaml); reload or restart mid-use (plugin reload, server restart, config hot-reload); resume after compaction or --resume. An item may add rows; none may be dropped silently.
• Columns: terminal (interactive CLI), desktop app, headless claude -p.
• Cells: exactly one of test: <test file or S#> (only when that test's fixture actually models the row's state), live-owed: <command or steps, in the form that will be executed>, or n/a: <reason>. A desktop cell an agent cannot drive is live-owed (to the user, or carrying a deferred: <item id> suffix on its Live-owed entry), never n/a merely because an agent cannot run it.
• Owed cells: the item's session-tracking note (the orchestrator's, under the session-tracked trait) lists every live-owed cell on a **Live-owed**: line. Each entry ends run <date>: <result> or deferred: <item id>; a deferral names a tracked item, never prose. An entry with neither suffix is open, and the item does not leave work while one is open (/implement Step 4c).

The matrix lives in the item's spec note (task-scope, diagnosis or specification). A plan may carry it or point at it (/implement Step 3, "Plans carry the State matrix"); a dispatch contract only points at it and never copies its cells.

Completion Checklist

Validate spec completeness before advancing past queue phase:

• At least 2 real alternatives evaluated (not strawmen)
• No "open decisions" or "options under consideration" sections remain in the spec
• At least 1 non-goal named (scope boundary explicit)
• Downstream consumers of changed interfaces traced
• Contracts cited (with location), not restated; any "verified" claim names what was checked
• Every nullability, redaction, ownership or honest-limit claim cites the file:line that establishes it
• Verification commands proven (succeed on good input, fail on bad input)
• Automated budget/ceiling headroom measured, if the blast radius touches one
• 1-2 concrete risk flags identified
• Test scenarios named for happy paths, failure paths, and edge cases
• Scenarios carry stable numbered ids (S1…) with an oracle source recorded for each
• State matrix present for a user-visible runtime change (or one n/a line with reason); every cell test | live-owed | n/a: reason
• Shared interface breakage assessed (if applicable)

Using This Framework

This framework sets a floor. The disciplines above are the minimum required analysis. Depending on the complexity of the work, additional analysis may be warranted — performance implications, migration strategies, API compatibility concerns, or anything else that would change the implementation approach if examined carefully.

Add whatever the problem demands. The goal is a plan that lets someone implement the change confidently, understanding not just what to build but why this approach was chosen and what to watch out for.