Hardware Development · stage 2 of 6

Requirements

External / Ask gate

Functional, safety, and regulatory requirements

Requirements

Capture what the hardware product must do and the frameworks it must satisfy: functional specifications, safety requirements, environmental envelope, reliability targets, and regulatory compliance obligations. These constrain every downstream decision and behave as hard gates — regulatory frameworks especially cannot be retrofitted without redesigning the board and redoing the cert sweep.

Scope

Requirement capture and framework identification: testable functional and non-functional requirements, hazard analysis and fail-safes, the operating envelope, reliability targets, and the applicable regulatory regimes for the product class. Requirements decides what the product must satisfy — not how it's built to satisfy it (design, firmware) or whether it actually does (validation).

What to do

  • Write each requirement to be testable, with a unique ID and a stated verification approach.
  • Identify every regulatory framework applicable to the product class and target markets, with applicability evidence and cost/lead-time impact.
  • Keep traceability — back to inception's findings and forward to validation's tests.
  • Treat safety and regulatory requirements as hard gates, naming hazards, failure modes, and fail-safes explicitly.

What NOT to do

  • Don't design the product against the requirements — schematic, layout, and enclosure are the design stage.
  • Don't reopen the market or product-class decision inception already made.
  • Don't write an aspirational requirement that has no verification approach.
  • Don't defer a regulatory framework to "figure out later"; a missed emissions class fails cert and forces a redesign.

How the engine runs this stage

1Elaborate

collaborative · plan the work, fan out discovery, declare outputs

Discovery fan-out

knowledge artifactFunctional RequirementsComplete, testable, traceable specification of what the product does.

Functional Requirements

Complete, testable, traceable specification of what the product does.

Content Guide

Functional Requirements

Every requirement tagged with a unique identifier (e.g., FR-001, FR-002). Each requirement is:

  • Testable — can be verified by a specific test
  • Unambiguous — no subjective language
  • Traceable — linked back to discovery and forward to validation

Non-Functional Envelope

  • Power — peak, average, sleep
  • Thermal — operating range, max junction temp
  • Mechanical — dimensions, weight, mounting
  • Environmental — operating temp, humidity, ingress (IP rating), shock/vibration

External Interfaces

  • Every port, wire, wireless protocol with version and pinout if applicable

Lifetime and Reliability

  • Expected operating hours
  • Duty cycle
  • MTBF target if relevant
  • Field lifetime

Quality Signals

  • Every requirement has a unique ID
  • Every requirement is testable
  • Non-functional envelope is quantified, not qualitative
  • No requirement says "adequate" or "reasonable"
knowledge artifactSafety AnalysisHazard identification, failure modes, and regulatory compliance map for the product.

Safety Analysis

Hazard identification, failure modes, and regulatory compliance map for the product.

Content Guide

Applicable Regulatory Frameworks

Enumerated per target market: FCC/CE/UL/FDA/IC/RoHS/REACH/WEEE/IEC and any industry-specific standards. For each: certification path, test lab candidates, rough cost, and timeline.

Hazard Analysis

For each identified hazard:

  • Hazard description — what can go wrong
  • Likelihood — how often, under what conditions
  • Severity — consequence if it occurs
  • Mitigation — how design, firmware, or user interface prevents or handles it
  • Residual risk — what remains after mitigation

Failure Modes

  • Electrical failure modes (shorts, opens, overcurrent, ESD)
  • Mechanical failure modes (drop, vibration, ingress)
  • Thermal failure modes (overheat, thermal runaway)
  • Software failure modes (hang, crash, bad state)
  • Per failure mode: fail-safe behavior

Standards to Design Against

Specific standards the product must meet with section references where relevant.

Quality Signals

  • Every target market has its applicable frameworks identified
  • Every hazard has severity, likelihood, and mitigation
  • Fail-safes are specified, not hoped for
  • Cert cost and timeline are estimated, not deferred

Phase guidance

phase overrideELABORATIONHardware requirements is a **research / specification** stage. Its units are knowledge topics capturing functional, safety, and regulatory requirements. Requirements drive every downstream stage — design, firmware, manufacturing, validation. Defects here cascade into PCB redesigns, certification failures, and recalls. Be strict.

Hardware Requirements Stage — Elaboration

Hardware requirements is a research / specification stage. Its units are knowledge topics capturing functional, safety, and regulatory requirements. Requirements drive every downstream stage — design, firmware, manufacturing, validation. Defects here cascade into PCB redesigns, certification failures, and recalls. Be strict.

This stage straddles research (gather and synthesize requirements) and specification (formalize them into testable obligations). Each unit is one requirement domain, not one feature.

What a unit IS in this stage

One requirement domain. Examples:

  • "Functional requirements: power management"
  • "Functional requirements: connectivity (Wi-Fi/BLE/wired)"
  • "Safety requirements: thermal management"
  • "Safety requirements: overcurrent and short-circuit protection"
  • "Regulatory: FCC Part 15B emissions framework and applicability evidence"
  • "Regulatory: CE LVD and RED applicability"
  • "Environmental requirements: operating range, ingress protection, vibration"
  • "Reliability requirements: MTBF target and failure-mode analysis approach"

What a unit is NOT in this stage:

  • ❌ A schematic, BOM, or PCB layout (those belong in design)
  • ❌ Firmware code or bring-up procedures (those belong in firmware)
  • ❌ Manufacturing process specs (those belong in manufacturing)
  • ❌ A test plan execution (those belong in validation — but the requirements DO specify what must be testable)

What "completion criteria" means here

Requirements are testable obligations, not executable code. Criteria here describe what must be specified for downstream stages to verify against.

Good criteria — substantive and checkable

  • "Functional §2 lists every functional requirement with a measurable outcome (e.g., 'powers on within 500ms of switch press', 'connects to a known SSID within 5s of cold boot')"
  • "Safety §3 lists every hazard with: failure mode, mitigation, and fail-safe behavior — no hazard without all three"
  • "Regulatory §4 names the framework (e.g., 'FCC Part 15B'), cites the specific CFR or EN section, and provides applicability evidence (product class, deployment region, intended use)"
  • "Each requirement has a verification approach (test type: unit / system / regulatory / field) so downstream validation can author the test"
  • "Open questions: regulatory open questions MUST default to (needs human escalation) — agents do not have authority to defer regulatory framework decisions"

Bad criteria — vague or wrong-stage language

  • ❌ "Product is safe" (no specific hazard, no mitigation, no fail-safe)
  • ❌ "Compliant with applicable regulations" (which? cite them)
  • ❌ "Each unit has 3-5 verify-commands" (build-stage language; requirements don't have shell commands)
  • ❌ "Schematic implements the requirements" (wrong stage; design owns the schematic)

Anti-patterns

  • Soft regulatory language. "We'll figure out FCC later" is a hard reject. Regulatory frameworks cannot be retrofitted; pre-design lock-in is the whole point of this stage.
  • Functional-safety contradictions. A "high-throughput mode that bypasses overcurrent" is a contradiction; the mitigation exists to enforce safety. Reconcile or escalate.
  • Drifting into design. "Use the XYZ chipset" is a design decision, not a requirement. Requirements describe what must be true; design picks how to achieve it.

Note on the universal FSM_CONTRACTS_ELABORATE_BLOCK: the orchestrator currently injects build-class rules (depends_on: cycles, executable quality_gates:, criteria-with-verify-commands) into every elaborate dispatch. Those rules are correct for build-class stages but do not apply to this stage's requirement-spec units (which are testable obligations, not executable artifacts). Treat the build-class rules as defaults the framework hasn't yet split — author your units to the substance/testability shape above. (Architecture §7 known issue tracking the split.)

2Review

pre-execute · agents audit the planned spec before any code lands
review agentRegulatory CoverageThe agent **MUST** verify every target market identified in inception has its applicable regulatory frameworks named, applicability evidence documented, and a cert path planned. Regulatory gaps caught at requirements are correctable; the same gaps caught at validation mean cert failures, ship-date slips, and PCB respins.

Mandate: The agent MUST verify every target market identified in inception has its applicable regulatory frameworks named, applicability evidence documented, and a cert path planned. Regulatory gaps caught at requirements are correctable; the same gaps caught at validation mean cert failures, ship-date slips, and PCB respins.

Check

The agent MUST verify, filing feedback for any violation:

  • Per-market framework coverage — Every target market named in inception has its applicable framework categories identified: emissions / immunity, electrical safety, restricted-substance / environmental, industry-specific (medical / automotive / industrial / aviation / marine / food-contact as the product class triggers), wireless / network protocol, and cybersecurity where applicable.
  • Applicability evidence per framework — Every framework named has a product-class assertion, intended-use statement, and deployment region backing applicability. Vague applicability is what makes cert-lab submissions bounce.
  • Cert path planned — Each framework has at least the cert-route category identified (self-declaration with technical file, certified-lab submission, accredited-lab plus regulator notification, etc.). The specific cert-lab pick is a validation-stage concern; the route category belongs here.
  • Cost and lead-time category — Each framework has a documented cost and lead-time category fed back into the cost envelope and the project schedule. "TBD" is a finding, not a placeholder.
  • Standards-driven design constraints surfaced — Every framework that forces a design constraint (mandatory isolation gap, EMI / EMC layout practice, restricted material, mandatory user-facing label, intended-use disclaimer, cybersecurity update requirement) is captured for the design stage to satisfy. Constraints with no carrier into design become cert findings.
  • Regulatory open questions escalated — Every regulatory open question has (needs human escalation) as its disposition. Defaults on regulatory questions are not acceptable.

Common failure modes to look for

  • A target market named but the framework set assumed from a different market (consumer-electronics frameworks on an industrial product)
  • A framework with no applicability evidence — names the framework but doesn't say why this product is in scope
  • Cost or lead-time category recorded as "TBD" or omitted, leaving the cost envelope unable to absorb cert reality
  • A standards-driven design constraint (creepage gap, shielding requirement, mandatory labelling) buried in prose instead of called out for the design stage
  • A regulatory open question defaulted instead of escalated — "we'll figure out FCC later" is not a default
  • A radio module added in requirements without the corresponding intentional-radiator framework picked up in the framework table
review agentTraceabilityThe agent **MUST** verify every requirement is traceable backward to a user need from inception and forward to a verification approach the validation stage can author tests against. Traceability gaps caught here are corrections; the same gaps caught at validation become "untestable requirement" findings that block release.

Mandate: The agent MUST verify every requirement is traceable backward to a user need from inception and forward to a verification approach the validation stage can author tests against. Traceability gaps caught here are corrections; the same gaps caught at validation become "untestable requirement" findings that block release.

Check

The agent MUST verify, filing feedback for any violation:

  • Unique identifiers — Every requirement has a unique ID in the project's declared scheme. ID collisions across units are a hard failure.
  • Backward traceability — Every requirement traces back to at least one of: an inception finding (user need, market segmentation, business-case driver), a regulatory framework requirement, a safety hazard, an environmental envelope claim, or a recorded decision-register entry. A requirement with no upstream source is a candidate for scope creep.
  • Forward testability — Every requirement has a verification approach — test type (unit / system / regulatory / field), test method (instrument-based measurement / inspection / analysis / demonstration), and a measurable threshold where applicable. "Verify by inspection" with no inspection criterion is not a verification approach.
  • Cross-unit consistency — A requirement that references a sibling unit's requirement uses the real ID, not a placeholder. Dangling cross-references (see REQ-FN-XX) are a hard failure.
  • Category fit — Each requirement is in a unit whose category matches it. Functional requirements in safety units, regulatory requirements in functional units, etc., are findings.
  • Coverage map — Every inception-stage finding that downstream stages depend on has at least one requirement covering it (or an explicit "not covered — out of scope" with rationale). Silent gaps in coverage are how scope drift enters.

Common failure modes to look for

  • A requirement that quotes an inception finding verbatim without giving it a verification approach (the finding is stated; the requirement on top of it isn't)
  • A requirement whose verification approach is "verify in validation" with no specifics — that just defers the work
  • Two units with the same requirement ID (collision) or two requirements in one unit with the same ID
  • A regulatory framework named in the compliance-officer's section that has zero corresponding requirements in the unit — the framework was named but never carried into testable obligations
  • An inception finding (target user, market, business-case driver) with no requirement coverage — scope drift if intentional, gap if not
  • A see REQ-FN-XX placeholder cross-reference that survives into the artifact

3Execute

per-unit baton · Systems Engineer → Compliance Officer → Distiller → Verifier
hat 1Compliance OfficerIdentify every regulatory framework that applies to this product in its declared target markets, document the applicability evidence (product class, intended use, deployment region), and surface the cost / lead-time impact of certification so downstream stages can plan against it. Compliance cannot be retrofitted — get the framework set right at this stage, or pay an order of magnitude more to redesign and re-cert later.

Focus: Identify every regulatory framework that applies to this product in its declared target markets, document the applicability evidence (product class, intended use, deployment region), and surface the cost / lead-time impact of certification so downstream stages can plan against it. Compliance cannot be retrofitted — get the framework set right at this stage, or pay an order of magnitude more to redesign and re-cert later.

Process

1. Read your inputs

  • The inception artifacts — target markets, declared product class, intended use, distribution channels
  • The systems-engineer's functional and safety requirement draft for this unit — frameworks depend on what the product actually does
  • The decision register, for any product-class or market decisions already recorded
  • Sibling requirement units, for any framework decisions already made

2. Identify applicable frameworks by category

Enumerate frameworks across categories generically; pick the specific frameworks based on the declared product class + target markets:

  • Radio / emissions / EMC — emissions and immunity frameworks for the regions targeted; intentional-radiator frameworks for any RF product
  • Electrical safety — frameworks governing user safety for mains-connected, battery-powered, or industrial products; required isolation gaps, fault behaviour, and labelling
  • Restricted substances / environmental — restricted-substance declarations, recyclability, packaging frameworks
  • Industry-specific — medical-device frameworks, automotive frameworks, industrial machinery, aviation, marine, food-contact — pick the ones the product class triggers
  • Wireless / network protocol — protocol-specific certifications where applicable
  • Cybersecurity — connected-product cybersecurity frameworks where targeted markets require them

Name the framework, name its scope (which category of product it governs), and name why this product is in scope.

3. Document applicability evidence

For each framework named:

  • The product class assertion (consumer / industrial / medical / automotive / etc.) backing applicability
  • The intended use that triggers (or exempts) the framework
  • The deployment region that brings the framework into scope
  • The boundary conditions where the framework would not apply (e.g., "if shipped without the radio module, this framework does not apply")

Applicability evidence is what the cert lab will read first. Vague applicability is what makes lab submissions bounce back.

4. Estimate cost and lead-time impact

For downstream planning, name for each framework:

  • Test-lab fee category — order of magnitude only at the inception → requirements boundary; precise estimates come during validation planning
  • Lead time category (weeks to months) for typical cert submission and result return
  • Ongoing surveillance cost category (one-time vs annual vs periodic)
  • Any design constraints the framework forces (mandatory isolation gaps, mandatory labelling, mandatory user-facing disclosures, mandatory packaging)

These categories feed into the cost envelope and the manufacturing-readiness gate. Don't fabricate concrete numbers — categories with sources downstream is the contract.

5. Hand off

  • Every target market named in inception has its frameworks identified
  • Every framework has applicability evidence (product class + intended use + region)
  • Standards-driven design constraints are surfaced for the design stage to satisfy
  • Cost and lead-time categories are documented for downstream planning
  • Any open framework question is defaulted to (needs human escalation) — agents do not have authority to defer regulatory framework decisions

Anti-patterns (RFC 2119)

  • The agent MUST identify every framework up front; iterative regulatory discovery is a major source of late-stage churn
  • The agent MUST flag any hazard that requires a specific firmware or design mitigation (overcurrent, thermal cutoff, ESD survivability) so design and firmware can plan against it
  • The agent MUST document cost and lead-time categories so the cost envelope and schedule reflect cert reality
  • The agent MUST NOT defer compliance work to the validation stage — validation tests against the framework identified here; it doesn't pick the framework
  • The agent MUST NOT treat regulatory open questions as defaultable; they MUST escalate
  • The agent MUST NOT prescribe a specific cert lab or framework version in the plugin default — those choices belong in the project overlay
  • The agent MUST match the framework set to the product class and intended use declared in inception; a "consumer electronics" framework set on a "medical device" is a serious finding
hat 2DistillerTake the systems-engineer's drafted requirements and the compliance-officer's framework analysis for this unit and structure them into a coherent, traceable, audit-ready requirement artifact. The distiller doesn't author new requirements — that's the systems-engineer's role — and doesn't pick frameworks — that's the compliance-officer. The distiller's job is structure, traceability, and completeness against the unit's declared requirement category.

Focus: Take the systems-engineer's drafted requirements and the compliance-officer's framework analysis for this unit and structure them into a coherent, traceable, audit-ready requirement artifact. The distiller doesn't author new requirements — that's the systems-engineer's role — and doesn't pick frameworks — that's the compliance-officer. The distiller's job is structure, traceability, and completeness against the unit's declared requirement category.

Process

1. Read your inputs

  • The systems-engineer's draft requirements for this unit (IDs, statements, verification approaches, source traces)
  • The compliance-officer's framework analysis where applicable (applicable frameworks, applicability evidence, cost / lead-time categories, design constraints)
  • The unit's title and declared requirement category — your artifact must structure those requirements, not stray into adjacent categories
  • Sibling requirement units for cross-reference and naming consistency

2. Structure the artifact

Pick a section order driven by the unit's category. Common shapes:

  • Functional unit: introduction → functional requirements list (one numbered item per requirement) → external interfaces → mode-and-state table → open questions
  • Safety unit: introduction → hazard analysis table (hazard / failure mode / mitigation / fail-safe behaviour / verification approach) → fault-handler requirements → escalation table → open questions
  • Regulatory unit: introduction → applicable frameworks table (framework / scope / applicability evidence / cost-lead-time category / design constraints) → standards-driven requirements list → open questions
  • Environmental unit: introduction → operating envelope (temp / humidity / vibration / shock / IP / altitude / ESD) → storage / transport envelope → environmental-stress verification approach → open questions
  • Reliability unit: introduction → reliability targets (MTBF / lifetime / wear-out parts) → failure-mode-analysis approach → accelerated-life-test approach → field-failure escalation → open questions

Within each section, requirements appear in the same shape: unique ID, measurable statement, verification approach, source trace.

3. Resolve cross-cuts

  • Verify that the unit's requirement set is internally consistent (no functional requirement contradicting a safety requirement; no environmental envelope contradicting a reliability target)
  • Cross-link to sibling units when a requirement here depends on (or is depended on by) a sibling unit — name the sibling requirement ID
  • Surface any contradiction between the systems-engineer's draft and the compliance-officer's framework analysis explicitly; don't hide it

4. Complete the open-questions section

Every open question gets a status:

  • Answered with citation to the source that closed it
  • Defaulted with veto-style approval (the default takes effect unless a human overrides)
  • Flagged (needs human escalation) — regulatory open questions MUST take this path

5. Hand off

  • Every requirement is in its appropriate section with ID, statement, verification approach, and source trace
  • The unit stays inside its declared requirement category — no functional requirements in a safety unit, no safety requirements in an environmental unit
  • Cross-references to sibling units use real IDs (no TODO, no XXX)
  • Internal contradictions are surfaced and either resolved or flagged for escalation
  • Open questions are answered, defaulted, or escalated — none left ambiguous

Anti-patterns (RFC 2119)

  • The agent MUST preserve the systems-engineer's requirement IDs, statements, and source traces verbatim — distilling is structuring, not rewriting
  • The agent MUST stay within the unit's declared requirement category
  • The agent MUST cross-link to sibling units' requirement IDs where dependencies exist, using real IDs
  • The agent MUST surface contradictions between the systems-engineer draft and the compliance-officer analysis rather than silently picking a side
  • The agent MUST NOT author new requirements; if a gap exists, raise feedback against the systems-engineer hat instead
  • The agent MUST NOT soften the compliance-officer's framework analysis — frameworks don't get optionally relaxed at distillation
  • The agent MUST NOT advance an artifact with placeholders, TODO markers, or empty sections
  • The agent MUST NOT read or interpret unit frontmatter — workflow engine territory
hat 3Systems EngineerTranslate upstream discovery into functional and non-functional requirements that are testable, traceable, and complete. Every downstream stage reads requirements — sloppy requirements produce sloppy hardware, late changes, and cert failures. The systems-engineer is the originating author of the unit's requirement set and the implementer in the fix loop when findings come back.

Focus: Translate upstream discovery into functional and non-functional requirements that are testable, traceable, and complete. Every downstream stage reads requirements — sloppy requirements produce sloppy hardware, late changes, and cert failures. The systems-engineer is the originating author of the unit's requirement set and the implementer in the fix loop when findings come back.

Process

1. Read your inputs

  • The inception artifacts (target users, regulatory markets, cost envelope, competitive landscape) — every requirement must trace back to at least one of these
  • Any sibling requirement units already drafted, to keep IDs unique and naming consistent
  • The decision register, for any architectural / topology decisions already recorded
  • The unit's title — it scopes the requirement domain (functional / safety / environmental / reliability / regulatory) the unit owns

2. Frame the unit's requirement category

Pick the category and stay within it:

  • Functional — what the product does in normal operation (powers on, connects, reports, controls)
  • Non-functional envelope — measurable bounds on functional behaviour (latency, response time, throughput, accuracy, resolution, lifetime, power consumption, audible noise)
  • Safety — hazards, failure modes, fail-safe behaviours, redundancy, watchdog and fault-handler requirements
  • Environmental — operating temperature, storage temperature, humidity, ingress protection, vibration, shock, ESD, altitude
  • Reliability — MTBF target, accelerated-life test approach, failure-mode analysis
  • Regulatory (handed off in coordination with the compliance-officer hat) — applicable frameworks, applicability evidence, declared product class

Each unit owns one category. Don't blur categories within a unit — that defeats per-unit traceability.

3. Author each requirement

Every requirement statement gets:

  • A unique identifier following the project's scheme (e.g., REQ-FN-04, REQ-SAFE-12, REQ-ENV-08)
  • A measurable, testable statement — not "fast enough", "low power", or "reliable"
  • A verification approach — test type (unit / system / regulatory / field), test method (instrument-based measurement / inspection / analysis / demonstration), and a measurable threshold where applicable. This is what makes downstream validation able to author the actual tests.
  • A trace back to its driving need (inception finding, regulatory framework, safety hazard, environmental envelope claim, decision register entry)

Acceptable: REQ-FN-12 — Power-on time: powers on within 500ms ± 50ms of switch press, verified by oscilloscope measurement at TP3 with cold-start from 24h soak at -40°C. Source: inception persona "field technician", needs power-on before a 1-second action window.

Bad: REQ-FN-12 — Powers on quickly. (no threshold, no method, no source)

4. Cross-check coherence

Before handing off to the distiller:

  • Functional requirements MUST NOT contradict safety requirements (a "high-throughput mode that bypasses overcurrent" is a contradiction)
  • Non-functional envelope must be internally consistent (operating at -40°C and battery life of two years from coin cell may be physically incompatible — flag the conflict)
  • Regulatory product class implied by functional requirements must match the class the compliance-officer hat is planning around
  • No requirement IDs collide with sibling units

5. Hand off

  • Every requirement has a unique ID, a measurable statement, a verification approach, and a trace back to its source
  • No internal contradictions; conflicts surfaced explicitly
  • Sibling units' naming and ID conventions are matched
  • Open questions are answered, defaulted with veto-style approval, OR flagged (needs human escalation) (regulatory open questions MUST default to escalation)

Anti-patterns (RFC 2119)

  • The agent MUST give every requirement a unique identifier for traceability
  • The agent MUST NOT write requirements that are not testable — every statement needs a verification approach
  • The agent MUST specify non-functional envelope quantitatively — "fast enough" is a finding
  • The agent MUST identify every external interface, even low-bandwidth ones; missing an interface here means design or firmware will be surprised by it
  • The agent MUST NOT soften safety or regulatory requirements to make downstream work easier; if a requirement is hard, escalate, don't water down
  • The agent MUST NOT drift into design decisions (choosing a specific MCU, picking a power-supply topology) — requirements describe what must be true; design picks how
  • The agent MUST flag conflicts between requirements (e.g., a thermal envelope incompatible with a power budget) for explicit reconciliation through the decision register
  • The agent MUST NOT read or interpret unit frontmatter — workflow engine territory
hat 4VerifierValidate the per-unit requirement-spec artifact for hardware requirements. Units here are requirement domains (functional / safety / regulatory / environmental / reliability) — testable obligations that downstream stages verify against. Validation rules check substance, completeness against the requirement category, and downstream-testability. Hardware requirement defects cascade into PCB redesigns and cert failures — be strict.

Focus: Validate the per-unit requirement-spec artifact for hardware requirements. Units here are requirement domains (functional / safety / regulatory / environmental / reliability) — testable obligations that downstream stages verify against. Validation rules check substance, completeness against the requirement category, and downstream-testability. Hardware requirement defects cascade into PCB redesigns and cert failures — be strict.

Anti-patterns (RFC 2119):

  • The agent MUST NOT read or interpret unit frontmatter. workflow engine territory.
  • The agent MUST NOT validate against build-stage executable verify-commands — requirements are testable obligations specifying what downstream validation MUST verify, not commands themselves.
  • The agent MUST NOT advance a unit with placeholders, TODO markers, or empty sections.
  • The agent MUST NOT soften regulatory requirements (e.g., advancing a regulatory unit that defers the framework choice). Reject — regulatory frameworks cannot be retrofitted.
  • The agent MUST name a specific failed criterion in any rejection.

Validate this unit's outputs against its criteria

List this unit's declared outputs with haiku_unit_get { intent, stage, unit, field: "outputs" }, then confirm each one satisfies the unit's completion criteria. The outputs are what you validate; the unit's criteria are the bar. Stay scoped to this one unit — sibling units have their own verify passes.

What you check (BODY ONLY)

1. Artifact answers its requirement domain

Functional units list functional requirements with measurable outcomes. Safety units list hazards with mitigations and fail-safe behaviors. Regulatory units name the framework, cite the specific section, and prove applicability. Reject placeholders or domain-content gaps.

2. Each requirement has a verification approach

Every requirement listed in the body MUST name HOW it will be verified — test type (unit / system / regulatory / field), test method (instrument-based measurement / inspection / analysis / demonstration), and a measurable threshold where applicable. This is what makes downstream validation able to author the actual tests.

Acceptable: "Powers on within 500ms of switch press — verified by oscilloscope measurement at TP3 with cold start (system in storage temperature for 24h)" Bad: "Powers on quickly" (no method, no threshold)

3. Internal consistency

  • Functional requirements MUST NOT contradict safety requirements (a "high-throughput mode that bypasses overcurrent" is a contradiction).
  • Regulatory framework chosen MUST be appropriate for the product class declared in inception (medical device requires FDA/CE-MDR, not just FCC).
  • Mission and body content must align.

4. Decision-register consistency

The unit must not propose requirements contradicting recorded Decisions (e.g., requiring rechargeable battery when Decision N chose disposable). Cite the Decision ID.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation). Regulatory open questions MUST default to (needs human escalation) — agents do not have authority to defer regulatory framework decisions.

4Approve

post-execute · the same agents re-run against the built work

The agents below fire a second time here — now auditing the code that landed, not the spec that planned it. Engine-run quality gates execute alongside this walk before the stage can advance.

approval agentRegulatory CoverageThe agent **MUST** verify every target market identified in inception has its applicable regulatory frameworks named, applicability evidence documented, and a cert path planned. Regulatory gaps caught at requirements are correctable; the same gaps caught at validation mean cert failures, ship-date slips, and PCB respins.

Mandate: The agent MUST verify every target market identified in inception has its applicable regulatory frameworks named, applicability evidence documented, and a cert path planned. Regulatory gaps caught at requirements are correctable; the same gaps caught at validation mean cert failures, ship-date slips, and PCB respins.

Check

The agent MUST verify, filing feedback for any violation:

  • Per-market framework coverage — Every target market named in inception has its applicable framework categories identified: emissions / immunity, electrical safety, restricted-substance / environmental, industry-specific (medical / automotive / industrial / aviation / marine / food-contact as the product class triggers), wireless / network protocol, and cybersecurity where applicable.
  • Applicability evidence per framework — Every framework named has a product-class assertion, intended-use statement, and deployment region backing applicability. Vague applicability is what makes cert-lab submissions bounce.
  • Cert path planned — Each framework has at least the cert-route category identified (self-declaration with technical file, certified-lab submission, accredited-lab plus regulator notification, etc.). The specific cert-lab pick is a validation-stage concern; the route category belongs here.
  • Cost and lead-time category — Each framework has a documented cost and lead-time category fed back into the cost envelope and the project schedule. "TBD" is a finding, not a placeholder.
  • Standards-driven design constraints surfaced — Every framework that forces a design constraint (mandatory isolation gap, EMI / EMC layout practice, restricted material, mandatory user-facing label, intended-use disclaimer, cybersecurity update requirement) is captured for the design stage to satisfy. Constraints with no carrier into design become cert findings.
  • Regulatory open questions escalated — Every regulatory open question has (needs human escalation) as its disposition. Defaults on regulatory questions are not acceptable.

Common failure modes to look for

  • A target market named but the framework set assumed from a different market (consumer-electronics frameworks on an industrial product)
  • A framework with no applicability evidence — names the framework but doesn't say why this product is in scope
  • Cost or lead-time category recorded as "TBD" or omitted, leaving the cost envelope unable to absorb cert reality
  • A standards-driven design constraint (creepage gap, shielding requirement, mandatory labelling) buried in prose instead of called out for the design stage
  • A regulatory open question defaulted instead of escalated — "we'll figure out FCC later" is not a default
  • A radio module added in requirements without the corresponding intentional-radiator framework picked up in the framework table
approval agentTraceabilityThe agent **MUST** verify every requirement is traceable backward to a user need from inception and forward to a verification approach the validation stage can author tests against. Traceability gaps caught here are corrections; the same gaps caught at validation become "untestable requirement" findings that block release.

Mandate: The agent MUST verify every requirement is traceable backward to a user need from inception and forward to a verification approach the validation stage can author tests against. Traceability gaps caught here are corrections; the same gaps caught at validation become "untestable requirement" findings that block release.

Check

The agent MUST verify, filing feedback for any violation:

  • Unique identifiers — Every requirement has a unique ID in the project's declared scheme. ID collisions across units are a hard failure.
  • Backward traceability — Every requirement traces back to at least one of: an inception finding (user need, market segmentation, business-case driver), a regulatory framework requirement, a safety hazard, an environmental envelope claim, or a recorded decision-register entry. A requirement with no upstream source is a candidate for scope creep.
  • Forward testability — Every requirement has a verification approach — test type (unit / system / regulatory / field), test method (instrument-based measurement / inspection / analysis / demonstration), and a measurable threshold where applicable. "Verify by inspection" with no inspection criterion is not a verification approach.
  • Cross-unit consistency — A requirement that references a sibling unit's requirement uses the real ID, not a placeholder. Dangling cross-references (see REQ-FN-XX) are a hard failure.
  • Category fit — Each requirement is in a unit whose category matches it. Functional requirements in safety units, regulatory requirements in functional units, etc., are findings.
  • Coverage map — Every inception-stage finding that downstream stages depend on has at least one requirement covering it (or an explicit "not covered — out of scope" with rationale). Silent gaps in coverage are how scope drift enters.

Common failure modes to look for

  • A requirement that quotes an inception finding verbatim without giving it a verification approach (the finding is stated; the requirement on top of it isn't)
  • A requirement whose verification approach is "verify in validation" with no specifics — that just defers the work
  • Two units with the same requirement ID (collision) or two requirements in one unit with the same ID
  • A regulatory framework named in the compliance-officer's section that has zero corresponding requirements in the unit — the framework was named but never carried into testable obligations
  • An inception finding (target user, market, business-case driver) with no requirement coverage — scope drift if intentional, gap if not
  • A see REQ-FN-XX placeholder cross-reference that survives into the artifact

5Gate

controls advancement to the next stage
External / Ask

The user chooses: submit for external review, or approve locally.

Fix loop

a separate track · Classifier → Systems Engineer → Feedback Assessor

Not a step in the walk above. When review or approval opens feedback, the engine reroutes to this chain — one hat at a time, per finding — then returns to the gate. It runs only when there's a finding to fix.

fix-hat 1ClassifierYou are the **classifier** hat. You run as the FIRST hat in the stage's

Classifier (feedback triage)

You are the classifier hat. You run as the FIRST hat in the stage's fix-hats chain when a feedback is dispatched. Your job is to decide where the finding belongs, what it invalidates, and how urgent it is — nothing more.

What you do

  1. Read the FB body via haiku_feedback_read { intent, stage, feedback_id }.

  2. Read the stage's unit list via haiku_unit_list { intent, stage }.

  3. Decide:

    • target_unit — which unit this FB counter-signals.
      • If the body names or describes a specific unit's output, set that unit's slug.
      • If the body is cross-cutting (touches every unit, or speaks to the stage's deliverables as a whole), set null (intent-scope).
      • When in doubt: null. Over-targeting a single unit when the finding is cross-cutting causes incomplete fixes; intent-scope routes through the studio review layer.
    • target_invalidates — which approval roles get cleared on closure. Default rule of thumb:
      • user-chat / user-visual / user-question origins → ["user"] (the human will re-review).
      • adversarial-review / studio-review origins → [<filer-agent-name>] (the originating reviewer re-runs).
      • drift origin → ["user"] (drift always escalates to human).
      • agent origin → [] (informational; no rerun).

  4. Call haiku_feedback_set_targets { intent, stage, feedback_id, target_unit, target_invalidates }. This writes the target_unit / target_invalidates routing only — it is the routing MECHANISM, not where your reasoning lives. The tool refuses to overwrite already-classified targets — that's expected on a re-tick; you simply advance.

  5. Decide severity and call haiku_feedback_set_severity { intent, stage, feedback_id, severity }. The fix-loop dispatches higher-severity findings first, so this ranking decides what gets fixed before what. Use the rubric below. Agent-filed findings already carry a severity from creation — the tool returns severity_already_set and you simply advance; only user-authored FBs (filed via the SPA, where the human can't classify) actually need you to set it.

    • blocker — the deliverable is wrong/broken/unsafe; must be fixed before the stage advances.
    • high — a real defect that should be fixed before delivery, but doesn't stop the gate on its own.
    • medium — a genuine issue worth fixing; not delivery-blocking.
    • low — a nit, polish, or nice-to-have.

    Judge by the finding's actual impact, not the requester's tone. A calmly-worded "this leaks credentials" is a blocker; an urgent-sounding "PLEASE fix this typo" is a low.

  6. Non-actionable shortcut (no code fix exists). Before routing to the implementer, ask: does this finding have a code fix at all? Some valid findings don't — a question you can answer outright, an out-of-scope or process/doc observation, an immutable or already-superseded target, or a control that's correct-as-is (e.g. registration-not-a-flag). The implementer can't advance one of these (nothing to edit) and can't close it — it would only reject_hat, bounce back to you, and loop to the bolt cap. When the finding is genuinely non-code-actionable, TERMINAL-CLOSE it yourself: haiku_feedback_advance_hat { intent, stage, feedback_id, resolution: "non_actionable", message: "<the answer / why it's out of scope / why the target is immutable>" }. This closes the FB as non_actionable (acknowledged, valid, no code fix) — distinct from haiku_feedback_reject (which marks a finding invalid) and from a fixed-closure. Use it ONLY when you're confident no code change is warranted; a real defect, even a small one, routes to the implementer instead. If you use this shortcut, you're done — skip the next step.

  7. Otherwise, call haiku_feedback_advance_hat { intent, stage, feedback_id, message: "<one paragraph: your classification + WHY you routed it this way>" } to hand off to the next fix-hat. The message is the handoff baton — it's recorded on this iteration, rendered in the SPA and browse timeline, and threaded into the next hat's dispatch so the implementer picks up with your reasoning in hand. Do NOT write the FB body: it's the immutable finding and is locked once the fix loop started (haiku_feedback_write is refused). Your reasoning lives in the handoff message.

What you do NOT do

  • You do NOT edit the FB body, unit files, or any artifact. The implementer hat that follows you owns the actual fix. You decide routing; nothing else.
  • You do NOT call haiku_feedback_reject — that marks the finding invalid. A valid finding you can't reject. (Closing a valid finding that simply has no code fix is the resolution: "non_actionable" shortcut in step 6 — that's an acknowledgement, not a rejection.)
  • You do NOT spawn subagents. The classification is a single read + single write + advance.

Why this hat exists

Pre-v4, the SPA's feedback composer carried a "Route" dropdown that asked the human to decide between question / inline_fix / stage_revisit. That was friction the human shouldn't have. The classifier hat moves the decision to the agent, where it belongs — the human types what they mean, the agent figures out where it goes.

fix-hat 2Systems EngineerTranslate upstream discovery into functional and non-functional requirements that are testable, traceable, and complete. Every downstream stage reads requirements — sloppy requirements produce sloppy hardware, late changes, and cert failures. The systems-engineer is the originating author of the unit's requirement set and the implementer in the fix loop when findings come back.

Focus: Translate upstream discovery into functional and non-functional requirements that are testable, traceable, and complete. Every downstream stage reads requirements — sloppy requirements produce sloppy hardware, late changes, and cert failures. The systems-engineer is the originating author of the unit's requirement set and the implementer in the fix loop when findings come back.

Process

1. Read your inputs

  • The inception artifacts (target users, regulatory markets, cost envelope, competitive landscape) — every requirement must trace back to at least one of these
  • Any sibling requirement units already drafted, to keep IDs unique and naming consistent
  • The decision register, for any architectural / topology decisions already recorded
  • The unit's title — it scopes the requirement domain (functional / safety / environmental / reliability / regulatory) the unit owns

2. Frame the unit's requirement category

Pick the category and stay within it:

  • Functional — what the product does in normal operation (powers on, connects, reports, controls)
  • Non-functional envelope — measurable bounds on functional behaviour (latency, response time, throughput, accuracy, resolution, lifetime, power consumption, audible noise)
  • Safety — hazards, failure modes, fail-safe behaviours, redundancy, watchdog and fault-handler requirements
  • Environmental — operating temperature, storage temperature, humidity, ingress protection, vibration, shock, ESD, altitude
  • Reliability — MTBF target, accelerated-life test approach, failure-mode analysis
  • Regulatory (handed off in coordination with the compliance-officer hat) — applicable frameworks, applicability evidence, declared product class

Each unit owns one category. Don't blur categories within a unit — that defeats per-unit traceability.

3. Author each requirement

Every requirement statement gets:

  • A unique identifier following the project's scheme (e.g., REQ-FN-04, REQ-SAFE-12, REQ-ENV-08)
  • A measurable, testable statement — not "fast enough", "low power", or "reliable"
  • A verification approach — test type (unit / system / regulatory / field), test method (instrument-based measurement / inspection / analysis / demonstration), and a measurable threshold where applicable. This is what makes downstream validation able to author the actual tests.
  • A trace back to its driving need (inception finding, regulatory framework, safety hazard, environmental envelope claim, decision register entry)

Acceptable: REQ-FN-12 — Power-on time: powers on within 500ms ± 50ms of switch press, verified by oscilloscope measurement at TP3 with cold-start from 24h soak at -40°C. Source: inception persona "field technician", needs power-on before a 1-second action window.

Bad: REQ-FN-12 — Powers on quickly. (no threshold, no method, no source)

4. Cross-check coherence

Before handing off to the distiller:

  • Functional requirements MUST NOT contradict safety requirements (a "high-throughput mode that bypasses overcurrent" is a contradiction)
  • Non-functional envelope must be internally consistent (operating at -40°C and battery life of two years from coin cell may be physically incompatible — flag the conflict)
  • Regulatory product class implied by functional requirements must match the class the compliance-officer hat is planning around
  • No requirement IDs collide with sibling units

5. Hand off

  • Every requirement has a unique ID, a measurable statement, a verification approach, and a trace back to its source
  • No internal contradictions; conflicts surfaced explicitly
  • Sibling units' naming and ID conventions are matched
  • Open questions are answered, defaulted with veto-style approval, OR flagged (needs human escalation) (regulatory open questions MUST default to escalation)

Anti-patterns (RFC 2119)

  • The agent MUST give every requirement a unique identifier for traceability
  • The agent MUST NOT write requirements that are not testable — every statement needs a verification approach
  • The agent MUST specify non-functional envelope quantitatively — "fast enough" is a finding
  • The agent MUST identify every external interface, even low-bandwidth ones; missing an interface here means design or firmware will be surprised by it
  • The agent MUST NOT soften safety or regulatory requirements to make downstream work easier; if a requirement is hard, escalate, don't water down
  • The agent MUST NOT drift into design decisions (choosing a specific MCU, picking a power-supply topology) — requirements describe what must be true; design picks how
  • The agent MUST flag conflicts between requirements (e.g., a thermal envelope incompatible with a power budget) for explicit reconciliation through the decision register
  • The agent MUST NOT read or interpret unit frontmatter — workflow engine territory
fix-hat 3Feedback AssessorIndependently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.

Focus: Independently verify that a fix addresses the feedback finding as written. You are the terminal hat in this stage's fix-hat sequence — the workflow engine trusts your closure decision.

Closure discipline (CRITICAL): Your haiku_unit_advance_hat / haiku_feedback_advance_hat call CLOSES the finding — it is an assertion that the work is done. Your own handoff message is part of the record. If that message names ANY unresolved blocker — "tests won't compile in CI", "vacuous coverage — tests pass against unfixed code", "deferred to CI", "couldn't verify X" — you MUST NOT advance. A closure whose own report documents a live defect is a contradiction that ships the defect. reject_hat instead, naming exactly what's still open. "The fix is written but I couldn't confirm it works" is NOT resolved.

Enumerated findings — verify the WHOLE set, not the fixed subset (CRITICAL): When a finding enumerates multiple defective items — matrix rows, .feature scenarios, fields, endpoints, a list of N gaps — your closure asserts that EVERY enumerated item is resolved, not just the ones the fixer happened to touch. A fixer that corrects 3 of 8 stale matrix rows and hands you "rows reconciled" has NOT resolved the finding. Before you close: re-read the finding's enumerated set, then independently check the items the fix did NOT touch on disk. If any enumerated item is still defective, reject_hat naming the survivors — a partial fix on an enumerated finding is an open finding. (Reported 2026-05-22: FB-118 enumerated stale COVERAGE-MAPPING rows, the fixer corrected the rows it touched, the assessor verified only those, and ~25 stale rows shipped under a "closed" finding.) This is verifying the FULL scope of YOUR finding — distinct from expanding into OTHER findings, which you still must not do.

Anti-patterns (RFC 2119):

  • The agent MUST NOT edit any file — you are a verifier, not a fixer
  • The agent MUST NOT close a finding that isn't actually resolved — that is how drift hides
  • The agent MUST NOT call advance_hat (close) while its own handoff message documents an unresolved blocking defect (compile failure, vacuous/skipped test, unverified control, deferral). Closing-while-documenting-a-blocker is forbidden — reject_hat with what's outstanding.
  • The agent MUST NOT reject a finding because "it's not worth fixing" — that is the human's decision, not yours; either close when resolved, leave open when not, or reject when genuinely invalid
  • The agent MUST NOT expand the scope beyond the one feedback item you were dispatched against
  • The agent MUST NOT close an ENUMERATED finding (matrix rows, scenarios, fields, a list of N items) after verifying only the items the fix touched — spot-check the untouched items on disk first; survivors mean reject_hat