sb-validate-design git:20261017.3169dcdA

Immutable. This exact content never changes and is served at /api/v1/blob/c7221bc80c249131.

---
name: sb-validate-design
description: Independently judge whether a Spec's design is ready to be built on — requirement coverage, boundary, buildability, self-containment, and architectural fit.
argument-hint: "<spec>"
---

# Validate one Spec's design

An independent verdict on whether this design can be built on.

You read and judge. You author nothing, repair nothing, and rewind nothing.

**Read-only stop rule — before any command:** whatever you find, do not run a
gate invalidation command. A `NOT_READY` verdict is information for the user;
it is not authority to change lifecycle state. In particular, invalidating the
design gate also deletes the milestone's accepted contract review. Report the
finding and stop with every gate and review record exactly as you found them.

## Apply project language style

Before authoring any artifact or user-facing prose, read:

```sh
specbind rule read language-style --for consume
```

Apply returned policy only to natural-language prose. `NO_CHANGE RULE_ABSENT`
means no additional project preference; any `ERROR` line stops the workflow.

This is not a gate — the design phase does not wait for you. It is available
before approval as a second opinion, and after approval when someone wants the
design checked by something that did not write it.

In a confirmed recovery, Plan may pass the exact `spec.yaml` path, an
accepted-review removal when present, and their captured diff as a proven
Design-rewind delta. Verify that the current path set and diff still match the
capture and that status reports state `design` with Design not reached and
review absent. Treat it as read-only lifecycle context, not as a Design finding.
Never edit it. A missing capture, mismatch, manually edited field, or additional
metadata path stops validation as an unsafe handoff.

## 1. Clear the structural checks first

```sh
specbind spec status <spec>
specbind check traceability <spec> --for-design
specbind check contracts --for-design <spec>
```

These are cheap, and a structural failure makes semantic review premature.
The Design-scoped traceability result verifies Requirements, the active
Requirement set, and Design coverage without reading a retained downstream
`tasks.yaml`. Its distinct result and `Task coverage: not evaluated (Design
scope)` line are not a claim that complete traceability passes. Tasks authoring
and approval own that later check.

Treat `spec status` as lifecycle inventory, not as the Design structural gate.
It may report `State health: inconsistent` and downstream Task diagnostics for
a retained previous plan. When `check traceability --for-design` succeeds, do
not stop or weaken the Design verdict because of those Task-only diagnostics;
report them only as later Tasks repair state. Any status diagnostic involving
Requirements or Design remains relevant and must agree with the scoped check.

The Design-scoped Contract check requires this Spec's valid Contract and every
direct consumed provider Contract/shared resource and target entry. An absent
or invalid required input is structural `NOT_READY`; do not waive it because
the provider is unfinished. Unrelated Specs and providers' own outgoing
references are outside this check, in both delivery and reverse establishment.
Its `Whole graph: not evaluated (Design scope)` result is not a complete graph
verdict. Do not substitute the whole-project check as this phase's prerequisite.
The complete graph remains mandatory at milestone Contract Review.

Read the direct provider Contracts named by the scoped check when judging the
actual consumed seams. A dependency visible in the Design but missing from its
Contract is a finding, not permission to omit that dependency from review.
`READY` settles this Spec against its current inputs. Later Design work or
Contract Review can reveal a conflict and send the owning Spec back through
the ordinary Design recovery; this validator never performs that rewind.

**Fix the review scope from CLI-owned lifecycle state before reading prose.**
`specbind check traceability <spec> --for-design` reports the exact `Active requirement set`;
that set, not any `requirement_ids` field in the Design being reviewed, is the
scope for this judgment. The status `Requirement coverage: design N/N` count is
over the same active Requirement IDs. The Requirements document is a complete persistent contract and
may retain other IDs that this milestone does not deliver. Read those retained
Requirements for context, but do not report the Design incomplete, expand its
scope, or raise a finding merely because it does not realize an inactive ID.
Validate only that CLI-reported active set. Compare Design traceability markers
with it, but never derive the review scope from those markers.

**They are not your review.** The CLI already verifies traceability markers,
active requirement coverage, and contract structure — repeating them back is not
a finding. It matters here more than anywhere: a complete set of traceability
markers is exactly what makes an unrealized requirement look covered.

## 2. Read

```sh
specbind artifact list <spec>
specbind artifact read <spec> requirements --for consume
specbind artifact read <spec> design/main --for consume
specbind artifact read <spec> contract --for consume
specbind steering list
```

Read every design artifact when the set is split. Read the research if the Spec
has one — you need to know what the design might be leaning on.

Read every Steering selector returned by the listing, one command per selector:

```sh
specbind steering read <selector> --for consume
```

Zero Steering documents is a complete answer. Do not select a subset from names
or rely on the Design author's account of project guidance. Check the Design
against the complete current Steering set as well as the Rules below. A conflict
with that guidance is a Design finding; do not silently choose which obligation
to ignore. If the listing or a required read fails, stop with `STATUS: BLOCKED`
and `BLOCKER: INPUT`, name the failed read, and return no Design verdict. Do not
judge from an incomplete input set or repair Steering in this workflow.

Then the standard:

```sh
specbind protocol read design-validation
specbind template list spec
```

Read the project's design and seam preferences through its rule surface:

```text
specbind rule read design-principles --for consume
specbind rule read contract-principles --for consume
specbind rule read design-template-selection --for consume
```

`NO_CHANGE RULE_ABSENT` for design or contract principles means that
customization is absent; the protocol still applies. Design-template selection
is required. Any `ERROR` line stops this validation. Confirm that the current
Design set contains every required template and every conditional template
whose responsibility applies to the current Requirements and repository. A
missing applicable Design is `NOT_READY`; do not create it.

When judging whether the design fits the system it enters requires real
investigation of the existing code, dispatch that as a fresh subagent with a
self-contained brief and have it return findings rather than file dumps.
Use the registered `specbind-researcher` role only when the active agent runtime
exposes named-role dispatch. A role configuration file in the project does not
by itself make that dispatch available, and there is no SpecBind CLI probe for
agent-role availability. When the runtime exposes only ordinary subagent
dispatch, use an ordinary fresh subagent directly. A named role that the runtime
does expose but whose configured model cannot start is a configuration or
environment failure, not permission to change models.

Once you dispatch a required investigation, wait for its result. If the
configured role or required investigation cannot start or complete, stop with
`STATUS: BLOCKED` and `BLOCKER: ENVIRONMENT`, name the failed role and operation,
and state that no Design verdict was completed. Do not substitute your own
investigation, another model or role, emit `READY`/`NOT_READY`, or record deferred
findings. Leave artifacts and lifecycle state unchanged. Resume independent
validation after the environment is repaired; do not ask the Design author to
revise a document merely to work around this failure.

Before dispatch, a small, bounded context read that needs no independent
investigation may stay in this context. A failed required dispatch cannot be
reclassified as that small-read path after the fact.

Everything else is a reading judgment — the criteria interlock, and splitting
them loses the picture.

Existing code is architectural context, not implementation evidence. This
validation normally runs before implementation, so code that does not yet
realize the proposed behavior is expected and is never by itself a finding.
Judge whether the design can realize the Requirements in that codebase; do not
judge whether the code already does.

## 3. Apply the deletion test

For anything the design points at rather than states — research, notes, a
ticket, the source itself — **remove it mentally and read the design again.** If
a requirement, constraint, interface, or rationale is now missing or ambiguous,
the design was depending on it.

**Research is the case that matters.** It is excluded from every gate
fingerprint and deleted at release, so a design that leans on it becomes
incomplete the moment the milestone closes — and nothing mechanical will ever
report that loss.

Code is the other one. Code says what the system does now; the design says what
it must do.

## 4. Return the verdict

Give every finding an ID scoped to this Spec's current Plan run. IDs make a
fresh revalidation auditable; they do not make the finding identity mechanical.
Identity follows the endangered Requirement or boundary and the missing or
conflicting obligation, not incidental rewording or a moved location.

```text
## Design validation
- VERDICT: READY | NOT_READY
- FINDINGS:
  - [BLOCKING|DEFERRED|RESOLVED] <finding-id> — <requirement or boundary at risk> — <where in the design> — <consequence>
```

Every finding carries a disposition. A finding with none is one nobody carries
past this report.

In the final report, state that this verdict covers the selected Spec and its
direct consumed seams, and that complete Contract Review is still required.
Keep that scope statement even for `READY` with no findings; a clean local
verdict must not sound like whole-project acceptance.

**There is no "cannot judge" verdict, and that is deliberate.** If you cannot
judge readiness from the design as written, that is the finding — the design
does not yet stand on its own — and the verdict is `NOT_READY`. Insufficient
meaning in a document is not an environment failure. The
`BLOCKED / ENVIRONMENT` stop above instead means the required review operation
could not execute; it carries no verdict about the Design.

`READY` asserts all of: every active requirement substantively realized, the
owned boundary explicit and inspectable, the work decomposable into bounded
tasks, the document carrying its own meaning, and proportionate complexity that
fits the architecture.

Every finding names what it endangers, points at where, and states the
consequence. "Section X is vague" cannot be acted on; "Section X does not
determine which component owns retry, so tasks cannot be bounded" can.

Rank by what would change the verdict, and say what the design does well when it
is true.

When the dispatch includes prior Design-validation findings, treat this as a
revalidation. Read the complete current Design independently, then account for
every prior `BLOCKING` finding ID exactly once in `FINDINGS`: reuse its ID and
mark it `RESOLVED` or still `BLOCKING`. Assign a new ID only to a materially
distinct finding. A changed description or document location does not create a
new finding when the same Requirement or boundary remains endangered by the
same missing or conflicting obligation.

Do not accept the Design author's claim that its repair succeeded as evidence.
If the supplied history is incomplete, an ID cannot be mapped confidently, or
one prior ID would need contradictory dispositions, return `NOT_READY`, state
that the comparison is incomplete or ambiguous, and do not manufacture a clean
mapping. The Plan orchestrator owns the revision limit; report the evidence and
do not recommend bypassing it.

## 5. Record deferred findings

A deferred finding needs the destination this project names, or it is not
deferred — it is dropped, and the next review raises its successor as blocking
to keep that from happening again.

```sh
specbind adapter read deferred --for consume
```

`NO_CHANGE ADAPTER_ABSENT` or `NO_CHANGE ADAPTER_SCAFFOLD` means the project has
no destination. Say so in one line and record nothing. Do not invent a place to
put it. Write only what the returned active guidance says to write. Read the
destination only far enough to avoid recording the same finding twice; nothing
in it is a source of work for you, and no entry there becomes work until a
person puts it on the Roadmap.

This adapter write happens only after the verdict. Report the exact
project-relative destination and whether you changed it so an orchestrator can
keep that phase-owned path inside the bounded unapproved-Design handoff. Do not
write any other path.

## Boundaries

- **Never edit the design or the contract.** A validator that fixes what it
  found is judging its own work.
- **Never invalidate the design gate**, whatever the verdict. That rewind
  belongs to `sb-plan` in explicit Design-phase mode, which states its cost first — it also deletes
  the milestone's accepted contract review — and requires confirmation. Your
  verdict is information; acting on it is someone else's decision.
- Approve nothing, and record no machine state.
- Do not author or revise research. That belongs to `sb-gap-analysis`.
- Report in the project's language, with the block above intact.