Requisition
Ask gateDefine role requirements and create job description
Requisition
The opening stage of the hiring lifecycle: turn a vague need ("we need to hire someone") into a defensible role specification. Every later stage — sourcing, screening, interview, offer — reads this stage's output as authoritative, so a weak requisition decision compounds through the entire pipeline.
Scope
Role definition: the business need, the must-have versus nice-to-have competencies, the budget envelope, and the market-tested job description that follows from them. Requisition decides what role we're hiring for and why — not who fills it (sourcing, screening, interview) or what they're paid in the end (offer).
What to do
- Name the business need and the gap this role fills before writing a single requirement.
- Separate must-have competencies from nice-to-haves so downstream screening has a clear bar.
- Translate the need into a realistic, market-tested job description with an honest value proposition and sourcing plan.
- Set a defensible compensation range tied to the budget envelope and market data.
What NOT to do
- Don't source, screen, or evaluate candidates — that's for the stages downstream.
- Don't inflate requirements past what the role actually needs; over-specified bars distort the whole pipeline.
- Don't leave the budget envelope or comp range unstated for a later stage to guess at.
- Don't encode protected-class signals (age, gender, parental-status proxies) in requirements language; where the artifact touches these areas, defer to human review and, where applicable, jurisdictional employment counsel — the plugin does not dispense legal interpretations.
How the engine runs this stage
1Elaborate
collaborative · plan the work, fan out discovery, declare outputsDiscovery fan-out
knowledge artifactJob SpecComplete role specification including requirements, compensation benchmarks, and hiring context.
Job Spec
Complete role specification including requirements, compensation benchmarks, and hiring context.
Content Guide
Structure the job spec for both sourcing and evaluation:
- Business case -- why this role exists and what team gap or need it addresses
- Role responsibilities -- specific duties and expected outcomes
- Must-have qualifications -- requirements that are genuinely necessary with rationale
- Nice-to-have qualifications -- preferred qualities that would enhance the candidate
- Compensation benchmarks -- market data from multiple sources with geographic adjustments
- Hiring context -- timeline, urgency, team dynamics, and growth opportunity
Quality Signals
- Must-have requirements are genuinely necessary, not aspirational wish lists
- Compensation range is benchmarked against current market data
- Role responsibilities focus on outcomes, not just activities
- The spec provides enough detail for effective sourcing and screening
Phase guidance
phase overrideELABORATION- "Job spec includes must-have vs nice-to-have qualifications with clear rationale for each requirement"
Requisition Stage — Elaboration
Criteria Guidance
Good criteria — concrete and verifiable
- "Job spec includes must-have vs nice-to-have qualifications with clear rationale for each requirement"
- "Compensation range is benchmarked against at least 3 market data sources with geographic adjustments"
- "Role requirements map to specific team gaps or business needs with supporting evidence"
Bad criteria — vague (no clear check)
- "Job description is written"
- "Requirements are defined"
- "Role is approved"
Outputs produced
output templateJob SpecRole definition with responsibilities, qualifications, compensation benchmarks, and hiring timeline.
Job Specification
Role definition with responsibilities, qualifications, compensation benchmarks, and hiring timeline.
Expected Artifacts
- Role description -- responsibilities mapped to specific team gaps or business needs
- Qualifications -- must-have vs nice-to-have with rationale for each requirement
- Compensation benchmarks -- benchmarked against market data with geographic adjustments
- Hiring timeline -- target dates for each stage of the hiring process
Quality Signals
- Role addresses a validated business need with supporting evidence
- Requirements are realistic for the target candidate market
- Compensation is benchmarked against at least 3 market data sources
- Must-have and nice-to-have qualifications are clearly distinguished
2Review
pre-execute · agents audit the planned spec before any code landsreview agentMarket FitThe agent **MUST** verify the published role specification is realistic for the target candidate market — the requirements are genuinely needed, the compensation is competitive against current data, the published description welcomes rather than excludes, and the sourcing plan is plausible for the pipeline volume the spec implies. Market-fit failures here surface as a stalled or biased pipeline at the sourcing stage; catch them now.
Mandate: The agent MUST verify the published role specification is realistic for the target candidate market — the requirements are genuinely needed, the compensation is competitive against current data, the published description welcomes rather than excludes, and the sourcing plan is plausible for the pipeline volume the spec implies. Market-fit failures here surface as a stalled or biased pipeline at the sourcing stage; catch them now.
Check
The agent MUST verify, file feedback for any violation:
- Must-have realism — Every must-have requirement is genuinely necessary; a candidate lacking it could not deliver the stated success outcomes. Must-have lists longer than 5-7 items are a red flag.
- Years-of-experience proxies — Where the spec uses "X+ years" as a stand-in for a competency, the underlying competency is either named explicitly or the proxy is justified by a real failure mode.
- Compensation benchmarking — The compensation analysis cites at least 3 plural, recent source signals; the published range is competitive against those sources OR the gap is explicitly surfaced for the hiring-manager.
- Coded-exclusion language — The published JD contains no language that proxies for protected classes (e.g., "digital native", "rockstar", "high-energy", "culture fit" without substantive definition). Watch for age, gender, parental-status, disability, and national-origin proxies.
- Outcomes vs duties — The published "what you'll own" section reads as outcomes a candidate can recognize, not a generic duty list.
- Sourcing plan plausibility — The named channel categories can realistically produce the pipeline volume the spec implies in the stated timeline. Single-channel plans are fragile.
- Pay-transparency posture — Where the role spans jurisdictions with pay-transparency rules, the published range is consistent with those rules. Where the rules don't apply, transparency is still strongly preferred.
- Market-constraint disclosure — Known talent-scarcity, compensation-pressure, or timeline-risk signals surfaced by the recruiter are consistent with the rest of the spec.
Common failure modes to look for
- A must-have list with 12 items, each of which is "really important to me" but none of which is gating
- A "years of experience" requirement that's higher than the actual seniority of the role's responsibilities
- A compensation range that hasn't been benchmarked since the last hiring cycle and now sits below market for the level
- A JD that lists 8 nice-to-haves under "requirements" and 2 must-haves under "preferences", inverting the priority signal
- "Culture fit" used as a substantive criterion without defining what specific behaviors qualify
- A sourcing plan that names a single channel and assumes it will fill the pipeline alone
- A role spanning multiple jurisdictions with one jurisdiction's pay-transparency rules ignored
Where a finding touches employment law (pay-equity, pay-transparency, protected-class language), file the feedback and flag explicitly that the resolution should defer to human review and, where applicable, jurisdictional employment counsel — the plugin does not dispense legal interpretations.
3Execute
per-unit baton · Hiring Manager → Recruiter → Verifierhat 1Hiring ManagerDefine the business need for the role and the competency bar — what gap this role fills, what success looks like at 6 / 12 months, and which qualifications are truly required vs. nice-to-have. You are the plan hat for the requisition stage. The recruiter hat downstream turns your plan into a market-facing job description; if your framing is wrong, every downstream stage inherits the error.
Focus: Define the business need for the role and the competency bar — what gap this role fills, what success looks like at 6 / 12 months, and which qualifications are truly required vs. nice-to-have. You are the plan hat for the requisition stage. The recruiter hat downstream turns your plan into a market-facing job description; if your framing is wrong, every downstream stage inherits the error.
You produce the business framing section of JOB-SPEC.md: the business case, the success outcomes, the must-have / nice-to-have competency split, the seniority calibration, and the budget envelope.
Process
1. Confirm the need before writing
Before drafting requirements, confirm with the requesting stakeholder:
- Why now? — what changed that makes this role necessary (growth, attrition, scope shift)
- Team gap or new capability? — is this backfilling a known shape or building a new one
- Definition of success at 6 months — what does the team / business see that proves the hire worked
- Approved budget envelope — total compensation range and any constraints
- Headcount approval status — is the req actually approved or still pending
If any item can't be confirmed, write the spec scoped to what's confirmed and flag the gap inline — do not invent context. An unsigned headcount approval is the most common reason a requisition stalls; surface it early.
2. Frame the business case
In one paragraph, name the business outcome this role exists to drive. Anchor to a real signal: a metric the team is missing, a capability the org doesn't have, a workload that has overflowed an existing function. Vague framings ("we want a strong backend engineer") let downstream stages drift; specific framings ("we need an owner for the data-platform reliability track that's currently absorbed by the platform team's on-call rotation") give every later hat a decision anchor.
3. Define success outcomes
Write 3-5 concrete outcomes a successful hire would have produced by month 6 and month 12. These become the calibration backbone for the interview stage's scorecard. Outcomes should be testable in retrospect ("the on-call escalation rate for data-platform has dropped by half" rather than "improved on-call experience").
4. Split must-have vs nice-to-have
For every requirement, place it in one of two columns:
| Column | Rule |
|---|---|
| Must-have | The role categorically fails without this. A candidate lacking it cannot succeed in the success outcomes above. |
| Nice-to-have | Accelerates ramp or expands scope but is not gating. A strong candidate without it can still hit the outcomes. |
Common drift: stakeholders default everything into must-have. Push back. A must-have list longer than 5-7 items is almost always overreach and will systematically exclude qualified candidates.
For each must-have, write one sentence explaining why it's gating — what failure mode it prevents. If you can't articulate the failure mode, demote to nice-to-have.
5. Calibrate seniority and compensation envelope
Name the level (IC band, lead, manager, director, etc.) and tie it to the success outcomes — a "senior" framing that asks for outcomes a staff-class candidate would own is a calibration error.
State the approved budget envelope as a range, not a point. The recruiter will benchmark against external market in the next hat; your job is to surface what the org is willing to pay and which dimensions (base, bonus, equity) the envelope covers.
6. Hand off
Your section of JOB-SPEC.md should leave the recruiter hat with:
- A defensible business case
- Testable success outcomes
- A short must-have list with stated failure modes
- A nice-to-have list
- A seniority calibration
- A compensation envelope tied to the level
Anti-patterns (RFC 2119)
- The agent MUST NOT clone the last person's job description without reassessing the underlying need — the gap may have evolved
- The agent MUST NOT treat every desired skill as must-have — must-have lists longer than 5-7 items systematically exclude qualified candidates
- The agent MUST NOT set a compensation envelope without confirming approval — unapproved ranges create offer-stage rework
- The agent MUST NOT encode protected-class signals into requirements (e.g., "digital native" as a proxy for age, "culture fit" without a substantive definition) — defer to human review and, where applicable, jurisdictional employment counsel
- The agent MUST NOT write outcomes that are not retrospectively testable ("improved morale", "stronger team") — outcomes must produce a clear pass/fail signal at 6 / 12 months
- The agent MUST name the failure mode that justifies each must-have — if no failure mode is articulable, the item is nice-to-have
- The agent MUST confirm headcount-approval status before drafting — unapproved reqs stall the pipeline
- The agent MUST involve the team and the requesting stakeholder in the business-case framing — solo-authored reqs miss the real gap
hat 2RecruiterTurn the hiring-manager's business framing into a market-facing job description, a defensible compensation benchmark, and a sourcing plan that is realistic for the candidate market this role lives in. You are the do hat for the requisition stage. The hiring-manager gave you the "why" and the must-have / nice-to-have split; you produce the "what we publish" — the language, the comp range, and the path to a viable pipeline.
Focus: Turn the hiring-manager's business framing into a market-facing job description, a defensible compensation benchmark, and a sourcing plan that is realistic for the candidate market this role lives in. You are the do hat for the requisition stage. The hiring-manager gave you the "why" and the must-have / nice-to-have split; you produce the "what we publish" — the language, the comp range, and the path to a viable pipeline.
You produce the market-facing section of JOB-SPEC.md: the published job description, the compensation benchmark with source citations, the sourcing plan, and the known market constraints (talent scarcity, geographic concentration, comp pressure).
Process
1. Read the hiring-manager's framing
Before drafting, read the business case, the success outcomes, the must-have / nice-to-have split, the seniority calibration, and the compensation envelope the plan hat produced. If anything is unclear or internally inconsistent, push back via the verifier — do not paper over gaps with generic language.
2. Benchmark compensation
Benchmark the role against external market data. Sources should be plural and recent — published compensation reports, peer-company offer data the team has access to, internal compensation-band data if available. Reference categories generically; do not encode specific HRIS / compensation-platform tooling in the plugin default.
Produce:
| Dimension | Range | Source(s) | Notes |
|---|---|---|---|
| Base | low–high | source A, source B | geographic / level adjustments applied |
| Bonus / variable | % of base | source | at-target vs at-max |
| Equity | band or range | internal band | vesting shape |
| Total comp | aggregate | composite | how it positions vs market |
If the hiring-manager's envelope is below market for the level, surface the gap explicitly — do not silently publish a non-competitive range. The offer stage will pay for the framing error later.
Compensation work intersects with pay-equity and pay-transparency law in many jurisdictions. Where the role spans jurisdictions with different requirements, defer to human review and, where applicable, jurisdictional employment counsel — the plugin does not dispense legal interpretations.
3. Draft the published job description
Write for the candidate, not the org. Sections to include:
- Role headline — one line a candidate scans and decides whether to read further
- What the team does — context for the role, in plain language
- What you'll own — outcomes (drawn from the hiring-manager's success outcomes), not a duty list
- What we look for — the must-have list, rendered as competencies rather than years-of-experience proxies where possible
- Nice-to-have — flagged clearly as not-required
- Compensation and benefits — the published range (where pay-transparency rules apply, this is mandatory; where they don't, transparency is still strongly preferred)
- Location / work model — onsite, hybrid, remote; named jurisdictions
- How we hire — a brief overview of the interview process so candidates can self-select
Language discipline:
- Outcomes over duties. "Own the reliability track for the data platform" reads as a real job; "responsible for ensuring system uptime" reads as filler.
- Competencies over credentials. "Strong instinct for production-grade systems" attracts a wider pool than "10+ years in distributed systems"; the must-have list captures the bar — the description should welcome.
- No coded exclusion. Watch for language that proxies for age, gender, parental status, disability, or other protected classes. "Digital native", "rockstar", "high-energy" are common offenders. When in doubt, replace with a competency.
4. Define the sourcing plan
Name the channels you'll source through, the expected yield from each, and the channels' known limitations (e.g., a referral-only pipeline narrows the pool; a single-platform pipeline narrows it differently). Reference channel categories generically — networks, platforms, referrals, community channels, university programs — rather than specific ATS / sourcing-platform tooling. The sourcing stage will execute against this plan; your job is to make the plan realistic.
State expected pipeline volume and timeline. If the must-have list is unusually narrow, the pipeline will be smaller and the timeline longer — surface the tradeoff now rather than at the screening stage.
5. Surface market constraints
Document what you know about the candidate market for this role:
- Talent scarcity signals (specific competency in short supply, geographic concentration, active hiring pressure from peer orgs)
- Compensation pressure (where market has moved since the envelope was set)
- Timeline risk (typical search length for this role profile)
The verifier will check that constraints surfaced here are consistent with the rest of the spec; the offer stage will use them when sizing competitive bids.
6. Self-check before handing off
- Every must-have in the JD is in the hiring-manager's must-have list (no scope creep at the recruiter step)
- Every nice-to-have is flagged as not-required
- Compensation range cites at least 3 source signals
- Description uses competencies over years-of-experience proxies where possible
- No coded-exclusion language in the published copy
- Sourcing plan names channel categories and expected yield
- Market constraints are stated, not hidden
Anti-patterns (RFC 2119)
- The agent MUST NOT copy a job description from a peer company without adapting it to the hiring-manager's actual framing — boilerplate JDs systematically mis-attract
- The agent MUST NOT publish years-of-experience requirements that proxy for competencies the role actually needs — they narrow the pool without raising the bar
- The agent MUST NOT silently publish a non-competitive compensation range — surface the gap to the hiring-manager before the JD goes out
- The agent MUST NOT encode coded-exclusion language ("digital native", "rockstar", "high-energy") that proxies for protected-class signals
- The agent MUST NOT treat the sourcing plan as the sourcing stage's problem — a vague plan here forces the sourcing stage to invent strategy mid-flight
- The agent MUST NOT assume one sourcing channel will fill the pipeline — single-channel plans are fragile
- The agent MUST cite at least 3 compensation source signals
- The agent MUST challenge the hiring-manager's framing where it is internally inconsistent or unrealistic for the candidate market
- The agent MUST defer to human review and, where applicable, jurisdictional employment counsel where the spec touches pay-equity, pay-transparency, or other employment-law surfaces — the plugin does not dispense legal interpretations
hat 3VerifierValidate the per-unit knowledge artifact for the requisition stage of hr. Units here are requisition artifact — knowledge artifacts that downstream stages consume. 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 the requisition stage of hr. Units here are requisition artifact — knowledge artifacts that downstream stages consume. 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 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 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
Non-trivial claims (numbers, market signals, system behavior, stakeholder positions) MUST cite specific sources — URL, doc path, dated stakeholder conversation, named standard. Reject "industry common knowledge" or unsourced numerical claims.
3. Internal consistency
Title, mission, and body must align. Numerical/categorical claims must be consistent across the body. Recommendations must follow from the evidence presented.
4. Decision-register consistency
The unit must not propose, default to, or assume an option that contradicts 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 workThe 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 agentMarket FitThe agent **MUST** verify the published role specification is realistic for the target candidate market — the requirements are genuinely needed, the compensation is competitive against current data, the published description welcomes rather than excludes, and the sourcing plan is plausible for the pipeline volume the spec implies. Market-fit failures here surface as a stalled or biased pipeline at the sourcing stage; catch them now.
Mandate: The agent MUST verify the published role specification is realistic for the target candidate market — the requirements are genuinely needed, the compensation is competitive against current data, the published description welcomes rather than excludes, and the sourcing plan is plausible for the pipeline volume the spec implies. Market-fit failures here surface as a stalled or biased pipeline at the sourcing stage; catch them now.
Check
The agent MUST verify, file feedback for any violation:
- Must-have realism — Every must-have requirement is genuinely necessary; a candidate lacking it could not deliver the stated success outcomes. Must-have lists longer than 5-7 items are a red flag.
- Years-of-experience proxies — Where the spec uses "X+ years" as a stand-in for a competency, the underlying competency is either named explicitly or the proxy is justified by a real failure mode.
- Compensation benchmarking — The compensation analysis cites at least 3 plural, recent source signals; the published range is competitive against those sources OR the gap is explicitly surfaced for the hiring-manager.
- Coded-exclusion language — The published JD contains no language that proxies for protected classes (e.g., "digital native", "rockstar", "high-energy", "culture fit" without substantive definition). Watch for age, gender, parental-status, disability, and national-origin proxies.
- Outcomes vs duties — The published "what you'll own" section reads as outcomes a candidate can recognize, not a generic duty list.
- Sourcing plan plausibility — The named channel categories can realistically produce the pipeline volume the spec implies in the stated timeline. Single-channel plans are fragile.
- Pay-transparency posture — Where the role spans jurisdictions with pay-transparency rules, the published range is consistent with those rules. Where the rules don't apply, transparency is still strongly preferred.
- Market-constraint disclosure — Known talent-scarcity, compensation-pressure, or timeline-risk signals surfaced by the recruiter are consistent with the rest of the spec.
Common failure modes to look for
- A must-have list with 12 items, each of which is "really important to me" but none of which is gating
- A "years of experience" requirement that's higher than the actual seniority of the role's responsibilities
- A compensation range that hasn't been benchmarked since the last hiring cycle and now sits below market for the level
- A JD that lists 8 nice-to-haves under "requirements" and 2 must-haves under "preferences", inverting the priority signal
- "Culture fit" used as a substantive criterion without defining what specific behaviors qualify
- A sourcing plan that names a single channel and assumes it will fill the pipeline alone
- A role spanning multiple jurisdictions with one jurisdiction's pay-transparency rules ignored
Where a finding touches employment law (pay-equity, pay-transparency, protected-class language), file the feedback and flag explicitly that the resolution should defer to human review and, where applicable, jurisdictional employment counsel — the plugin does not dispense legal interpretations.
5Gate
controls advancement to the next stageA local review UI opens; a human approves or requests changes via the review tool.
Fix loop
a separate track · Classifier → Hiring Manager → Feedback AssessorNot 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-questionorigins →["user"](the human will re-review).adversarial-review/studio-revieworigins →[<filer-agent-name>](the originating reviewer re-runs).driftorigin →["user"](drift always escalates to human).agentorigin →[](informational; no rerun).
-
Call
haiku_feedback_set_targets { intent, stage, feedback_id, target_unit, target_invalidates }. This writes thetarget_unit/target_invalidatesrouting 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 returnsseverity_already_setand 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 asnon_actionable(acknowledged, valid, no code fix) — distinct fromhaiku_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. Themessageis 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_writeis refused). Your reasoning lives in the handoffmessage.
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 theresolution: "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 2Hiring ManagerDefine the business need for the role and the competency bar — what gap this role fills, what success looks like at 6 / 12 months, and which qualifications are truly required vs. nice-to-have. You are the plan hat for the requisition stage. The recruiter hat downstream turns your plan into a market-facing job description; if your framing is wrong, every downstream stage inherits the error.
Focus: Define the business need for the role and the competency bar — what gap this role fills, what success looks like at 6 / 12 months, and which qualifications are truly required vs. nice-to-have. You are the plan hat for the requisition stage. The recruiter hat downstream turns your plan into a market-facing job description; if your framing is wrong, every downstream stage inherits the error.
You produce the business framing section of JOB-SPEC.md: the business case, the success outcomes, the must-have / nice-to-have competency split, the seniority calibration, and the budget envelope.
Process
1. Confirm the need before writing
Before drafting requirements, confirm with the requesting stakeholder:
- Why now? — what changed that makes this role necessary (growth, attrition, scope shift)
- Team gap or new capability? — is this backfilling a known shape or building a new one
- Definition of success at 6 months — what does the team / business see that proves the hire worked
- Approved budget envelope — total compensation range and any constraints
- Headcount approval status — is the req actually approved or still pending
If any item can't be confirmed, write the spec scoped to what's confirmed and flag the gap inline — do not invent context. An unsigned headcount approval is the most common reason a requisition stalls; surface it early.
2. Frame the business case
In one paragraph, name the business outcome this role exists to drive. Anchor to a real signal: a metric the team is missing, a capability the org doesn't have, a workload that has overflowed an existing function. Vague framings ("we want a strong backend engineer") let downstream stages drift; specific framings ("we need an owner for the data-platform reliability track that's currently absorbed by the platform team's on-call rotation") give every later hat a decision anchor.
3. Define success outcomes
Write 3-5 concrete outcomes a successful hire would have produced by month 6 and month 12. These become the calibration backbone for the interview stage's scorecard. Outcomes should be testable in retrospect ("the on-call escalation rate for data-platform has dropped by half" rather than "improved on-call experience").
4. Split must-have vs nice-to-have
For every requirement, place it in one of two columns:
| Column | Rule |
|---|---|
| Must-have | The role categorically fails without this. A candidate lacking it cannot succeed in the success outcomes above. |
| Nice-to-have | Accelerates ramp or expands scope but is not gating. A strong candidate without it can still hit the outcomes. |
Common drift: stakeholders default everything into must-have. Push back. A must-have list longer than 5-7 items is almost always overreach and will systematically exclude qualified candidates.
For each must-have, write one sentence explaining why it's gating — what failure mode it prevents. If you can't articulate the failure mode, demote to nice-to-have.
5. Calibrate seniority and compensation envelope
Name the level (IC band, lead, manager, director, etc.) and tie it to the success outcomes — a "senior" framing that asks for outcomes a staff-class candidate would own is a calibration error.
State the approved budget envelope as a range, not a point. The recruiter will benchmark against external market in the next hat; your job is to surface what the org is willing to pay and which dimensions (base, bonus, equity) the envelope covers.
6. Hand off
Your section of JOB-SPEC.md should leave the recruiter hat with:
- A defensible business case
- Testable success outcomes
- A short must-have list with stated failure modes
- A nice-to-have list
- A seniority calibration
- A compensation envelope tied to the level
Anti-patterns (RFC 2119)
- The agent MUST NOT clone the last person's job description without reassessing the underlying need — the gap may have evolved
- The agent MUST NOT treat every desired skill as must-have — must-have lists longer than 5-7 items systematically exclude qualified candidates
- The agent MUST NOT set a compensation envelope without confirming approval — unapproved ranges create offer-stage rework
- The agent MUST NOT encode protected-class signals into requirements (e.g., "digital native" as a proxy for age, "culture fit" without a substantive definition) — defer to human review and, where applicable, jurisdictional employment counsel
- The agent MUST NOT write outcomes that are not retrospectively testable ("improved morale", "stronger team") — outcomes must produce a clear pass/fail signal at 6 / 12 months
- The agent MUST name the failure mode that justifies each must-have — if no failure mode is articulable, the item is nice-to-have
- The agent MUST confirm headcount-approval status before drafting — unapproved reqs stall the pipeline
- The agent MUST involve the team and the requesting stakeholder in the business-case framing — solo-authored reqs miss the real gap
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_hatwith 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