The why → what → verify chain — Product / Driver / Goal / Requirement / AcceptanceCriterion

Status: open/proposed

Summary

• Designs the five entities around SDLC’s traceability chain: Product (the why), Capability (the what, already shipped), and Requirement / AcceptanceCriterion (the verify) form the chain; Driver is a standalone supplemental why-record; Goal, Requirement, and AcceptanceCriterion are deferred.
• Every unit of work should trace up to a motivation and down to a test: Task → Requirement → Capability → Product, with AcceptanceCriterion proving the Requirement.
• References point up. Each entity names its parent in the chain; containers derive the downward view via tooling — the same shape as Capability’s parent_key / contains.
• Design only. This fixes the entities’ purpose, fields-in-prose, status lifecycles, and relationship cardinality. Schemas ship per entity when a milestone scaffolds them: Product and Driver are active in D-ORMG-data-model; Goal, Requirement, and AcceptanceCriterion are deferred.
• Prefixes are fixed by the D-ORMG-data-model roster (PR, DR, G, R, AC); Specification stays deferred (the Capability body is the spec).

The missing spine of the model: how a task traces back to why it exists and forward to how it’s proven done.

Decision

Adopt the why → what → verify chain below as the target design for SDLC’s Product and SDLC layers: Task → Requirement → Capability → Product, with AcceptanceCriterion proving the Requirement. The chain closes the two gaps the current model has: a Task today is justified only by itself (no upstream why) and is proven done only by a merged PR (no declared verify). Product supplies the why; Requirement / AcceptanceCriterion supply the verify; the existing Capability is the what they hang off.

Two designed entities sit outside the chain:

• Driver is not a chain rung. It stays active as a standalone, addressable motivation record that products, decisions, and capabilities wikilink freely — every instance carries inbound references, so the attachment works without being mandated — but nothing is required to trace through it. Its stored product: ref is Driver’s own anchor, not an obligation on the rest of the chain.
• Goal is deferred (D-ORMG-data-model roster): zero instances exist, and its success-metrics territory is partly covered by Milestone success criteria today.

The verify rungs are deferred too (2026-07-19): Requirement and AcceptanceCriterion stay designed-but-unscheduled until a concrete consumer needs declared verify conditions that the Task body’s Acceptance-criteria section cannot serve — today “done” is proven by the merged PR plus per-task criteria, and no tooling reads a Requirement. Not cancelled: the design below is the activation baseline, and AcceptanceCriterion activates only with Requirement (it exists to prove one).

Why-prose therefore reaches Product directly; Drivers enrich it as supplemental records. The Requirement ↔ Capability ordering — which one points up, and where a capability-creating requirement enters — is settled at Requirement activation (see Open questions, which record the current leaning: scope, not parentage).

This is a design decision, not an implementation plan. It fixes each entity’s purpose, its load-bearing fields (described, not schema’d), its status lifecycle, and the reference direction between links. Schemas land with the milestone that schedules each entity (they “earn their way in” per the entity-model README adoption order): Product and Driver have shipped schemas; Requirement, AcceptanceCriterion, and Goal are deferred.

Context — the two gaps

Gap	Today	What the chain adds
Why	A Task stands alone; nothing records the motivation it serves.	Product roots every Capability (and the Tasks under it) in the thing being built; supplemental Drivers record the pain points, use-cases, and opportunities behind it.
Verify	”Done” = a merged PR. No declared, testable success condition lives in the model.	Requirement → AcceptanceCriterion makes the success condition an entity that a Task closes against.

The Capability layer (shipped; instances C-0001…C-0010 and later) already models what the system does. It is the hinge: Capabilities trace up to the Product, and Requirements attach to Capabilities. The chain threads through it without redesigning it.

The chain

  Product  ◀─ part of ──  Capability   (Architecture layer; shipped)
  (why: scope)             (what)
                              │ has
                              ▼
                          Requirement ─ verified by ─▶ AcceptanceCriterion
                           (what must)                  (verify: testable)
                              ▲                              ▲
                              └──────── serves ───── Task ───┘ closes against
                                                   (Work layer)

  Driver ─ product ─▶ Product   (standalone why-record: pain-point / use-case /
  opportunity — wikilinked freely as supplemental why; not a rung)

Read top-to-bottom it answers, for any node: why does this exist (walk up to Product; read any wikilinked Drivers for the fuller why), what is it (Capability), how is it proven (walk down to AcceptanceCriterion). A Task sits at the bottom, serving a Requirement/Capability and closing against the AcceptanceCriteria that prove it.

Entity design

Each entity below lists its purpose, the fields that carry meaning (prose, not schema), its status lifecycle, and where its reference to the rest of the chain lives. Common-denominator frontmatter (type, schema_version, id, status, title, created, tags, related) is per D-0004-entity-definition-architecture and omitted here.

Product — the thing being built (Product layer)

Aspect	Design
Purpose	A product this project builds and ships. Multi-instance — see PR-0001-sdlc / products/ for the canonical roster.
Key fields	Prose in body sections (Summary / What it is / Boundary); related may link vision and other narrative docs.
Status	open/draft → open/active → closed/sunset.
Reference	Root of the chain; holds no upward ref. Capabilities point at it; Drivers anchor to it.

Driver — supplemental why-record (Product layer)

A Driver is anything the system is trying to solve — a pain point, use-case, or opportunity. It is a standalone, addressable record, not a chain rung: entities wikilink Drivers freely, and nothing is required to trace through one. Its kind says which flavor:

kind	Meaning	Example
pain-point	Friction, toil, or a defect that exists today.	”PR triage is fully manual; drift compounds on every merge.”
use-case	A job-to-be-done we want supported.	”Run the project hands-off overnight and converge with no intervention.”
opportunity	Non-painful leverage worth taking.	”Self-host: the tool dogfoods its own entity model.”

Aspect	Design
Purpose	A motivating driver — pain-point, use-case, or opportunity — recorded as supplemental why for whatever wikilinks it.
Key fields	kind ∈ {pain-point, use-case, opportunity}; body sections Statement, Who/what it affects, Evidence (inline — no separate Evidence entity, deferred), Toward resolution.
Status	open/proposed → open/validated → {closed/resolved | closed/retired}.
Reference	product — names the Product it belongs to (1 Product : many Drivers). Driver’s own anchor, not an obligation on the chain.

Goal — the desired outcome (Product layer; deferred)

Goal is deferred before scaffolding: zero instances exist, and its success-metrics territory is partly covered by Milestone success criteria today. The design below is retained for if it ships.

Aspect	Design
Purpose	A measurable outcome that addresses a Driver.
Key fields	outcome (the statement), success_metrics[] (how we know it’s met — the field that distinguishes a Goal from a Driver).
Status	draft → active → {achieved | abandoned}.
Reference	addresses[] — names the Driver(s) it answers (many : many).

Capability — the what (Architecture layer; shipped)

Not redesigned here. Capability is the hinge: it traces up to the Product it belongs to (the upward ref lives on Capability, keeping the “reference points up” rule), and it self-nests via parent_key — the only stored direction since schema v2. The chain’s one implied schema change — the upward product: ref — is deferred (2026-07-29): with one product carrying the whole capability corpus, the ref is derivable noise. It activates when a second product’s capabilities create real ambiguity — the same moment a product-wide Requirement scope would stop identifying its product. See C-0001 and the entity-model README.

Requirement — what the system must do (SDLC layer; deferred)

Requirement is deferred before scaffolding (2026-07-19): per-task acceptance criteria carry the verify burden today, and no consumer reads a declared Requirement. The design below is retained as the activation baseline.

Aspect	Design
Purpose	A specific obligation the system must meet, attached to one Capability.
Key fields	statement; kind ∈ {functional, non-functional, constraint-derived, user-story} (a user-story carries the role / goal / benefit triple in its body); optional derived_from link to a Constraint for the constraint-derived kind.
Status	proposed → accepted → {satisfied | dropped}.
Reference	capability — the single Capability it attaches to (1 Capability : many Requirements).

AcceptanceCriterion — the testable unit (SDLC layer; deferred)

Defers with Requirement — it exists only to prove one.

Aspect	Design
Purpose	The atomic, testable condition that proves a Requirement. The leaf of the verify branch.
Key fields	statement; format ∈ {prose, bdd} (a bdd criterion carries the Given/When/Then triple).
Status	untested → {pass | fail | blocked}.
Reference	requirement — the single Requirement it proves (1 Requirement : many AcceptanceCriteria). Optionally records the Task/PR that verified it (verified_by), deferred to the Work-layer linkage.

Reference direction & cardinality

Every link is held by the lower / more-numerous entity and points up the chain — mirroring Task.parent_key and Capability.parent_key. Containers never enumerate their members in frontmatter; tooling derives the downward view (the contains pattern). This keeps creation cheap (a new child doesn’t edit its parent) and rename-safe (one upward wikilink per child).

Edge	Holder (ref field)	Cardinality
Product ← Capability	Capability.product (deferred — activates with a second product)	1 : many
Capability ← Requirement	Requirement.capability	1 : many
Requirement ← AcceptanceCriterion	AcceptanceCriterion.requirement	1 : many
Requirement/Capability ← Task	Task.serves[] (Work-layer, deferred)	many : many
Product ← Driver (supplemental)	Driver.product	1 : many

Worked example — C-0001 Executable Task, threaded end to end

Layer	Node	Content
Product	SDLC	The plugin that manages its own software lifecycle.
Capability	C-0001 Executable Task	A task walks idea → merged code via named operations. Traces up to the SDLC Product.
Requirement	”Driveable lifecycle”	(functional) A task at open/ready can be driven to a merged PR through operations invokable from a Claude session. capability: C-0001.
AcceptanceCriterion	”work opens a PR”	(bdd) Given a task at open/ready, when task-work runs, then a PR opens and the task reaches in-progress. requirement: the above.
Task	T-3OVF-add-orchestrate-skill	serves[] the Requirement; closing it passes the AcceptanceCriterion.
Driver (supplemental)	DR-0001 “The lifecycle is human-driven at every junction”	The SDLC loop stalls without manual scheduling; drift compounds on every merge. Wikilinked from the Product and Capability; not a hop on the walk.

The column reads as the chain: a reviewer can start at any row and walk up to the motivation or down to the proof.

What this does not decide

• Schemas. None ship here; each lands with its scheduling milestone. Product and Driver are active in D-ORMG-data-model; Requirement, AcceptanceCriterion, and Goal are deferred.
• Prefixes. Not decided here; the D-ORMG-data-model roster fixes them (PR, DR, G, R, AC) per D-0002-entity-identifier-shape.
• Status shape. Lifecycles for the unshipped entities are the intended states; whether they take the system’s major/minor form (like Task’s open/ready, which shipped Product and Driver took) is a schema-time call.
• Specification. Stays deferred — the Capability body is the spec until a Capability needs multiple independent ones.
• Evidence / Constraint depth. Evidence stays inline (deferred); Constraint is a drafted Architecture entity referenced only by the constraint-derived Requirement kind.

Open questions

• Goal vs Milestone. Both group work — Goal by outcome, Milestone by release. A Task plausibly belongs to one Milestone and serves a Requirement under one Goal. Model the dual membership if Goal ships (tracked in D-ORMG-data-model / entity-model README).
• Where the Task→chain link lives. Task.serves[] is the natural holder, but it lands with the Work-layer migration, not here. Until then the link is prose in the Task body.
• Requirement granularity. One Requirement per Capability obligation vs a thin Requirement that is mostly a bag of AcceptanceCriteria. Settle when the first real Requirement is authored.
• Requirement ↔ Capability ordering. The chain has Requirement pointing up to Capability — solution-first. Two known failures: a capability-creating requirement has no parent until the capability is invented, and a cross-cutting requirement (non-functional / constraint-derived — “every state change leaves an audit record”) binds to the product or several capabilities at once, so single-capability attachment cannot survive activation. Recorded leaning (2026-07-19): scope, not parentage — scope: capability-wikilink[], empty = product-wide, matching Constraint’s designed shape (D-3PDM-cross-project-data-model-adoption P6, whose territory the constraint-derived kind absorbed). A capability-creating requirement then enters product-wide (scope: []) or scoped to an open/planned Capability stub; requirement-decomposes-requirement, if the granularity question ever demands hierarchy, is parent_key like every other entity. Confirm at activation.

References

• D-ORMG-data-model — the roster these five entities sit in (Product / Driver active; Requirement / AcceptanceCriterion planned; Goal deferred).
• D-0003-datamodel-categorization — the five-layer categorization (Product / SDLC layers).
• D-0004-entity-definition-architecture — common frontmatter + per-entity definition surface.
• entity-model README — the design rationale and adoption order these entities follow.
• C-0001 — the Capability the worked example threads through.

---

← Back to Decisions