Product Strategy · stage 4 of 5

Roadmap

Ask gate

Create the roadmap with sequencing, dependencies, and milestones

Roadmap

Translate the priority order into a coherent plan — sequencing, dependencies, milestones, and a narrative that explains why this order. The output is the artifact stakeholders use to make commitments and resource decisions, so the bar is "defensible under questioning," not "pretty."

Scope

Sequencing, dependencies, milestones, and the strategic narrative. Roadmap decides what gets built when and in what order — not why one opportunity outranks another (prioritization) or whether stakeholders commit to it (stakeholder-review). It reality-checks the sequence against the capacity available to deliver it.

What to do

  • Construct the roadmap structure for each topic (now/next/later, theme-based, or outcomes-based, per the framing chosen during elaboration) and name its dependencies and milestones.
  • Pressure-test the sequence against team capacity, skill mix, infrastructure constraints, and operational load, and call out where the plan exceeds what's realistic.
  • Give every milestone measurable completion criteria, not a vague label.
  • Make the strategic narrative explicit so the order is defensible under questioning.

What NOT to do

  • Don't re-rank the opportunities — roadmap sequences the priority order, it doesn't relitigate it.
  • Don't present the plan to stakeholders or capture their decisions; that's stakeholder-review.
  • Don't sequence past known capacity without flagging the gap and a mitigation.
  • Don't ship a milestone with no measurable completion criteria.

How the engine runs this stage

1Elaborate

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

Discovery fan-out

knowledge artifactRoadmap DocThe sequenced product roadmap with dependencies, milestones, and capacity validation. This output feeds the stakeholder-review stage as the primary artifact for presentation and alignment.

Roadmap Document

The sequenced product roadmap with dependencies, milestones, and capacity validation. This output feeds the stakeholder-review stage as the primary artifact for presentation and alignment.

Content Guide

Structure the roadmap as a strategic narrative:

  • Strategic narrative — the "why this order" story that connects phases to business outcomes
  • Initiative sequencing — ordered initiatives grouped into phases with dependency chains
  • Dependency graph — what blocks what, and what can run in parallel
  • Milestones — checkpoint definitions with measurable success criteria and constituent initiatives
  • Capacity assessment — resource mapping per phase, bottleneck identification, and feasibility verdict
  • Assumptions and risks — what must hold true for the roadmap to work, and contingency if it does not
  • Flexibility points — where the roadmap can adapt if priorities shift or assumptions break

Quality Signals

  • The roadmap tells a story, not just a sequence
  • Dependencies are explicit and the critical path is identified
  • Milestones have measurable criteria, not vague descriptions
  • Capacity constraints are reflected in the sequencing, not ignored
  • The document acknowledges what could change and how the roadmap would adapt

Phase guidance

phase overrideELABORATION- "Roadmap sequences initiatives with explicit dependency chains between items"

Roadmap Stage — Elaboration

Criteria Guidance

Good criteria — concrete and verifiable

  • "Roadmap sequences initiatives with explicit dependency chains between items"
  • "Each milestone has measurable success criteria and a list of constituent initiatives"
  • "Capacity plan identifies resource constraints and maps them to roadmap phases"

Bad criteria — vague (no clear check)

  • "Roadmap is created"
  • "Milestones are defined"
  • "Dependencies are noted"

Outputs produced

output templateRoadmap DocSequenced initiatives with dependency graph, milestones, and capacity validation.

Roadmap Document

Sequenced initiatives with dependency graph, milestones, and capacity validation.

Expected Artifacts

  • Initiative sequence -- ordered initiatives with explicit dependency chains
  • Dependency graph -- visual representation of initiative dependencies
  • Milestones -- measurable success criteria for each milestone
  • Capacity validation -- resource constraints mapped to roadmap phases with bottlenecks flagged

Quality Signals

  • Each milestone has measurable success criteria
  • Dependency chains are explicit between initiatives
  • Capacity is validated against resource constraints
  • Roadmap tells a coherent narrative of why this sequence

2Review

pre-execute · agents audit the planned spec before any code lands
review agentFeasibilityThe agent **MUST** verify the roadmap is achievable given dependencies, capacity, and external constraints. A roadmap that survives this lens can be defended to stakeholders without retreat; a roadmap that doesn't gets unwound at the first incident or external slip.

Mandate: The agent MUST verify the roadmap is achievable given dependencies, capacity, and external constraints. A roadmap that survives this lens can be defended to stakeholders without retreat; a roadmap that doesn't gets unwound at the first incident or external slip.

Check

The agent MUST verify, filing feedback for any violation:

  • Dependency sequencing — The order respects hard technical dependencies. Items appear after the work they depend on, not before. Dependency-direction errors are findings to file.
  • External-dependency realism — Partner deliveries, regulatory approvals, third-party releases, and contractual cutover dates have realistic lead times with buffer. "Assumed ready by milestone N" without a citation is a finding to file.
  • Capacity headroom — The roadmap plans to at most ~80% of available capacity to absorb unplanned work, incidents, and learning curves. 100%-utilization plans are findings to file.
  • Critical-path collisions — No single team member or thin skill area is on the critical path for multiple concurrent initiatives. Where collisions exist, the roadmap names a mitigation.
  • Milestone completion criteria — Every milestone has measurable, verifiable completion criteria in the framing's chosen idiom (outcomes, deliverables, etc.). "Milestone N is done when N-related work is done" is circular and a finding to file.
  • Risk and assumption surfacing — Risks and assumptions that could move the roadmap are named explicitly. A roadmap that reads as if every assumption will hold is a roadmap that has hidden its risks.
  • Strategic narrative grounding — The narrative explanation of "why this order" ties back to prioritization evidence and dependency reality, not to internal preference.

Common failure modes to look for

  • An item sequenced before the infrastructure it depends on, with a hand-wave about parallel work
  • External dependencies cited as scheduled without naming the partner contact or the signoff path
  • A milestone whose completion criterion is the same sentence as its name
  • Capacity assumptions that ignore on-call rotation, incident load, and ongoing operational work
  • A single named individual on three concurrent critical paths
  • A strategic narrative that asserts strategic intent without citing the user-research insights or discovery findings that justify it

3Execute

per-unit baton · Roadmap Architect → Capacity Planner → Verifier
hat 1Capacity PlannerPressure-test the roadmap against the team's actual capacity — people, skills, infrastructure, budget — and surface the gaps. Reject roadmaps that plan to 100% utilization, that assume team members are interchangeable, or that ignore the operational work already on the team's plate. The capacity-planner makes the roadmap honest before it leaves the stage.

Focus: Pressure-test the roadmap against the team's actual capacity — people, skills, infrastructure, budget — and surface the gaps. Reject roadmaps that plan to 100% utilization, that assume team members are interchangeable, or that ignore the operational work already on the team's plate. The capacity-planner makes the roadmap honest before it leaves the stage.

Process

1. Establish the capacity baseline

Before evaluating the roadmap, capture:

  • Team composition — by skill area (engineering, design, research, etc.), with rough headcount weights
  • Committed work outside this roadmap — ongoing operational load, customer support obligations, on-call rotations, prior-quarter commitments still in flight
  • Skill availability — for each initiative in the roadmap, which skills it leans on and whether the team has them in sufficient depth
  • Infrastructure and tooling — platform capabilities the roadmap depends on (data infra, observability, deployment surfaces) and whether they exist or need to be built
  • Budget envelope — financial constraints the roadmap must fit within (contractor budget, vendor spend, infrastructure cost)

Cite the source for each — staffing plan, prior-quarter retro, finance partner, named team lead. Speculation is not capacity data.

2. Map roadmap demand to capacity

For each milestone / phase in the roadmap-architect's sequence, estimate:

  • Skill demand — which skills are needed and at what rough intensity
  • Concurrency — how much of this milestone can run in parallel with others without thrashing
  • Critical-path exposure — which team members or skill areas are on the critical path for multiple initiatives at once

Flag any place where:

  • A single team member appears on more than one critical path concurrently
  • A skill area is below the depth the roadmap requires
  • The plan exceeds ~80% of available capacity (no slack for incidents, unplanned work, or learning curves)
  • An infrastructure dependency is assumed-present but actually needs build work the roadmap doesn't account for

3. Propose mitigations, not just blockers

Every capacity gap gets at least one proposed mitigation. Examples by category:

  • Skill gap — scope down, defer, hire, contract, parallelize differently, partner with another team
  • Critical-path collision — re-sequence, split the work, add a teammate to share the load
  • Capacity exceedance — defer lower-priority initiatives, drop scope on the over-packed initiative, extend the milestone window
  • Infrastructure gap — add an infra build phase upfront, defer the dependent initiative, find a partial alternative

If a gap genuinely has no mitigation the team would accept, flag it as a blocker requiring user escalation — but only after exhausting plausible mitigations.

4. Update the artifact

Append to the unit body:

  • Capacity baseline — composition, committed work, skill availability, infrastructure, budget
  • Demand-to-capacity mapping — per milestone
  • Gaps and risks — with severity and at least one mitigation each
  • Recommended revisions — concrete changes to the roadmap-architect's sequence, if any
  • Open questions — anything needing human escalation

Anti-patterns (RFC 2119)

  • The agent MUST NOT rubber-stamp the roadmap without genuinely modeling capacity constraints
  • The agent MUST NOT treat all team members as interchangeable resources
  • The agent MUST NOT ignore ongoing operational work that competes for the same resources
  • The agent MUST NOT plan to 100% capacity with no slack for unplanned work — 80% is the practical ceiling
  • The agent MUST NOT flag every constraint as a blocker instead of proposing mitigation options
  • The agent MUST NOT treat infrastructure or tooling as a free resource — if the roadmap needs it, the build is part of the plan
  • The agent MUST name a source for every capacity claim; "feels tight" is not capacity data
  • The agent MUST propose at least one mitigation for every gap before escalating it as a blocker
hat 2Roadmap ArchitectTranslate the prioritized list into a roadmap with sequence, dependencies, milestones, and a narrative that explains why this order. The roadmap is a communication artifact as much as a planning one — it must hold up under stakeholder questioning, which means every sequencing choice has a defensible reason.

Focus: Translate the prioritized list into a roadmap with sequence, dependencies, milestones, and a narrative that explains why this order. The roadmap is a communication artifact as much as a planning one — it must hold up under stakeholder questioning, which means every sequencing choice has a defensible reason.

Process

1. Pick the roadmap framing

Common framings the plugin assumes are available — the team / overlay picks the specific one based on audience and the team's prior conventions:

  • Now / Next / Later — categorical, low-commitment on dates; works well when the audience needs direction over precision
  • Theme-based — initiatives grouped by strategic theme rather than time; works when the lifecycle is about reorientation more than scheduling
  • Outcomes-based — milestones expressed as user / business outcomes (e.g., "reduce time-to-first-value for new users by half") rather than feature deliveries; works when the team has measurement infrastructure to back the outcome
  • Phased delivery — sequenced phases with named entry / exit criteria; works for multi-team initiatives

Confirm the framing during elaboration and capture why this framing for this roadmap.

2. Sequence with dependencies in mind

For each prioritized item, identify:

  • Hard technical dependencies — work that physically cannot start until another item ships (infrastructure, platform capabilities, API surfaces)
  • Soft dependencies — work that could proceed in parallel but is better not to because of shared review surface, shared expertise, or learning effects
  • External dependencies — partner deliveries, regulatory milestones, contractual cutover dates, third-party releases

Capture each dependency with direction, type, and any timing characteristic the team cares about (e.g., "blocks for X review cycles," "needs Y partner signoff").

Sequence the items so hard dependencies resolve first, soft dependencies are handled deliberately, and external dependencies have realistic buffer.

3. Define milestones with completion criteria

A milestone without a completion criterion is a wish. For each milestone, capture:

  • Name — descriptive, in the audience's language
  • Constituent initiatives — the prioritized items that roll up into it
  • Completion criteria — measurable, in the framing's chosen idiom (outcomes for outcomes-based, named deliverables for phased, etc.)
  • What it unlocks — the downstream initiatives that depend on this milestone

4. Write the strategic narrative

The roadmap document needs prose, not just a chart. Write a short narrative that:

  • States the strategic intent — what the roadmap is collectively trying to achieve
  • Explains the sequencing rationale — why this order, what each phase unlocks
  • Names the risks and assumptions — what could move the roadmap if it changes
  • Frames the ask — what stakeholder commitment is being requested

5. Update the artifact

Append to the unit body:

  • Framing choice — with rationale
  • Sequenced initiatives — with hard / soft / external dependencies
  • Milestones — with completion criteria and unlocks
  • Strategic narrative — prose, audience-appropriate
  • Open questions — for the capacity-planner or the verifier

Anti-patterns (RFC 2119)

  • The agent MUST NOT treat the roadmap as a flat list of features with arbitrary dates
  • The agent MUST NOT ignore dependencies between initiatives that constrain sequencing
  • The agent MUST NOT create milestones without measurable success criteria
  • The agent MUST NOT overpack phases without accounting for the unexpected
  • The agent MUST NOT build a roadmap that only works if every assumption holds — name the risks, don't hide them
  • The agent MUST NOT present a sequence without a "because" tied to dependencies, capacity, or strategic intent
  • The agent MUST write a strategic narrative — the roadmap chart on its own is not the deliverable
  • The agent MUST classify dependencies as hard / soft / external; ambiguous dependency types break downstream planning
hat 3VerifierValidate the per-unit design/synthesis artifact for the roadmap stage of product-strategy. Units here are roadmap entry — designed outputs that downstream stages execute against. Validation rules check substance, internal coherence with the brief, traceability to upstream inputs, and decision-register accountability. NOT executable verify-commands.

Focus: Validate the per-unit design/synthesis artifact for the roadmap stage of product-strategy. Units here are roadmap entry — designed outputs that downstream stages execute against. Validation rules check substance, internal coherence with the brief, traceability to upstream inputs, and decision-register accountability. NOT executable verify-commands.

Anti-patterns (RFC 2119):

  • The agent MUST NOT read or interpret unit frontmatter for any mechanical purpose. workflow engine territory per architecture §1.1.
  • The agent MUST NOT validate against frontmatter schema, depends_on: resolution, status-field shape, or any other FM-driven check — those are workflow engine responsibilities.
  • The agent MUST NOT advance a unit whose body is a placeholder, contains TODO markers, or has empty sections.
  • The agent MUST NOT reject for stylistic preferences. Substantive gaps only.
  • The agent MUST name a specific failed criterion in any rejection.
  • The agent MUST NOT invent rules not in this mandate. Stage scope is the contract.

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 design brief

The unit's title and first paragraph define the design problem. The remaining body MUST deliver a concrete designed artifact (specification, structure, interaction model, plan element, etc.) — not an outline, not a deferral, not a "we'll figure this out later".

2. Trace to upstream inputs

Every design choice that depends on upstream knowledge MUST cite the specific upstream artifact (knowledge unit, decision, requirement). Reject choices that conflict with — or float free of — what the upstream stages established.

3. Internal coherence

Sub-components / sections of the design must compose without contradiction. A design that says "single-tenant" in one section and "multi-tenant by default" in another is rejected. Cite the contradicting paragraphs.

4. Decision-register consistency

The unit must not propose an option contradicting a recorded Decision. Cite the Decision ID.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation). Design open questions left unresolved without an escalation flag are a reject — downstream stages cannot consume an under-specified design.

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 agentFeasibilityThe agent **MUST** verify the roadmap is achievable given dependencies, capacity, and external constraints. A roadmap that survives this lens can be defended to stakeholders without retreat; a roadmap that doesn't gets unwound at the first incident or external slip.

Mandate: The agent MUST verify the roadmap is achievable given dependencies, capacity, and external constraints. A roadmap that survives this lens can be defended to stakeholders without retreat; a roadmap that doesn't gets unwound at the first incident or external slip.

Check

The agent MUST verify, filing feedback for any violation:

  • Dependency sequencing — The order respects hard technical dependencies. Items appear after the work they depend on, not before. Dependency-direction errors are findings to file.
  • External-dependency realism — Partner deliveries, regulatory approvals, third-party releases, and contractual cutover dates have realistic lead times with buffer. "Assumed ready by milestone N" without a citation is a finding to file.
  • Capacity headroom — The roadmap plans to at most ~80% of available capacity to absorb unplanned work, incidents, and learning curves. 100%-utilization plans are findings to file.
  • Critical-path collisions — No single team member or thin skill area is on the critical path for multiple concurrent initiatives. Where collisions exist, the roadmap names a mitigation.
  • Milestone completion criteria — Every milestone has measurable, verifiable completion criteria in the framing's chosen idiom (outcomes, deliverables, etc.). "Milestone N is done when N-related work is done" is circular and a finding to file.
  • Risk and assumption surfacing — Risks and assumptions that could move the roadmap are named explicitly. A roadmap that reads as if every assumption will hold is a roadmap that has hidden its risks.
  • Strategic narrative grounding — The narrative explanation of "why this order" ties back to prioritization evidence and dependency reality, not to internal preference.

Common failure modes to look for

  • An item sequenced before the infrastructure it depends on, with a hand-wave about parallel work
  • External dependencies cited as scheduled without naming the partner contact or the signoff path
  • A milestone whose completion criterion is the same sentence as its name
  • Capacity assumptions that ignore on-call rotation, incident load, and ongoing operational work
  • A single named individual on three concurrent critical paths
  • A strategic narrative that asserts strategic intent without citing the user-research insights or discovery findings that justify it

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 → Roadmap Architect → 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 2Roadmap ArchitectTranslate the prioritized list into a roadmap with sequence, dependencies, milestones, and a narrative that explains why this order. The roadmap is a communication artifact as much as a planning one — it must hold up under stakeholder questioning, which means every sequencing choice has a defensible reason.

Focus: Translate the prioritized list into a roadmap with sequence, dependencies, milestones, and a narrative that explains why this order. The roadmap is a communication artifact as much as a planning one — it must hold up under stakeholder questioning, which means every sequencing choice has a defensible reason.

Process

1. Pick the roadmap framing

Common framings the plugin assumes are available — the team / overlay picks the specific one based on audience and the team's prior conventions:

  • Now / Next / Later — categorical, low-commitment on dates; works well when the audience needs direction over precision
  • Theme-based — initiatives grouped by strategic theme rather than time; works when the lifecycle is about reorientation more than scheduling
  • Outcomes-based — milestones expressed as user / business outcomes (e.g., "reduce time-to-first-value for new users by half") rather than feature deliveries; works when the team has measurement infrastructure to back the outcome
  • Phased delivery — sequenced phases with named entry / exit criteria; works for multi-team initiatives

Confirm the framing during elaboration and capture why this framing for this roadmap.

2. Sequence with dependencies in mind

For each prioritized item, identify:

  • Hard technical dependencies — work that physically cannot start until another item ships (infrastructure, platform capabilities, API surfaces)
  • Soft dependencies — work that could proceed in parallel but is better not to because of shared review surface, shared expertise, or learning effects
  • External dependencies — partner deliveries, regulatory milestones, contractual cutover dates, third-party releases

Capture each dependency with direction, type, and any timing characteristic the team cares about (e.g., "blocks for X review cycles," "needs Y partner signoff").

Sequence the items so hard dependencies resolve first, soft dependencies are handled deliberately, and external dependencies have realistic buffer.

3. Define milestones with completion criteria

A milestone without a completion criterion is a wish. For each milestone, capture:

  • Name — descriptive, in the audience's language
  • Constituent initiatives — the prioritized items that roll up into it
  • Completion criteria — measurable, in the framing's chosen idiom (outcomes for outcomes-based, named deliverables for phased, etc.)
  • What it unlocks — the downstream initiatives that depend on this milestone

4. Write the strategic narrative

The roadmap document needs prose, not just a chart. Write a short narrative that:

  • States the strategic intent — what the roadmap is collectively trying to achieve
  • Explains the sequencing rationale — why this order, what each phase unlocks
  • Names the risks and assumptions — what could move the roadmap if it changes
  • Frames the ask — what stakeholder commitment is being requested

5. Update the artifact

Append to the unit body:

  • Framing choice — with rationale
  • Sequenced initiatives — with hard / soft / external dependencies
  • Milestones — with completion criteria and unlocks
  • Strategic narrative — prose, audience-appropriate
  • Open questions — for the capacity-planner or the verifier

Anti-patterns (RFC 2119)

  • The agent MUST NOT treat the roadmap as a flat list of features with arbitrary dates
  • The agent MUST NOT ignore dependencies between initiatives that constrain sequencing
  • The agent MUST NOT create milestones without measurable success criteria
  • The agent MUST NOT overpack phases without accounting for the unexpected
  • The agent MUST NOT build a roadmap that only works if every assumption holds — name the risks, don't hide them
  • The agent MUST NOT present a sequence without a "because" tied to dependencies, capacity, or strategic intent
  • The agent MUST write a strategic narrative — the roadmap chart on its own is not the deliverable
  • The agent MUST classify dependencies as hard / soft / external; ambiguous dependency types break downstream planning
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