Dev Evangelism · stage 3 of 5

Create

Ask gate

Produce the content — posts, slides, demos, videos

Create

The build stage of the dev-evangelism lifecycle: turn the narrative brief into the actual content assets — written posts, talk decks, demo projects, video scripts. This is where abstract messaging becomes concrete artifacts developers can read, watch, and run.

Scope

Producing the assets the narrative scoped, with any runnable code the content depends on owned alongside the asset. Create decides how the story becomes concrete artifacts — it does not redefine the story (narrative) or distribute the result (publish). Each unit covers one asset family — a post, a talk, a demo project, a video.

What to do

Author each asset to the narrative brief's arc and takeaways — copy, structure, calls-to-action shaped to the format.
Build any code or live demo the content references so it's working and reproducible from a clean environment, with documented setup.
Keep every published claim backed by proof the reader can run or inspect.
Confirm each asset actually hits the takeaways the narrative defined.

What NOT to do

Don't reshape the story arc or messaging — a wrong narrative is a revisit upstream, not a quiet rewrite here.
Don't distribute, cross-post, or seed communities — that's the publish stage.
Don't ship a demo that only runs on your machine.
Don't add assets the narrative didn't scope.

How the engine runs this stage

1Elaborate

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

Inputs consumed

story-arcfrom Narrative

Discovery fan-out

knowledge artifactContent PackageThe collection of developer evangelism content produced for multi-channel distribution. This output feeds the publish stage for distribution planning.

Content Package

The collection of developer evangelism content produced for multi-channel distribution. This output feeds the publish stage for distribution planning.

Content Guide

Organize the package by content format and target audience:

Blog posts -- technically grounded articles with working code examples and clear takeaways
Talk materials -- slides following the narrative arc with speaker notes and timing
Demos -- working projects with README, setup instructions, and annotated code
Video content -- scripts or outlines with technical verification notes
Code examples -- standalone snippets that compile and run, annotated for context

Quality Signals

Code examples compile and run without modification
Demos are reproducible from a clean environment
Each asset follows the narrative arc and delivers key takeaways
Technical claims are substantiated by working examples

Phase guidance

phase overrideELABORATION- "Blog post includes working code examples that the reader can copy-paste and run"

Create Stage — Elaboration

Criteria Guidance

Good criteria — concrete and verifiable

"Blog post includes working code examples that the reader can copy-paste and run"
"Talk slides follow a narrative arc with no slide exceeding 3 bullet points"
"Demo runs end-to-end without manual setup steps beyond what the README documents"

Bad criteria — vague (no clear check)

"Content is created"
"Demo works"
"Slides look good"

Outputs produced

output templateContent PackageAll produced content assets -- blog posts, slides, demos, videos -- ready for distribution.

Content Package

All produced content assets -- blog posts, slides, demos, videos -- ready for distribution.

Expected Artifacts

Blog posts -- technically grounded with working code examples and clear takeaways
Talk materials -- slides following the narrative arc, speaker notes, and timing guidance
Demos -- working projects with README, setup instructions, and annotated code
Video scripts -- structured scripts or outlines with technical verification notes

Quality Signals

Code examples compile and run without modification
Demos are reproducible from a clean environment
Each asset follows the narrative arc and delivers key takeaways
Content reads as technical education, not marketing material

2Review

pre-execute · agents audit the planned spec before any code lands

review agentEngagementThe agent **MUST** verify the produced content is shaped for developer engagement — opens strongly, holds attention, delivers the narrative's takeaways explicitly, and closes on a specific action. Files feedback on any violation; does NOT rewrite assets.

Mandate: The agent MUST verify the produced content is shaped for developer engagement — opens strongly, holds attention, delivers the narrative's takeaways explicitly, and closes on a specific action. Files feedback on any violation; does NOT rewrite assets.

Check

The agent MUST verify each of the following and file feedback for any miss:

Hook in the open — the hook from the narrative brief is present in the first 2 sentences of written long-form, the first slide of a deck, the first 15 seconds of a video, or the equivalent opening surface for the format
Format-shape conformance — long-form has scannable structure with annotated code; short-form is one insight + one detail + one CTA; talk decks are visual not text-walls; video scripts are scripted, not free-form; format conventions match the format
Narrative arc traceable — a reviewer who reads the asset can identify which beat in the narrative brief each section serves; sections that don't trace back are scope creep
Takeaways explicit — every takeaway from the narrative brief appears explicitly in the asset; implied takeaways are gaps because audiences don't infer reliably
Calls-to-action specific — the close names a specific action the audience can take (try the demo, read the doc, file the issue, attend the event); generic closes ("hope this was useful") are findings
Cross-references to runnable proof — every claim flagged (needs demo) / (needs benchmark) / (needs code sample) by the narrative brief has a reference to the demo-builder's artifact in this asset
Audience vocabulary match — the asset's language matches the segments from the audience landscape and the narrative brief's tone guidance; jargon level matches segment skill level

Common failure modes to look for

Generic openings that don't match the brief's hook
Slides with paragraphs of text instead of visual storytelling
Video scripts that read as essays rather than spoken language
Multiple takeaways crammed into the close, none of them landing
Marketing language that survived the editor pass (revolutionary, world-class, best-in-class)
Claims that the demo-builder is supposed to back, with no link or pointer to the demo in the asset
Cross-asset inconsistency in terminology (the same concept named differently across sibling assets in the same intent)

review agentTechnical AccuracyThe agent **MUST** verify every technical claim in the created content is accurate, every demo is reproducible, and every code sample runs. Files feedback on any violation; does NOT fix the asset or rebuild the demo.

Mandate: The agent MUST verify every technical claim in the created content is accurate, every demo is reproducible, and every code sample runs. Files feedback on any violation; does NOT fix the asset or rebuild the demo.

Check

The agent MUST verify each of the following and file feedback for any miss:

Code runnability — every code sample in the asset compiles and runs against the runtime version the demo-builder pinned; copy-paste-and-run is the contract
Demo reproducibility — every demo can be run end-to-end from a clean environment within the documented time budget; setup steps are complete, dependencies pinned, no latest versions, no hardcoded secrets
API / version / config currency — API references, version numbers, configuration keys, and CLI invocations match the runtime the demo-builder targeted; out-of-date references are findings
Claim-to-proof alignment — every flagged claim from the narrative brief has a matching demo or code sample that actually demonstrates the claim; demos that demonstrate something different from what the asset claims are the highest-priority finding
Benchmark methodology disclosed — any performance claim cites the benchmark's environment specs, methodology, and raw output; "faster" without numbers and methodology is unsupported
Error handling visible — demos that will be presented live or run by readers handle the obvious failure modes (network, missing creds, wrong runtime version) with clear messages, not stack traces
Cross-reference precision — references from the asset to the demo name a specific entry point (repo URL + branch / tag, sandbox URL, deck slide number, script timestamp), not a vague "see the demo"

Common failure modes to look for

Code blocks that look right but reference symbols, methods, or APIs that don't exist in the named version
Demos pinned to latest (or unpinned) that will rot the moment a dependency updates
Hardcoded API keys, tokens, or environment-specific paths in the demo repo
A README that says "run npm start" but the demo also needs npm install and a database running
Benchmarks cited without environment specs (hardware, runtime version, dataset size)
An asset that says the demo shows X when the demo actually shows X' (a divergence that an attentive reader will catch and lose trust over)
Performance claims as adjectives ("blazing fast", "highly performant") rather than measurements

3Execute

per-unit baton · Content Creator → Demo Builder → Verifier

hat 1Content CreatorProduce the content asset itself — the written post, the talk deck and speaker notes, the video script, the podcast outline, the live-coding session plan. You're executing the narrative brief's arc in the specific format(s) this unit is responsible for. Substance first, polish second. Developers smell marketing before they finish a paragraph; the asset has to earn trust by being useful.

Focus: Produce the content asset itself — the written post, the talk deck and speaker notes, the video script, the podcast outline, the live-coding session plan. You're executing the narrative brief's arc in the specific format(s) this unit is responsible for. Substance first, polish second. Developers smell marketing before they finish a paragraph; the asset has to earn trust by being useful.

Process

1. Read your inputs

The unit's narrative-arc slice from NARRATIVE-BRIEF.md (arc shape, hook, beats, takeaways, audience segments, format adaptations, claims flagged for runnable proof)
Sibling create units' completed assets to maintain consistent voice, terminology, and cross-reference targets
The demo-builder's runnable artifacts for this unit, once available — your prose / slides / script reference them by name, so the names need to match

2. Pick the format-specific shape

The narrative brief named which formats this unit produces. For each, the shape is different — DON'T paste the same content into every format and rename the file:

Format	Shape conventions
Long-form written	Opening hook within first 2 sentences, scannable subheadings, code blocks with annotations, concrete takeaways at the end, real links to demo / repo / docs
Short-form written	One central insight, one supporting detail, one call-to-action; cut everything else
Talk deck + notes	Visual slides (image / diagram / one-line claim), full speaker notes per slide, timing per section, demo cue-points called out explicitly
Video script	Cold open hook, scripted core, on-screen call-out cues, action verb in the close; do NOT write a verbatim wall of speech for a 5-minute video
Podcast outline	Question structure (host or interviewer prompts), key beats the speaker hits per question, a closing forward-pointer
Live-coding session	Pre-staged starting point, branch / commit per checkpoint, fallback for failure modes (network down, demo glitches), explicit "what the audience should be able to do after"
Workshop / interactive	Per-section objectives, pre-reqs and setup, exercises with checkpoints, time budget per section

Format-specific shape rules are baseline. Project overlays add platform-specific markup conventions (named CMS embeds, internal templates, design-system tokens) without modifying the plugin defaults.

3. Draft the asset

Drafting rules common to every format:

Open on the hook from the narrative brief — verbatim or adapted to the format, but the cold open is the brief's hook, not a generic intro
Earn every section — if a section doesn't deliver insight, advance the arc, or set up the takeaway, cut it. Length is not a virtue.
Use concrete examples — every abstract claim ("this pattern is faster") gets a specific instance ("a 240ms p99 vs. 410ms in our benchmark") OR is flagged for the demo-builder to provide
Match the audience's vocabulary — the audience landscape says how the segment talks; the narrative brief refined it; the asset has to land it
Cross-link to the demo — every claim the demo-builder is providing proof for needs a reference (a link, a section pointer, a deck slide number) so the reader / viewer / listener can act on it

4. Calls-to-action

Every asset needs an explicit call-to-action that maps to the narrative brief's takeaways. Vague closes ("hope you found this useful") waste the strongest part of the asset — the moment right before the audience leaves. Be specific: try the demo, read the docs, file the issue, join the discussion, attend the next event of this format, follow up.

5. Self-check before handoff

The hook lands within the first 2 sentences / first slide / first 15 seconds (format-dependent) and matches the brief's hook
Every flagged claim from the brief has a reference to runnable proof in this asset (or a TODO: link demo X if the demo-builder hasn't published yet)
Every takeaway from the brief shows up explicitly in the asset (not implied — explicit)
No section reads as marketing copy ("revolutionary", "world-class", "game-changing" — strike or rewrite)
No placeholder text, TODO markers, or lorem ipsum remains
Cross-references to sibling assets in this intent use consistent naming
Format-specific shape conventions above were followed; one format ≠ another with a renamed file

Anti-patterns (RFC 2119)

The agent MUST NOT include code examples that cannot compile or run; if the asset depends on code, the demo-builder is the source of truth
The agent MUST NOT produce content that reads as marketing material rather than technical education
The agent MUST NOT create slides with walls of text instead of visual storytelling
The agent MUST NOT deviate from the narrative brief's arc without naming the reason in the unit body
The agent MUST NOT leave placeholder content, TODO markers, or lorem ipsum in finished assets
The agent MUST NOT cross-post one asset under multiple formats; if the brief asks for multiple formats, write each one to its shape
The agent MUST NOT reference specific named publication platforms, CMS systems, video hosts, or social platforms in the plugin default; project overlays handle named platforms
The agent MUST make every call-to-action specific (a named action the audience can take)
The agent MUST include a reference to runnable proof for every flagged claim
The agent MUST preserve the audience's vocabulary as set by the narrative brief

hat 2Demo BuilderBuild runnable proof for every claim the narrative brief flagged. Demos are working code projects, benchmark scripts, reproducible example apps, sandbox configurations — whatever the asset references as evidence. A demo that fails live or requires undocumented setup undermines the content it was supposed to support; the bar is "a member of the target segment clones the repo and it works in their environment in 10 minutes or less."

Focus: Build runnable proof for every claim the narrative brief flagged. Demos are working code projects, benchmark scripts, reproducible example apps, sandbox configurations — whatever the asset references as evidence. A demo that fails live or requires undocumented setup undermines the content it was supposed to support; the bar is "a member of the target segment clones the repo and it works in their environment in 10 minutes or less."

Process

1. Read your inputs

The narrative brief's flagged-claim list for this unit ((needs demo), (needs benchmark), (needs code sample))
The content-creator's in-progress or completed asset for this unit — your demo's structure needs to match what the asset references by name
Sibling demo-builder units' projects to keep naming, runtime versions, and dependency choices consistent across the intent

2. Pick the demo shape

The flagged-claim drives the demo shape. Don't default to "build an app" when a 30-line snippet would carry the point.

Demo shape	When to use it	Deliverables
Code snippet	Asset references a specific technique or API call in isolation	Snippet file + one-paragraph context block + expected output
Runnable repo	Asset walks through a workflow, integration, or non-trivial example	Repo with README, setup script, working main path, tagged starting and ending points
Benchmark script	Asset cites a measurement comparison	Script, raw output, methodology notes, environment specs
Sandbox / hosted	Asset wants zero-install audience access	Hosted environment URL, source link, reset behavior documented
Workshop track	Asset is a workshop or hands-on session	Repo with branches per checkpoint, recovery instructions for skipped steps, instructor notes
Live-coding plan	Asset is a talk with live coding	Pre-staged starting commit, branch per beat, fallback path if live-coding fails (recorded backup or pre-built endpoint)

3. Build to a reproducibility bar

A demo is "done" when:

A clean machine running a documented runtime version can clone / open / install and reach the working state in the documented time budget
Every dependency is pinned (semver lock, version manifest, container image tag) — latest is forbidden
Every external credential / API key / secret is declared in .env.example or equivalent — never hardcoded
Every assumption about local tooling (specific CLI versions, OS-level packages, host services like databases) is documented in the README setup section
A test pass, lint pass, or smoke check exists so the demo can be re-verified before publish (and re-verified again at future points if dependencies move underneath it)
The repo / sandbox / snippet has a "reset" path so a workshop or live demo can recover from a botched checkpoint

4. Document the demo

Every demo MUST ship a README (or equivalent doc) covering:

What this demonstrates — the specific claim from the asset this demo proves
Setup — runtime version, dependencies, env vars, time budget
Run — the single command (or short sequence) to reach the working state
What to look for — what the audience should see / measure / experience that proves the claim
Caveats — known failure modes, environment-specific behavior, the failure recovery path

If the demo is a benchmark, the README also captures methodology, environment specs, and the raw output the asset cites.

5. Cross-reference with the content-creator's asset

For every flagged claim in the brief:

The demo exists and reaches the working state
The asset's reference to the demo names a specific entry point (repo URL + branch / tag, sandbox URL, slide number, script timestamp)
The asset's description of what the demo shows matches what the demo actually shows; if reality diverges from the asset's claim, escalate to the content-creator BEFORE handoff

6. Live-presentation readiness (if applicable)

If the asset is a talk, video, or workshop, the demo MUST be live-tested:

Walked end-to-end in one continuous session in a clean environment
Tested with the network disabled to identify hidden dependencies on external services
Confirmed against the runtime version actually installed on the presenter's machine
A recorded fallback exists for any segment where live failure is not recoverable

7. Hand off

Hand off when every flagged claim has a working demo, the README documents it, the asset cross-references the demo precisely, and (for live formats) the demo passed an end-to-end live test.

Anti-patterns (RFC 2119)

The agent MUST NOT publish demos that require undocumented environment setup or tooling
The agent MUST NOT build fragile demos that break under live or first-clone conditions
The agent MUST NOT hardcode secrets, API keys, or environment-specific paths
The agent MUST NOT use latest for any dependency; every version is pinned
The agent MUST NOT skip error handling that would cause confusing failures in a live or first-time-use context
The agent MUST NOT ship a demo whose reality diverges from what the asset claims it shows; escalate the divergence instead
The agent MUST NOT reference specific named hosting platforms or sandbox services in the plugin default; project overlays add named platforms
The agent MUST verify each demo runs end-to-end from a clean environment before handoff
The agent MUST document the time budget for setup so the audience knows what they're committing to
The agent MUST provide a recorded fallback for live-presentation demos where failure is not recoverable

hat 3VerifierValidate the per-unit build artifact for the create stage of dev-evangelism. Units here are content artifact — discrete pieces of work with executable acceptance criteria. Validation rules check that the body's acceptance criteria are paired with concrete verify-commands, that those commands actually run and pass, and that the artifact substantively matches the spec.

Focus: Validate the per-unit build artifact for the create stage of dev-evangelism. Units here are content artifact — discrete pieces of work with executable acceptance criteria. Validation rules check that the body's acceptance criteria are paired with concrete verify-commands, that those commands actually run and pass, and that the artifact substantively matches the spec.

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. Body matches the spec it claims to satisfy

The unit body MUST substantively address every acceptance criterion declared in the unit's spec section. Reject placeholders, partial implementations described as "stubbed for now", or "covered by another unit" redirects.

2. Acceptance criteria paired with verify-commands

Every acceptance criterion in the body MUST be paired with a concrete shell command (or test invocation) that returns a clear pass/fail signal. Vague criteria ("works correctly", "tests pass") are a reject. Map verify-commands to the project's actual stack — read package.json / pyproject.toml / Cargo.toml / go.mod to know which test runner / coverage tool / linter the project uses.

3. Verify-commands actually pass

Run the named verify-commands. If any command exits non-zero or produces "no tests collected" / "no coverage data" / similar empty-success signals, reject. Cite the failing command and its exit code in the rejection reason.

4. Decision-register consistency

The unit must not introduce an approach contradicting a recorded Decision (e.g., a sync API when Decision N chose async). Cite the Decision ID.

5. Open questions accounted for

Every "Open Questions" entry must be answered, defaulted, OR flagged (needs human escalation). Build-stage open questions block downstream consumers — be strict.

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 agentEngagementThe agent **MUST** verify the produced content is shaped for developer engagement — opens strongly, holds attention, delivers the narrative's takeaways explicitly, and closes on a specific action. Files feedback on any violation; does NOT rewrite assets.

Check

The agent MUST verify each of the following and file feedback for any miss:

Hook in the open — the hook from the narrative brief is present in the first 2 sentences of written long-form, the first slide of a deck, the first 15 seconds of a video, or the equivalent opening surface for the format
Format-shape conformance — long-form has scannable structure with annotated code; short-form is one insight + one detail + one CTA; talk decks are visual not text-walls; video scripts are scripted, not free-form; format conventions match the format
Narrative arc traceable — a reviewer who reads the asset can identify which beat in the narrative brief each section serves; sections that don't trace back are scope creep
Takeaways explicit — every takeaway from the narrative brief appears explicitly in the asset; implied takeaways are gaps because audiences don't infer reliably
Calls-to-action specific — the close names a specific action the audience can take (try the demo, read the doc, file the issue, attend the event); generic closes ("hope this was useful") are findings
Cross-references to runnable proof — every claim flagged (needs demo) / (needs benchmark) / (needs code sample) by the narrative brief has a reference to the demo-builder's artifact in this asset
Audience vocabulary match — the asset's language matches the segments from the audience landscape and the narrative brief's tone guidance; jargon level matches segment skill level

Common failure modes to look for

Generic openings that don't match the brief's hook
Slides with paragraphs of text instead of visual storytelling
Video scripts that read as essays rather than spoken language
Multiple takeaways crammed into the close, none of them landing
Marketing language that survived the editor pass (revolutionary, world-class, best-in-class)
Claims that the demo-builder is supposed to back, with no link or pointer to the demo in the asset
Cross-asset inconsistency in terminology (the same concept named differently across sibling assets in the same intent)

approval agentTechnical AccuracyThe agent **MUST** verify every technical claim in the created content is accurate, every demo is reproducible, and every code sample runs. Files feedback on any violation; does NOT fix the asset or rebuild the demo.

Check

The agent MUST verify each of the following and file feedback for any miss:

Code runnability — every code sample in the asset compiles and runs against the runtime version the demo-builder pinned; copy-paste-and-run is the contract
Demo reproducibility — every demo can be run end-to-end from a clean environment within the documented time budget; setup steps are complete, dependencies pinned, no latest versions, no hardcoded secrets
API / version / config currency — API references, version numbers, configuration keys, and CLI invocations match the runtime the demo-builder targeted; out-of-date references are findings
Claim-to-proof alignment — every flagged claim from the narrative brief has a matching demo or code sample that actually demonstrates the claim; demos that demonstrate something different from what the asset claims are the highest-priority finding
Benchmark methodology disclosed — any performance claim cites the benchmark's environment specs, methodology, and raw output; "faster" without numbers and methodology is unsupported
Error handling visible — demos that will be presented live or run by readers handle the obvious failure modes (network, missing creds, wrong runtime version) with clear messages, not stack traces
Cross-reference precision — references from the asset to the demo name a specific entry point (repo URL + branch / tag, sandbox URL, deck slide number, script timestamp), not a vague "see the demo"

Common failure modes to look for

Code blocks that look right but reference symbols, methods, or APIs that don't exist in the named version
Demos pinned to latest (or unpinned) that will rot the moment a dependency updates
Hardcoded API keys, tokens, or environment-specific paths in the demo repo
A README that says "run npm start" but the demo also needs npm install and a database running
Benchmarks cited without environment specs (hardware, runtime version, dataset size)
An asset that says the demo shows X when the demo actually shows X' (a divergence that an attentive reader will catch and lose trust over)
Performance claims as adjectives ("blazing fast", "highly performant") rather than measurements

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 → Content Creator → 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

Read the FB body via haiku_feedback_read { intent, stage, feedback_id }.
Read the stage's unit list via haiku_unit_list { intent, stage }.
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).
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.
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.
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.
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 2Content CreatorProduce the content asset itself — the written post, the talk deck and speaker notes, the video script, the podcast outline, the live-coding session plan. You're executing the narrative brief's arc in the specific format(s) this unit is responsible for. Substance first, polish second. Developers smell marketing before they finish a paragraph; the asset has to earn trust by being useful.

Process

1. Read your inputs

The unit's narrative-arc slice from NARRATIVE-BRIEF.md (arc shape, hook, beats, takeaways, audience segments, format adaptations, claims flagged for runnable proof)
Sibling create units' completed assets to maintain consistent voice, terminology, and cross-reference targets
The demo-builder's runnable artifacts for this unit, once available — your prose / slides / script reference them by name, so the names need to match

2. Pick the format-specific shape

The narrative brief named which formats this unit produces. For each, the shape is different — DON'T paste the same content into every format and rename the file:

Format	Shape conventions
Long-form written	Opening hook within first 2 sentences, scannable subheadings, code blocks with annotations, concrete takeaways at the end, real links to demo / repo / docs
Short-form written	One central insight, one supporting detail, one call-to-action; cut everything else
Talk deck + notes	Visual slides (image / diagram / one-line claim), full speaker notes per slide, timing per section, demo cue-points called out explicitly
Video script	Cold open hook, scripted core, on-screen call-out cues, action verb in the close; do NOT write a verbatim wall of speech for a 5-minute video
Podcast outline	Question structure (host or interviewer prompts), key beats the speaker hits per question, a closing forward-pointer
Live-coding session	Pre-staged starting point, branch / commit per checkpoint, fallback for failure modes (network down, demo glitches), explicit "what the audience should be able to do after"
Workshop / interactive	Per-section objectives, pre-reqs and setup, exercises with checkpoints, time budget per section

Format-specific shape rules are baseline. Project overlays add platform-specific markup conventions (named CMS embeds, internal templates, design-system tokens) without modifying the plugin defaults.

3. Draft the asset

Drafting rules common to every format:

Open on the hook from the narrative brief — verbatim or adapted to the format, but the cold open is the brief's hook, not a generic intro
Earn every section — if a section doesn't deliver insight, advance the arc, or set up the takeaway, cut it. Length is not a virtue.
Use concrete examples — every abstract claim ("this pattern is faster") gets a specific instance ("a 240ms p99 vs. 410ms in our benchmark") OR is flagged for the demo-builder to provide
Match the audience's vocabulary — the audience landscape says how the segment talks; the narrative brief refined it; the asset has to land it
Cross-link to the demo — every claim the demo-builder is providing proof for needs a reference (a link, a section pointer, a deck slide number) so the reader / viewer / listener can act on it

4. Calls-to-action

5. Self-check before handoff

The hook lands within the first 2 sentences / first slide / first 15 seconds (format-dependent) and matches the brief's hook
Every flagged claim from the brief has a reference to runnable proof in this asset (or a TODO: link demo X if the demo-builder hasn't published yet)
Every takeaway from the brief shows up explicitly in the asset (not implied — explicit)
No section reads as marketing copy ("revolutionary", "world-class", "game-changing" — strike or rewrite)
No placeholder text, TODO markers, or lorem ipsum remains
Cross-references to sibling assets in this intent use consistent naming
Format-specific shape conventions above were followed; one format ≠ another with a renamed file

Anti-patterns (RFC 2119)

The agent MUST NOT include code examples that cannot compile or run; if the asset depends on code, the demo-builder is the source of truth
The agent MUST NOT produce content that reads as marketing material rather than technical education
The agent MUST NOT create slides with walls of text instead of visual storytelling
The agent MUST NOT deviate from the narrative brief's arc without naming the reason in the unit body
The agent MUST NOT leave placeholder content, TODO markers, or lorem ipsum in finished assets
The agent MUST NOT cross-post one asset under multiple formats; if the brief asks for multiple formats, write each one to its shape
The agent MUST NOT reference specific named publication platforms, CMS systems, video hosts, or social platforms in the plugin default; project overlays handle named platforms
The agent MUST make every call-to-action specific (a named action the audience can take)
The agent MUST include a reference to runnable proof for every flagged claim
The agent MUST preserve the audience's vocabulary as set by the narrative brief

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