haiku-method 2.2.0

package/studios/documentation/review-agents/cross-stage-consistency.md

@@ -0,0 +1,17 @@
+---
+scope: intent
+interpretation: lens
+---
+**Mandate:** Verify the intent's artifacts are internally consistent across stages. You are the only reviewer that sees the whole intent at once — your job is to catch seams that per-stage reviewers miss.
+
+**Check:**
+- The agent **MUST** verify that each stage's outputs align with what upstream stages specified — no dropped requirements, no silent scope expansion
+- The agent **MUST** verify that naming is consistent across stages — a concept named one thing upstream should carry the same name downstream
+- The agent **MUST** verify that stages' declared outputs exist at the paths their unit frontmatter promised
+- The agent **MUST** verify that the stages collectively deliver the intent's stated goal (read `intent.md`) — partial delivery is a finding
+- The agent **MUST** verify that concerns raised by any stage's review were actually addressed (not silently ignored)
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** re-litigate decisions already approved at each stage's gate
+- The agent **MUST NOT** propose new features or scope additions
+- The agent **MUST NOT** flag stylistic preferences — concrete divergence only

package/studios/documentation/stages/audit/STAGE.md

@@ -0,0 +1,13 @@
+---
+name: audit
+description: Assess existing documentation, identify gaps, and prioritize what to write or update
+hats: [auditor, gap-analyst, verifier]
+fix_hats: [auditor, feedback-assessor]
+review: auto
+elaboration: autonomous
+inputs: []
+---
+
+# Audit
+
+Assess existing documentation, identify gaps, and prioritize what to write or update.

package/studios/documentation/stages/audit/hats/auditor.md

@@ -0,0 +1,7 @@
+**Focus:** Inventory existing documentation, assess its currency and accuracy, and catalog what exists. Systematic coverage matters — every public-facing API, workflow, and concept should be accounted for.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** skip areas because they "probably haven't changed"
+- The agent **MUST NOT** assess documentation without checking it against the actual system
+- The agent **MUST NOT** inventory only what's easy to find while missing scattered or informal docs
+- The agent **MUST NOT** treat all documentation equally regardless of user impact

package/studios/documentation/stages/audit/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**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.
+
+**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** 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

package/studios/documentation/stages/audit/hats/gap-analyst.md

@@ -0,0 +1,8 @@
+**Focus:** Analyze the auditor's inventory to identify documentation gaps, prioritize them by user impact, and produce a ranked backlog of documentation work. Connect gaps to real user pain — support tickets, onboarding friction, common mistakes.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** list gaps without prioritizing them
+- The agent **MUST NOT** prioritize by internal convenience rather than user impact
+- The agent **MUST NOT** recommend documentation types without considering the audience's context
+- The agent **MUST NOT** treat all missing docs as equally urgent
+- The agent **MUST NOT** ignore outdated documentation as "good enough"

package/studios/documentation/stages/audit/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit knowledge artifact for the audit stage of documentation. Units here are doc-gap finding — 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.
+
+## 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)`.

package/studios/documentation/stages/audit/outputs/AUDIT-REPORT.md

@@ -0,0 +1,25 @@
+---
+name: audit-report
+location: .haiku/intents/{intent-slug}/stages/audit/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Audit Report
+
+Documentation inventory with coverage status, gap analysis, and prioritized backlog.
+
+## Expected Artifacts
+
+- **Documentation inventory** -- coverage status (documented, outdated, missing) for each area
+- **Gap analysis** -- missing, outdated, and incomplete documentation with severity ratings
+- **Priority ranking** -- documentation needs ranked by user impact and effort
+- **Backlog** -- ordered list of documentation work to be done
+
+## Quality Signals
+
+- Inventory covers all public-facing areas with explicit status for each
+- Gaps are prioritized by user impact and frequency of support requests
+- Each gap includes a severity rating and recommended documentation type
+- Backlog is actionable with clear scope for each item

package/studios/documentation/stages/audit/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Audit Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Inventory covers all public APIs with status (documented/outdated/missing) for each"
+- "Gap analysis prioritizes documentation needs by user impact and frequency of support requests"
+- "Each identified gap includes a severity rating and recommended documentation type"
+
+### Bad criteria — vague (no clear check)
+
+- "Audit is complete"
+- "Gaps are identified"
+- "Documentation is reviewed"
+

package/studios/documentation/stages/audit/review-agents/coverage.md

@@ -0,0 +1,9 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the audit identified all documentation gaps and priorities are correctly ranked.
+
+**Check:**
+- The agent **MUST** verify that all user-facing features, APIs, and workflows have been inventoried
+- The agent **MUST** verify that gap severity reflects actual user impact, not just completeness for its own sake
+- The agent **MUST** verify that existing documentation that is outdated or misleading is flagged, not just missing docs

package/studios/documentation/stages/draft/STAGE.md

@@ -0,0 +1,15 @@
+---
+name: draft
+description: Write the documentation content following the approved outline
+hats: [writer, technical-reviewer]
+fix_hats: [writer, feedback-assessor]
+review: ask
+elaboration: autonomous
+inputs:
+  - stage: outline
+    discovery: document-outline
+---
+
+# Draft
+
+Write the documentation content following the approved outline.

package/studios/documentation/stages/draft/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**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.
+
+**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** 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

package/studios/documentation/stages/draft/hats/technical-reviewer.md

@@ -0,0 +1,11 @@
+---
+interpretation: lens
+---
+**Focus:** Verify the technical accuracy of the writer's draft. Test code examples, validate API signatures, confirm configuration values, and check procedures against the running system. Every claim should be traceable to the source of truth.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** skim documentation without actually testing the examples
+- The agent **MUST NOT** assume API signatures are correct because they look plausible
+- The agent **MUST NOT** only check happy-path procedures while ignoring error cases
+- The agent **MUST** flag version-specific behavior that may break on upgrade
+- The agent **MUST NOT** approve documentation that describes intended behavior rather than actual behavior

package/studios/documentation/stages/draft/hats/writer.md

@@ -0,0 +1,9 @@
+**Focus:** Write clear, accurate documentation following the approved outline. Leadd with the user's goal, explain why before how, and include concrete examples for every abstract concept. Code samples must be runnable, not pseudocode.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** write documentation from memory instead of verifying against the actual system
+- The agent **MUST NOT** use jargon without defining it or linking to a glossary
+- The agent **MUST NOT** include code examples that are untested or syntactically invalid
+- The agent **MUST NOT** write procedures without prerequisites or expected outcomes
+- The agent **MUST NOT** leave placeholder sections ("TODO: add example here")
+- The agent **MUST NOT** explain what the system does without explaining why the user would care

package/studios/documentation/stages/draft/outputs/DRAFT-CONTENT.md

@@ -0,0 +1,25 @@
+---
+name: draft-content
+location: .haiku/intents/{intent-slug}/stages/draft/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Draft Content
+
+Content-complete documentation draft with all sections populated.
+
+## Expected Artifacts
+
+- **Documentation draft** -- all sections populated following the approved outline
+- **Code examples** -- syntactically valid and tested against the current version
+- **Procedures** -- numbered steps with prerequisites and expected outcomes
+- **Conceptual sections** -- explanations that answer "why" before explaining "how"
+
+## Quality Signals
+
+- All sections from the outline are populated
+- Code examples are accurate and runnable
+- Procedures include prerequisites, steps, and expected outcomes
+- Technical accuracy has been verified against the actual system

package/studios/documentation/stages/draft/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Draft Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Every code example is syntactically valid and tested against the current version"
+- "Each procedure includes prerequisites, numbered steps, and expected outcomes"
+- "Conceptual sections answer 'why' before explaining 'how'"
+
+### Bad criteria — vague (no clear check)
+
+- "Documentation is written"
+- "Content is complete"
+- "Examples are included"
+

package/studios/documentation/stages/draft/review-agents/accuracy.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify all technical content is factually correct against the current codebase.
+
+**Check:**
+- The agent **MUST** verify that code examples compile/run against the current version
+- The agent **MUST** verify that aPI signatures, parameters, and return types match the implementation
+- The agent **MUST** verify that configuration options exist and behave as described
+- The agent **MUST** verify that version-specific information is clearly labeled

package/studios/documentation/stages/draft/review-agents/clarity.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the documentation is understandable by its target audience.
+
+**Check:**
+- The agent **MUST** verify that jargon is defined on first use or in a glossary
+- The agent **MUST** verify that procedures have numbered steps that can be followed without guessing
+- The agent **MUST** verify that concepts are introduced before they are referenced
+- The agent **MUST** verify that examples illustrate the common case, not just the trivial or exotic case

package/studios/documentation/stages/outline/STAGE.md

@@ -0,0 +1,15 @@
+---
+name: outline
+description: Structure the documentation with clear information architecture
+hats: [architect, outline-reviewer]
+fix_hats: [architect, feedback-assessor]
+review: ask
+elaboration: collaborative
+inputs:
+  - stage: audit
+    discovery: audit-report
+---
+
+# Outline
+
+Structure the documentation with clear information architecture.

package/studios/documentation/stages/outline/hats/architect.md

@@ -0,0 +1,8 @@
+**Focus:** Design the information architecture — how content is organized, navigated, and discovered. Structure documentation around user tasks and workflows, not around system internals. Apply progressive disclosure so readers find what they need at the right level of detail.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** organize documentation by system component instead of user task
+- The agent **MUST NOT** create deeply nested hierarchies that are hard to navigate
+- The agent **MUST NOT** design structure without considering how readers will arrive at each page
+- The agent **MUST NOT** omit a clear entry point or getting-started path
+- The agent **MUST NOT** treat the outline as a table of contents instead of an information architecture

package/studios/documentation/stages/outline/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**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.
+
+**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** 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

package/studios/documentation/stages/outline/hats/outline-reviewer.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Focus:** Validate the architect's outline from the reader's perspective. Walk through common user journeys and verify the structure supports them. Check for orphaned sections, circular references, and gaps in the learning path.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** approve an outline without mentally walking through user journeys
+- The agent **MUST NOT** focus on section naming while ignoring structural problems
+- The agent **MUST** verify that the outline addresses all prioritized gaps from the audit
+- The agent **MUST NOT** treat the outline as final without considering how it will evolve

package/studios/documentation/stages/outline/outputs/DOCUMENT-OUTLINE.md

@@ -0,0 +1,25 @@
+---
+name: document-outline
+location: .haiku/intents/{intent-slug}/stages/outline/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Document Outline
+
+Information architecture with logical section hierarchy and purpose statements.
+
+## Expected Artifacts
+
+- **Section hierarchy** -- organized structure with no more than 3 levels of nesting
+- **Purpose statements** -- one-sentence description of what the reader will learn per section
+- **Audience mapping** -- target audience identified for each section
+- **Navigation design** -- task-oriented structure with progressive disclosure
+
+## Quality Signals
+
+- Structure serves the reader's workflow, not the system's architecture
+- Each section has a defined purpose and audience
+- Information architecture groups content by user task
+- No orphaned sections or dead-end navigation paths

package/studios/documentation/stages/outline/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Outline Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Outline defines a clear hierarchy with no more than 3 levels of nesting"
+- "Each section has a one-sentence purpose statement explaining what the reader will learn"
+- "Information architecture groups content by user task, not by system component"
+
+### Bad criteria — vague (no clear check)
+
+- "Outline is structured"
+- "Sections are organized"
+- "Architecture is clear"
+

package/studios/documentation/stages/outline/review-agents/structure.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the information architecture supports how users actually look for information.
+
+**Check:**
+- The agent **MUST** verify that organization follows user tasks, not internal code structure
+- The agent **MUST** verify that heading hierarchy is logical and consistent
+- The agent **MUST** verify that no section is so large it should be split, or so small it should be merged
+- The agent **MUST** verify that cross-references between related topics are identified

package/studios/documentation/stages/publish/STAGE.md

@@ -0,0 +1,20 @@
+---
+name: publish
+description: Format, validate links, and publish the documentation
+hats: [publisher, verifier]
+fix_hats: [publisher, feedback-assessor]
+review: auto
+elaboration: autonomous
+inputs:
+  - stage: draft
+    discovery: draft-documentation
+  - stage: review
+    discovery: review-report
+review-agents-include:
+  - stage: draft
+    agents: [accuracy]
+---
+
+# Publish
+
+Format, validate links, and publish the documentation.

package/studios/documentation/stages/publish/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**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.
+
+**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** 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

package/studios/documentation/stages/publish/hats/publisher.md

@@ -0,0 +1,8 @@
+**Focus:** Incorporate review findings, finalize formatting for the target platform, validate all links, and ensure metadata is complete. The publisher bridges "reviewed draft" to "live documentation" — addressing findings, confirming rendering, and verifying that the documentation is discoverable.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** ignore critical or major review findings
+- The agent **MUST NOT** publish without validating that links resolve correctly
+- The agent **MUST** test rendering on the target platform (markdown quirks, broken tables, image paths)
+- The agent **MUST NOT** add new content during the publish stage instead of sending it back for review
+- The agent **MUST NOT** skip metadata (title, description, last-updated) that enables discoverability

package/studios/documentation/stages/publish/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit operational artifact for the publish stage of documentation. Units here are publish action — operational steps with concrete preconditions, actions, and post-condition checks. Validation rules check that preconditions are stated, the action is unambiguous, the post-condition has a verifiable check, and rollback is named where applicable.
+
+**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.
+
+## What you check (BODY ONLY)
+
+### 1. Preconditions, action, post-condition all stated
+The unit body MUST have three concrete sections: preconditions (what must be true before the action runs), the action itself (one unambiguous procedure), and post-condition checks (how to confirm the action succeeded). Reject if any of the three is missing or vague.
+
+### 2. Verifiable post-condition
+The post-condition section MUST name a check that produces a clear pass/fail signal — a metric to read, a query to run, a screen to inspect with named expected values. "Verify by eye that things look good" is a reject.
+
+### 3. Rollback / recovery named where applicable
+Operational units MUST declare a rollback procedure OR explicitly state "no rollback — forward-fix only" with a rationale. Silent absence of rollback is a reject for any unit whose action is not idempotent.
+
+### 4. Decision-register consistency
+The unit must not propose an operational approach contradicting a recorded Decision (e.g., blue-green deploy when Decision N chose canary). Cite the Decision ID.
+
+### 5. Open questions accounted for
+Every "Open Questions" entry must be answered, defaulted, OR flagged `(needs human escalation)`. Operational open questions left to runtime are how outages happen.

package/studios/documentation/stages/publish/outputs/PUBLISHED-DOCS.md

@@ -0,0 +1,25 @@
+---
+name: published-docs
+location: (project source tree)
+scope: repo
+format: text
+required: true
+---
+
+# Published Documentation
+
+Final documentation deployed to the target platform with all links validated.
+
+## Expected Artifacts
+
+- **Final documentation** -- all review findings addressed in the published version
+- **Link validation** -- all internal and external links resolve to valid targets
+- **Platform verification** -- documentation renders correctly in the target platform
+- **Publication record** -- where documentation is published and how to access it
+
+## Quality Signals
+
+- All critical and major review findings are addressed
+- All links resolve to valid targets
+- Documentation renders correctly on the target platform
+- Publication location is documented and accessible

package/studios/documentation/stages/publish/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Publish Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "All internal and external links resolve to valid targets"
+- "All critical and major review findings are addressed in the final version"
+- "Documentation renders correctly in the target platform (site, wiki, PDF)"
+
+### Bad criteria — vague (no clear check)
+
+- "Documentation is published"
+- "Links work"
+- "Formatting is done"
+

package/studios/documentation/stages/publish/review-agents/formatting.md

@@ -0,0 +1,10 @@
+---
+interpretation: lens
+---
+**Mandate:** The agent **MUST** verify the published documentation renders correctly and is navigable.
+
+**Check:**
+- The agent **MUST** verify that all links resolve (no 404s, no broken anchors)
+- The agent **MUST** verify that images and diagrams render at appropriate sizes
+- The agent **MUST** verify that code blocks have correct syntax highlighting
+- The agent **MUST** verify that table of contents and navigation reflect the actual content structure

package/studios/documentation/stages/review/STAGE.md

@@ -0,0 +1,15 @@
+---
+name: review
+description: Review documentation for accuracy, clarity, and completeness
+hats: [editor, subject-matter-expert, verifier]
+fix_hats: [editor, feedback-assessor]
+review: ask
+elaboration: collaborative
+inputs:
+  - stage: draft
+    discovery: draft-documentation
+---
+
+# Review
+
+Review documentation for accuracy, clarity, and completeness.

package/studios/documentation/stages/review/hats/editor.md

@@ -0,0 +1,8 @@
+**Focus:** Review documentation for clarity, consistency, and readability. Ensure terminology is consistent with the project glossary. Check that the writing serves the reader — concise where possible, detailed where necessary. Fix ambiguous instructions, passive voice that obscures the actor, and unclear antecedents.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** rewrite the author's voice instead of clarifying their intent
+- The agent **MUST NOT** prioritize grammatical perfection over technical accuracy
+- The agent **MUST NOT** ignore inconsistent terminology because each instance is individually clear
+- The agent **MUST NOT** make style changes that alter technical meaning
+- The agent **MUST** check that headings, labels, and cross-references match

package/studios/documentation/stages/review/hats/feedback-assessor.md

@@ -0,0 +1,11 @@
+---
+agent_type: general-purpose
+model: haiku
+---
+**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.
+
+**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** 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

package/studios/documentation/stages/review/hats/subject-matter-expert.md

@@ -0,0 +1,8 @@
+**Focus:** Validate that the documentation accurately represents the system's behavior, design intent, and operational reality. Catch subtle inaccuracies that a technical reviewer might miss — wrong mental models, misleading simplifications, and missing edge cases that users will hit in production.
+
+**Anti-patterns (RFC 2119):**
+- The agent **MUST NOT** rubber-stamp documentation because the surface-level facts are correct
+- The agent **MUST** flag misleading simplifications that will confuse advanced users
+- The agent **MUST NOT** ignore missing edge cases or failure modes
+- The agent **MUST NOT** assume the reader has the same context as the author
+- The agent **MUST NOT** validate against design intent rather than actual behavior

package/studios/documentation/stages/review/hats/verifier.md

@@ -0,0 +1,26 @@
+**Focus:** Validate the per-unit operational artifact for the review stage of documentation. Units here are doc-review pass — operational steps with concrete preconditions, actions, and post-condition checks. Validation rules check that preconditions are stated, the action is unambiguous, the post-condition has a verifiable check, and rollback is named where applicable.
+
+**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.
+
+## What you check (BODY ONLY)
+
+### 1. Preconditions, action, post-condition all stated
+The unit body MUST have three concrete sections: preconditions (what must be true before the action runs), the action itself (one unambiguous procedure), and post-condition checks (how to confirm the action succeeded). Reject if any of the three is missing or vague.
+
+### 2. Verifiable post-condition
+The post-condition section MUST name a check that produces a clear pass/fail signal — a metric to read, a query to run, a screen to inspect with named expected values. "Verify by eye that things look good" is a reject.
+
+### 3. Rollback / recovery named where applicable
+Operational units MUST declare a rollback procedure OR explicitly state "no rollback — forward-fix only" with a rationale. Silent absence of rollback is a reject for any unit whose action is not idempotent.
+
+### 4. Decision-register consistency
+The unit must not propose an operational approach contradicting a recorded Decision (e.g., blue-green deploy when Decision N chose canary). Cite the Decision ID.
+
+### 5. Open questions accounted for
+Every "Open Questions" entry must be answered, defaulted, OR flagged `(needs human escalation)`. Operational open questions left to runtime are how outages happen.

package/studios/documentation/stages/review/outputs/REVIEW-REPORT.md

@@ -0,0 +1,25 @@
+---
+name: review-report
+location: .haiku/intents/{intent-slug}/stages/review/artifacts/
+scope: intent
+format: text
+required: true
+---
+
+# Review Report
+
+Categorized review findings with severity ratings and actionable fix recommendations.
+
+## Expected Artifacts
+
+- **Findings** -- categorized by type (accuracy, clarity, completeness, consistency) with severity
+- **Fix recommendations** -- specific problem description and concrete fix for each finding
+- **Technical validation** -- confirmation of correctness from subject-matter expertise
+- **Verdict** -- approve, revise, or reject with rationale
+
+## Quality Signals
+
+- Every finding includes severity, the specific problem, and a concrete fix
+- Technical claims are verified against the running system or source code
+- Terminology consistency is checked against the project glossary
+- Verdict is clear with supporting rationale

package/studios/documentation/stages/review/phases/ELABORATION.md

@@ -0,0 +1,16 @@
+# Review Stage — Elaboration
+
+## Criteria Guidance
+
+### Good criteria — concrete and verifiable
+
+- "Every technical claim is verified against the running system or source code"
+- "Review identifies ambiguous instructions and provides specific rewording suggestions"
+- "Consistency check confirms terminology matches the project glossary throughout"
+
+### Bad criteria — vague (no clear check)
+
+- "Review is done"
+- "Content is accurate"
+- "Feedback is given"
+