Hardware Development · stage 1 of 6

Inception

Ask gate

Market research, user problem, and business case

Inception

The opening stage of the hardware lifecycle: understand the market, the user problem, and the business case for the product. What are we building and why, who would buy it, what's the competitive landscape, what's the unit-economics envelope — answered with evidence before any engineering decision gets made.

Scope

Market and business understanding: the user problem, the competitive landscape, the addressable segments, and the unit-economics envelope. Inception decides which markets and product class matter — so the requirements stage knows which regulatory and safety frameworks to plan against. It does not decide the hardware constraints themselves.

What to do

  • Investigate the market and user problem from cited primary and secondary sources, not assumption.
  • Name the addressable segments and price the alternatives so the business case is decision-ready.
  • Identify the product class precisely enough that requirements can map it to the right regulatory regimes.
  • Articulate the gaps in what's known rather than papering over them.

What NOT to do

  • Don't decide safety, regulatory, manufacturing-feasibility, or environmental constraints — those belong to requirements.
  • Don't specify the product's functional behavior or design — those are downstream stages.
  • Don't commit to a product class you can't ground in market evidence.
  • Don't leave an unknown unstated; an unexamined gap here becomes a wrong framework choice in requirements.

How the engine runs this stage

1Elaborate

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

Discovery fan-out

knowledge artifactDiscoveryMarket, user, and business context for the hardware product. Foundation for downstream stages.

Discovery

Market, user, and business context for the hardware product. Foundation for downstream stages.

Content Guide

Problem & Users

  • Target users and their context
  • The problem this product solves
  • Why hardware (vs. a software solution)

Market

  • Competitive landscape with named products
  • Pricing bands and positioning
  • Distribution channels and retail strategy

Business Case

  • Rough COGS envelope
  • Target price and margin
  • Volume estimate
  • Target regulatory markets (US, EU, etc.) — so requirements knows which frameworks apply

Non-Goals

  • Features or markets explicitly deferred

Quality Signals

  • Target users are specific, not generic
  • Competitors are named with product SKUs
  • Regulatory markets are identified so requirements can plan
  • Cost envelope is defensible, not aspirational

Phase guidance

phase overrideELABORATIONHardware inception is a **research / distillation** stage. Its units are knowledge topics covering market opportunity, business case, and target-user understanding for a hardware product. Hardware-specific constraints (safety, regulatory, manufacturing feasibility) belong in the **requirements** stage, not here.

Hardware Inception Stage — Elaboration

Hardware inception is a research / distillation stage. Its units are knowledge topics covering market opportunity, business case, and target-user understanding for a hardware product. Hardware-specific constraints (safety, regulatory, manufacturing feasibility) belong in the requirements stage, not here.

What a unit IS in this stage

One investigable knowledge topic. Examples:

  • "Target market segmentation and primary user persona"
  • "Competitive product landscape with price, primary features, and gaps"
  • "Business case: addressable market, unit economics, payback period"
  • "Distribution channels and channel economics"
  • "Brand positioning and differentiation thesis"
  • "Hardware-product-specific risks (e.g., supply-chain dependencies, component lead times) at a strategic level"

What a unit is NOT in this stage:

  • ❌ Functional or safety requirements (those belong in requirements)
  • ❌ Mechanical/electrical/PCB design (those belong in design)
  • ❌ Manufacturing process specs (those belong in manufacturing)
  • ❌ A bill of materials or component selection (those follow from design)

What "completion criteria" means here

Knowledge-artifact criteria are about substance and accountability, not testable outcomes. Hardware inception is upstream of any physical artifact.

Good criteria — substantive and checkable

  • "Market segmentation §2 names ≥3 distinct segments with size estimates and a one-paragraph differentiation per segment"
  • "Competitive landscape §3 names ≥4 alternatives the user could buy instead, each with current MSRP, primary feature, and the gap this product addresses"
  • "Business case §5 cites concrete numbers (volume, ASP, BOM target, channel margin, payback) — no placeholder ranges like 'TBD' or 'reasonable margin'"
  • "Open questions section has ≥0 entries; each open question has a proposed default for veto-style approval OR (needs human escalation)"

Bad criteria — vague or wrong-stage language

  • ❌ "Market is understood" (no concrete check)
  • ❌ "Each unit has a verifiable command" (build-stage language; hardware inception is non-executable)
  • ❌ "FCC compliance is verified" (wrong stage — requirements owns regulatory framework choice; certification happens in validation)
  • ❌ "Schematic is finalized" (wrong stage — design owns electrical/mechanical artifacts)

Anti-patterns

  • Bleeding into requirements / design. Hardware inception is "should we build this and for whom"; not "what does it do" (requirements) or "how is it built" (design).
  • Single-document syndrome. One giant business-case doc defeats the per-unit model. One topic per unit.
  • Skipping citation. Hardware decisions cost money to undo; sources for market and competitive claims are mandatory.

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 knowledge-artifact units. Treat the build-class rules as defaults the framework hasn't yet split — author your units to the substance/accountability shape above, not to executable verify-commands. (Architecture §7 known issue tracking the split.)

Outputs produced

output templateKnowledgeSupporting research for hwdev inception: market data, competitor teardowns, component cost research, early BOM estimates.

Knowledge

Supporting research for hwdev inception: market data, competitor teardowns, component cost research, early BOM estimates.

2Review

pre-execute · agents audit the planned spec before any code lands
review agentCompletenessThe agent **MUST** verify the inception knowledge artifacts collectively cover everything downstream hardware stages will need to plan against. Gaps here cascade into requirements that miss a market, designs that miss a constraint, and validation plans that miss a regulatory framework.

Mandate: The agent MUST verify the inception knowledge artifacts collectively cover everything downstream hardware stages will need to plan against. Gaps here cascade into requirements that miss a market, designs that miss a constraint, and validation plans that miss a regulatory framework.

Check

The agent MUST verify, filing feedback for any violation:

  • Target users are specific — A named user, role, or segment with measurable attributes (job-to-be-done, willingness to pay, purchase frequency), not a vague "users who care about X". Vague target users propagate into vague requirements.
  • Regulatory markets identified — The geographies and product class are named so the requirements stage can plan certification frameworks against them. "Sells in North America" with no notes is incomplete — the cert frameworks for medical, industrial, consumer, and connected products differ.
  • Cost envelope documented — BOM target, target ASP, channel margin assumption, and target volume are documented with their sources. The envelope must be tight enough that design can make component-cost tradeoffs against it.
  • Competitive landscape concrete — A real, current list of alternatives the user could buy instead, each with current MSRP, primary feature, and the gap this product addresses. Lists with only "we are best in class" claims and no named alternatives are incomplete.
  • Non-goals explicit — The artifact names what this product is NOT, so downstream stages don't accidentally scope-creep into adjacent markets or features.
  • Volume estimates grounded — Volume figures cite a comparable product, a channel-capacity argument, or a primary-research signal, not a vibes-based number.
  • Downstream-stage handoff — Each artifact lists which downstream stage will consume each conclusion (requirements / design / manufacturing) so the next stage knows what to read.

Common failure modes to look for

  • A target user described only in demographic terms ("affluent urban professionals") with no job-to-be-done
  • A regulatory-markets section that names countries but doesn't identify the product class that drives the cert framework
  • A cost envelope without channel margin — retail-margin compression is how products lose money
  • "Best in class" positioning with no concrete competitor table
  • Volume estimates of "we expect 10k units year one" with no comparable-product anchor
  • A business-case unit that doesn't surface the most fragile assumption (the one a single bad input would collapse the case on)
review agentMarket FeasibilityThe agent **MUST** challenge whether the product has a defensible position given the documented competitive landscape, cost envelope, channel economics, and regulatory cost-of-entry. Adversarial review of the business case at inception is the cheapest place to find out the product won't pay for itself.

Mandate: The agent MUST challenge whether the product has a defensible position given the documented competitive landscape, cost envelope, channel economics, and regulatory cost-of-entry. Adversarial review of the business case at inception is the cheapest place to find out the product won't pay for itself.

Check

The agent MUST verify, filing feedback for any violation:

  • Cost envelope vs target retail — The declared BOM target, channel margin assumption, and target ASP are mathematically consistent: BOM × markup × channel-margin landing at a retail price the documented target user will pay. If the math doesn't close, that's a finding.
  • Differentiation a consumer would notice — The artifact names at least one differentiator that a target user would observe in normal use (not "better firmware quality", not "more rigorous QA") and explains why the competitor isn't already doing it. "We will be better" is not differentiation.
  • Regulatory cost-of-entry reflected — Any regulatory framework whose certification adds meaningful unit cost or per-launch cost is reflected in the envelope: cert lab fees, ongoing surveillance, restricted-substance compliance costs, country-specific approvals. A "we'll get FCC" line item with no cost is an under-estimate.
  • Volume estimates grounded — Volume figures cite a comparable product, a channel-capacity argument, or a primary-research signal — not a wish list. The most fragile assumption in the business case has a sensitivity note showing what happens if it's half what's claimed.
  • Channel economics — Channel margins, return-rate assumptions, and shelf / placement fees are documented for the chosen channels. A channel with high return rates (consumer electronics) needs reserve in the envelope.
  • Time-to-market vs window — Any market window argument cites a documented window (competitor announcement, regulatory deadline, seasonal buying pattern). "We need to be first" without a window is wishful thinking.

Common failure modes to look for

  • A BOM-to-MSRP markup that assumes single-channel direct-to-consumer when the actual plan goes through multi-tier distribution
  • A "competitors don't do X" claim with no citation, when in fact they do (or did, and stopped for a reason)
  • Regulatory cost left as a single line item with no actual cert-lab estimate
  • Volume estimates that ignore typical year-one ramp curves and book year-one revenue as if production runs at steady-state from day one
  • A channel choice incompatible with the cost envelope (mass retail margins with a premium-product BOM)
  • Differentiation that's invisible at point of purchase (only the second-time user would notice, but the buying decision is made by the first-time user)

3Execute

per-unit baton · Researcher → Distiller → Verifier
hat 1DistillerTake the researcher's raw findings for this unit and turn them into a decision-ready knowledge artifact — segmented, sourced, structured so downstream stages can build on it without re-doing the research. The distiller's job is not more investigation; it is reduction, structure, and accountability. A good distilled artifact is one a stranger to the project can read and walk away with a clear picture of the question and its answer.

Focus: Take the researcher's raw findings for this unit and turn them into a decision-ready knowledge artifact — segmented, sourced, structured so downstream stages can build on it without re-doing the research. The distiller's job is not more investigation; it is reduction, structure, and accountability. A good distilled artifact is one a stranger to the project can read and walk away with a clear picture of the question and its answer.

You produce one artifact per unit: the structured knowledge artifact for the unit's topic.

Process

1. Read your inputs

  • The researcher's findings for this unit (sourced, with inline citations and Open Questions)
  • The unit's title and topic — the artifact must answer that specific question and not stray
  • The intent's decision register — recorded decisions are constraints on what conclusions you may reach
  • Sibling units' completed artifacts to keep naming, segment definitions, and competitor names consistent

2. Settle the artifact's structure

Pick a structure that matches the unit's question:

  • For segmentation questions: segment definition → segment sizes → per-segment differentiation
  • For competitive-landscape questions: alternative-product table (name / MSRP / primary feature / gap) → positioning thesis → list of alternatives the user could buy instead
  • For business-case questions: addressable market → unit economics (BOM target, ASP, channel margin, payback) → sensitivity analysis on the most fragile assumption
  • For channel / distribution questions: channel options → channel economics → channel-fit assessment per segment
  • For positioning / differentiation questions: claim → evidence → comparison to existing alternatives

One topic per unit. If your artifact is starting to cover two distinct questions, split into two units rather than blending them.

3. Distill

  • Reduce the researcher's corpus to the smallest set of statements that answer the unit's question, with citations preserved inline
  • For every numerical claim, restate the number with the original publication date AND a confidence note (single source, multi-source corroborated, primary research only, etc.)
  • Resolve contradictions between sources explicitly — pick a position, cite the basis, and note the dissenting source
  • Flag remaining uncertainty as Open Questions with a proposed default for veto-style approval OR (needs human escalation) for items beyond agent authority
  • Identify which downstream stages depend on each conclusion (requirements needs the regulatory markets; design needs the cost envelope; manufacturing needs the volume estimates)

4. Cross-reference siblings

  • If a segment, competitor, channel, or persona appears in another unit, use the SAME name and definition
  • If your artifact contradicts a sibling unit's claim, flag it as an Open Question rather than silently overruling — the verifier needs the contradiction surfaced

5. Hand off

  • The artifact answers the unit's specific question and does not stray into adjacent topics
  • Every non-trivial claim retains its source citation
  • Numerical claims include original publication date and a confidence note
  • Contradictions between sources are resolved with rationale, not hidden
  • Every Open Question has a proposed default OR is flagged (needs human escalation)
  • Downstream-stage dependencies are listed so the next stage knows what to consume

Anti-patterns (RFC 2119)

  • The agent MUST preserve every inline citation from the researcher's findings — distilling is reduction, not de-sourcing
  • The agent MUST restate numerical claims with their original publication date so reviewers can judge freshness
  • The agent MUST answer the unit's specific question and not drift into adjacent topics — drift is how unit-level review breaks down
  • The agent MUST match sibling units' naming for segments, competitors, channels, and personas
  • The agent MUST NOT invent findings the researcher did not provide; if a gap exists, surface it as an Open Question
  • The agent MUST NOT hide contradictions between sources — pick a position and cite the basis, or flag for escalation
  • The agent MUST NOT advance an artifact with placeholders, TODO markers, or empty sections — the verifier will reject those
  • The agent MUST NOT ensure unit DAG correctness or interpret unit frontmatter — workflow engine territory
  • The agent MUST NOT specify safety, regulatory, or design decisions — those belong in requirements and design
hat 2ResearcherInvestigate one knowledge topic about the hardware product's market, target user, business case, or strategic landscape. Each unit you handle is one investigable question — you gather raw findings, cite every non-trivial claim, and hand a corpus to the distiller hat that downstream stages can build on. Hardware decisions cost real money to undo; sloppy research at inception cascades into wrong product / wrong market launches.

Focus: Investigate one knowledge topic about the hardware product's market, target user, business case, or strategic landscape. Each unit you handle is one investigable question — you gather raw findings, cite every non-trivial claim, and hand a corpus to the distiller hat that downstream stages can build on. Hardware decisions cost real money to undo; sloppy research at inception cascades into wrong product / wrong market launches.

Process

1. Read your inputs

  • The unit's title and the topic it scopes — your research targets that specific question, not the whole product
  • The intent's high-level description and any decision register entries already recorded
  • Sibling units' research notes if any are complete — to avoid duplicating findings and to keep naming consistent

2. Choose source classes deliberately

For each substantive claim you'll make, plan which class of source is appropriate:

  • Primary user research — interviews, surveys, observation studies. Most credible for "what do users actually do / want". Cite the date, sample size, and method.
  • Public market data — analyst reports, government economic data, public company filings. Most credible for sizing and growth rates. Cite the publication and date.
  • Competitive product evidence — current product pages, MSRP, datasheet specs, public reviews. Most credible for "what's available today". Cite the page URL and access date.
  • Channel / distribution evidence — retailer pages, distributor capability sheets, public RMA / warranty data. Most credible for channel economics.
  • Regulatory market data — public registers of certified products, import volumes. Most credible for "is this market real for products like this".

"Industry common knowledge" is not a source. If you cannot cite it, you cannot claim it.

3. Investigate and capture findings

  • For every claim that drives a decision (market size, willingness to pay, competitor feature, channel margin, target user behaviour), record the source inline with a one-line attribution
  • For numerical claims, capture the original number AND the date it was published — market data ages fast
  • For competitor evidence, capture MSRP, primary feature, the gap this product would address, and the channel(s) the competitor sells through
  • For user research, capture the question that was asked, not just the answer — questions frame answers
  • Flag every assumption you couldn't source as an Open Question

4. Frame the artifact for the distiller

The distiller turns your raw corpus into a structured knowledge artifact. Make the handoff easy:

  • Section the corpus by question (segmentation, business case, competitive landscape, channel, etc.) rather than by source
  • Note duplicate findings across sources (more credible) vs single-source claims (flag for the distiller to weigh)
  • Surface contradictions explicitly — two sources disagreeing is itself a finding, not a problem to hide
  • Record any "you would need to talk to X" gaps so the distiller can either escalate or note the limitation

5. Hand off

  • Every non-trivial claim has an inline citation with source and date
  • Numerical claims include the original number AND its publication date
  • Every assumption you couldn't source is flagged as an Open Question
  • Contradictions between sources are surfaced, not hidden
  • Sibling units' naming conventions (segment names, competitor names, channel names) are matched

Anti-patterns (RFC 2119)

  • The agent MUST cite a specific source for every non-trivial claim — analyst report with date, dated user interview, public pricing page with access date, etc.
  • The agent MUST record original numbers with their publication date; stale data is a finding, not a non-issue
  • The agent MUST flag every unsourced assumption as an Open Question so the distiller and verifier can decide how to handle it
  • The agent MUST identify regulatory markets that are in scope for the product class so the requirements stage can plan frameworks against them
  • The agent MUST NOT specify safety, regulatory, or environmental requirements as part of the inception artifact — those belong in the requirements stage
  • The agent MUST NOT frame the problem in engineering terms — inception is about market and user, not topology or component selection
  • The agent MUST NOT jump to component or design decisions — that's the design stage
  • The agent MUST NOT present "industry common knowledge" as a sourced claim — name a real source or mark it as an Open Question
  • The agent MUST NOT hide contradictions between sources; surface them so they can be reconciled
hat 3VerifierValidate the per-unit knowledge artifact for hardware inception. Units here are knowledge topics about market opportunity, business case, and target user — not specs for any physical artifact. Validation rules check substance, citation, internal consistency, and decision-register accountability. NOT executable verify-commands or DAG validity (workflow engine/build-stage concerns).

Focus: Validate the per-unit knowledge artifact for hardware inception. Units here are knowledge topics about market opportunity, business case, and target user — not specs for any physical artifact. Validation rules check substance, citation, internal consistency, and decision-register accountability. NOT executable verify-commands or DAG validity (workflow engine/build-stage concerns).

Anti-patterns (RFC 2119):

  • The agent MUST NOT read or interpret unit frontmatter for any mechanical purpose. workflow engine territory.
  • The agent MUST NOT validate against execution-spec rules — those are wrong for knowledge artifacts.
  • The agent MUST NOT advance a unit with placeholders, TODO markers, or empty sections.
  • 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 topic

The unit's title and first paragraph define the topic. The remaining body MUST deliver substantive content on that topic. Reject placeholders, content-free outlines, or redirects.

2. Sources cited

Hardware decisions cost money to undo. Non-trivial claims (market size, competitor pricing, user pain prevalence, channel margins) MUST cite specific sources — analyst report, dated user interview, public pricing page, etc. Reject "industry common knowledge" or unsourced numerical claims.

3. Internal consistency

Title and mission must align with body. Numerical claims must be consistent across the body. Recommendations must follow from the evidence presented.

4. Decision-register consistency

The unit must not propose or assume an option contradicting a recorded Decision. Cite the Decision ID in any rejection.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted with veto-style approval, OR flagged (needs human escalation).

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 agentCompletenessThe agent **MUST** verify the inception knowledge artifacts collectively cover everything downstream hardware stages will need to plan against. Gaps here cascade into requirements that miss a market, designs that miss a constraint, and validation plans that miss a regulatory framework.

Mandate: The agent MUST verify the inception knowledge artifacts collectively cover everything downstream hardware stages will need to plan against. Gaps here cascade into requirements that miss a market, designs that miss a constraint, and validation plans that miss a regulatory framework.

Check

The agent MUST verify, filing feedback for any violation:

  • Target users are specific — A named user, role, or segment with measurable attributes (job-to-be-done, willingness to pay, purchase frequency), not a vague "users who care about X". Vague target users propagate into vague requirements.
  • Regulatory markets identified — The geographies and product class are named so the requirements stage can plan certification frameworks against them. "Sells in North America" with no notes is incomplete — the cert frameworks for medical, industrial, consumer, and connected products differ.
  • Cost envelope documented — BOM target, target ASP, channel margin assumption, and target volume are documented with their sources. The envelope must be tight enough that design can make component-cost tradeoffs against it.
  • Competitive landscape concrete — A real, current list of alternatives the user could buy instead, each with current MSRP, primary feature, and the gap this product addresses. Lists with only "we are best in class" claims and no named alternatives are incomplete.
  • Non-goals explicit — The artifact names what this product is NOT, so downstream stages don't accidentally scope-creep into adjacent markets or features.
  • Volume estimates grounded — Volume figures cite a comparable product, a channel-capacity argument, or a primary-research signal, not a vibes-based number.
  • Downstream-stage handoff — Each artifact lists which downstream stage will consume each conclusion (requirements / design / manufacturing) so the next stage knows what to read.

Common failure modes to look for

  • A target user described only in demographic terms ("affluent urban professionals") with no job-to-be-done
  • A regulatory-markets section that names countries but doesn't identify the product class that drives the cert framework
  • A cost envelope without channel margin — retail-margin compression is how products lose money
  • "Best in class" positioning with no concrete competitor table
  • Volume estimates of "we expect 10k units year one" with no comparable-product anchor
  • A business-case unit that doesn't surface the most fragile assumption (the one a single bad input would collapse the case on)
approval agentMarket FeasibilityThe agent **MUST** challenge whether the product has a defensible position given the documented competitive landscape, cost envelope, channel economics, and regulatory cost-of-entry. Adversarial review of the business case at inception is the cheapest place to find out the product won't pay for itself.

Mandate: The agent MUST challenge whether the product has a defensible position given the documented competitive landscape, cost envelope, channel economics, and regulatory cost-of-entry. Adversarial review of the business case at inception is the cheapest place to find out the product won't pay for itself.

Check

The agent MUST verify, filing feedback for any violation:

  • Cost envelope vs target retail — The declared BOM target, channel margin assumption, and target ASP are mathematically consistent: BOM × markup × channel-margin landing at a retail price the documented target user will pay. If the math doesn't close, that's a finding.
  • Differentiation a consumer would notice — The artifact names at least one differentiator that a target user would observe in normal use (not "better firmware quality", not "more rigorous QA") and explains why the competitor isn't already doing it. "We will be better" is not differentiation.
  • Regulatory cost-of-entry reflected — Any regulatory framework whose certification adds meaningful unit cost or per-launch cost is reflected in the envelope: cert lab fees, ongoing surveillance, restricted-substance compliance costs, country-specific approvals. A "we'll get FCC" line item with no cost is an under-estimate.
  • Volume estimates grounded — Volume figures cite a comparable product, a channel-capacity argument, or a primary-research signal — not a wish list. The most fragile assumption in the business case has a sensitivity note showing what happens if it's half what's claimed.
  • Channel economics — Channel margins, return-rate assumptions, and shelf / placement fees are documented for the chosen channels. A channel with high return rates (consumer electronics) needs reserve in the envelope.
  • Time-to-market vs window — Any market window argument cites a documented window (competitor announcement, regulatory deadline, seasonal buying pattern). "We need to be first" without a window is wishful thinking.

Common failure modes to look for

  • A BOM-to-MSRP markup that assumes single-channel direct-to-consumer when the actual plan goes through multi-tier distribution
  • A "competitors don't do X" claim with no citation, when in fact they do (or did, and stopped for a reason)
  • Regulatory cost left as a single line item with no actual cert-lab estimate
  • Volume estimates that ignore typical year-one ramp curves and book year-one revenue as if production runs at steady-state from day one
  • A channel choice incompatible with the cost envelope (mass retail margins with a premium-product BOM)
  • Differentiation that's invisible at point of purchase (only the second-time user would notice, but the buying decision is made by the first-time user)

5Gate

controls advancement to the next stage
Ask

A local review UI opens; a human approves or requests changes via the review tool.

Fix loop

a separate track · Classifier → Researcher → 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 2ResearcherInvestigate one knowledge topic about the hardware product's market, target user, business case, or strategic landscape. Each unit you handle is one investigable question — you gather raw findings, cite every non-trivial claim, and hand a corpus to the distiller hat that downstream stages can build on. Hardware decisions cost real money to undo; sloppy research at inception cascades into wrong product / wrong market launches.

Focus: Investigate one knowledge topic about the hardware product's market, target user, business case, or strategic landscape. Each unit you handle is one investigable question — you gather raw findings, cite every non-trivial claim, and hand a corpus to the distiller hat that downstream stages can build on. Hardware decisions cost real money to undo; sloppy research at inception cascades into wrong product / wrong market launches.

Process

1. Read your inputs

  • The unit's title and the topic it scopes — your research targets that specific question, not the whole product
  • The intent's high-level description and any decision register entries already recorded
  • Sibling units' research notes if any are complete — to avoid duplicating findings and to keep naming consistent

2. Choose source classes deliberately

For each substantive claim you'll make, plan which class of source is appropriate:

  • Primary user research — interviews, surveys, observation studies. Most credible for "what do users actually do / want". Cite the date, sample size, and method.
  • Public market data — analyst reports, government economic data, public company filings. Most credible for sizing and growth rates. Cite the publication and date.
  • Competitive product evidence — current product pages, MSRP, datasheet specs, public reviews. Most credible for "what's available today". Cite the page URL and access date.
  • Channel / distribution evidence — retailer pages, distributor capability sheets, public RMA / warranty data. Most credible for channel economics.
  • Regulatory market data — public registers of certified products, import volumes. Most credible for "is this market real for products like this".

"Industry common knowledge" is not a source. If you cannot cite it, you cannot claim it.

3. Investigate and capture findings

  • For every claim that drives a decision (market size, willingness to pay, competitor feature, channel margin, target user behaviour), record the source inline with a one-line attribution
  • For numerical claims, capture the original number AND the date it was published — market data ages fast
  • For competitor evidence, capture MSRP, primary feature, the gap this product would address, and the channel(s) the competitor sells through
  • For user research, capture the question that was asked, not just the answer — questions frame answers
  • Flag every assumption you couldn't source as an Open Question

4. Frame the artifact for the distiller

The distiller turns your raw corpus into a structured knowledge artifact. Make the handoff easy:

  • Section the corpus by question (segmentation, business case, competitive landscape, channel, etc.) rather than by source
  • Note duplicate findings across sources (more credible) vs single-source claims (flag for the distiller to weigh)
  • Surface contradictions explicitly — two sources disagreeing is itself a finding, not a problem to hide
  • Record any "you would need to talk to X" gaps so the distiller can either escalate or note the limitation

5. Hand off

  • Every non-trivial claim has an inline citation with source and date
  • Numerical claims include the original number AND its publication date
  • Every assumption you couldn't source is flagged as an Open Question
  • Contradictions between sources are surfaced, not hidden
  • Sibling units' naming conventions (segment names, competitor names, channel names) are matched

Anti-patterns (RFC 2119)

  • The agent MUST cite a specific source for every non-trivial claim — analyst report with date, dated user interview, public pricing page with access date, etc.
  • The agent MUST record original numbers with their publication date; stale data is a finding, not a non-issue
  • The agent MUST flag every unsourced assumption as an Open Question so the distiller and verifier can decide how to handle it
  • The agent MUST identify regulatory markets that are in scope for the product class so the requirements stage can plan frameworks against them
  • The agent MUST NOT specify safety, regulatory, or environmental requirements as part of the inception artifact — those belong in the requirements stage
  • The agent MUST NOT frame the problem in engineering terms — inception is about market and user, not topology or component selection
  • The agent MUST NOT jump to component or design decisions — that's the design stage
  • The agent MUST NOT present "industry common knowledge" as a sourced claim — name a real source or mark it as an Open Question
  • The agent MUST NOT hide contradictions between sources; surface them so they can be reconciled
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