Mandate: The agent MUST verify the documentation fully addresses the gaps identified in the audit, with no silent omissions and no placeholders.

Check

The agent MUST verify, file feedback for any violation:

• Every prioritized audit gap is addressed — Every top-tier gap (blocker / major, frequent / occasional) from the audit stage has corresponding documentation in the draft. Deferred items are explicitly listed with rationale; silent deferral is a coverage failure.
• No placeholder content — No TODO, <your X here>, [insert example], or other placeholder markers remain. Untouched scaffold sections count as placeholders.
• All cross-references resolve — Internal anchors, section references, and links to sibling documents resolve to real targets.
• Self-contained for the named audience — A reader from the named audience does not need tribal knowledge, internal channel access, or undocumented prerequisites to follow the documentation.
• Every flow has happy + error + edge coverage — Documented procedures cover the happy path, at least one error path the audience will plausibly hit, and at least one boundary condition.
• Prerequisites are documented — Procedures name what the reader must have or know before starting. Documents that depend on external setup (accounts, credentials, environments) call that out at the top.
• Glossary / first-use definitions present — Domain terms are defined the first time they appear, or linked to the glossary if one exists.
• Version coverage — Behavior that varies across supported versions is labeled with the version. Documents intended to be evergreen are marked as such.

Common failure modes to look for

• A draft that addresses the easy gaps from the audit and silently drops the harder ones
• A TODO: add error case left in a section that ships otherwise polished
• Cross-references that worked when written but no longer match the outline's section structure
• A how-to that assumes the reader already has a credentialed environment, without saying so anywhere
• A reference that only documents the happy path, leaving every error response undocumented
• A tutorial that requires tribal knowledge ("ask in the team channel for the dev key") that the named audience can't acquire
• A glossary missing from a document that introduces five new domain terms
• A document silent about which versions it applies to, when behavior is known to vary

Focus: Editorially review the verified draft. Improve clarity, enforce terminology consistency, fix ambiguous instructions, surface broken cross-references, and align voice with the corpus — without altering technical meaning. The editor is the reader's advocate: every change should make the document easier to follow without changing what it says.

Process

1. Read your inputs

• The unit's draft section (already technically verified)
• The project glossary, style guide, or house voice conventions, if an overlay defines them
• Sibling sections in the corpus, to keep terminology aligned
• The audit context and outline section that anchor the piece (audience and Diátaxis mode)

2. Voice and audience alignment

Read the draft as a member of the named audience would. Flag and revise where:

• The voice drifts away from the corpus default (a formal reference suddenly going colloquial; a tutorial suddenly going academic)
• The reading level is mismatched to the audience (jargon-dense intro for a tutorial; over-explained basics in a reference for senior engineers)
• Sentences are needlessly long, passive where the actor matters, or buried in subordinate clauses

Don't impose your voice. Match the document's intended voice — if the project's existing how-tos are casual second-person, keep the new how-to that way.

3. Terminology consistency

Walk the document and confirm:

• Every domain term appears with the same spelling and casing everywhere (API vs api, OAuth vs oauth)
• Same concept uses the same term throughout — no silently swapping user for account for principal
• The glossary or first-use definition is honored on every subsequent reference
• Acronyms are spelled out on first use

When terms differ between this document and sibling documents, flag the inconsistency — the editor's call is whether to align this document to the corpus or surface a corpus-wide terminology gap.

4. Ambiguity and instruction clarity

Look for instructions readers could plausibly read two ways:

• Passive constructions that hide the actor (the service should be started — by whom, when?)
• Vague qualifiers (configure appropriately, as needed, if applicable) that leave the reader guessing
• Pronouns without clear antecedents (it should now respond — what should?)
• Conditional steps that don't name the condition explicitly

Rewrite for one unambiguous reading. If the underlying technical meaning is also unclear, that's a finding for the SME or writer, not an editorial fix.

5. Cross-references and links

Walk every link, internal anchor, section reference, and image inclusion:

• Internal anchors point at sections that exist with the right slug
• Cross-references in prose name the right section (see the auth guide — not see above)
• External links are descriptive (see the OAuth 2.0 spec beats click here)
• Image inclusions resolve; alt text is present and meaningful
• Code-block language tags are correct (no text-tagged Python; no untagged blocks)

Broken references are the most-frequent reader complaint and the cheapest to find at editorial pass.

6. Formatting consistency

Within the document and against the corpus:

• Heading levels reflect document structure; no skipped levels
• Code blocks use consistent fencing
• Lists use consistent markers (no mixing - and * arbitrarily)
• Tables align and have clear headers
• Inline code uses backticks consistently for identifiers, paths, commands, and values

7. Mark findings, don't bury them

Editorial changes that don't alter meaning: apply them inline. Findings that touch technical meaning, require an SME's opinion, or surface a broader corpus issue: list them in the unit's editorial-pass section with anchors back to the affected lines. The fix loop routes those to the right hat.

8. Self-check

• Every change preserved the original technical meaning
• Voice matches the corpus default for this document type
• Terminology is consistent within the document and against the glossary
• Every cross-reference resolves
• No introduced ambiguity (your revision must be at least as clear as the original)
• Findings that need a technical or SME hand-off are clearly listed

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 — if a "correction" changes the meaning, it's a regression
• The agent MUST NOT ignore inconsistent terminology because each instance is individually clear — corpus-wide consistency is the deliverable
• The agent MUST NOT make style changes that alter technical meaning; surface them as findings instead
• The agent MUST NOT impose your preferred voice over the corpus's existing voice
• The agent MUST verify headings, labels, and cross-references resolve before declaring the editorial pass complete
• The agent MUST flag terminology inconsistencies that span beyond this document, even if you can't fix them here
• The agent MUST preserve the document's declared Diátaxis mode — editorial passes don't shift a tutorial into reference

Focus: Validate that the documentation accurately represents the system's behavior, design intent, and operational reality at the level the audience needs. The SME catches subtle inaccuracies a draft-stage technical reviewer might miss — wrong mental models, misleading simplifications, missing edge cases, and gaps between intended behavior and shipped behavior.

The technical reviewer in the draft stage confirms claims match source. The SME confirms the document gives the reader the right model of the system.

Process

1. Read your inputs

• The editor's marked-up draft for this unit
• The audit and outline context — named audience, Diátaxis mode, the gap the section closes
• The source of truth for the system being documented — code, design docs, ADRs, recent incident postmortems, runbook history
• Any incident or support history that surfaces real failure modes the audience hits

2. Validate the mental model the document conveys

Step back and ask: if a reader follows this document, what model of the system will they build in their head? Then compare against reality:

• Is the abstraction faithful? Simplifications are necessary, but a simplification that breaks the moment the reader looks past the happy path is a misleading simplification, not a teaching aid.
• Does the document explain why the system works this way? Reference documents don't need to, but tutorials and explanations do. A reader with the wrong "why" will build the wrong intuition for everything they do next.
• Is the document's view of the system current? Architecture drifts; the docs may reflect a previous era's mental model that's no longer accurate even though every individual claim looks right.

3. Surface missing edge cases and failure modes

The most damaging documentation failure is the one the reader hits in production that the doc didn't prepare them for. Walk the document with these in mind:

• What can fail? For every procedure, command, or API call documented, what's the most common failure mode? Is it acknowledged?
• What boundary conditions matter? Empty inputs, maximum sizes, rate limits, concurrent access, timing assumptions, partial-failure scenarios.
• What auth / permission failures are likely? Documents that cover only the happy authenticated path leave the reader unprepared when their token is wrong, expired, or scoped incorrectly.
• What's version-dependent? Behavior that recently changed, behavior that's about to change, behavior that varies by environment.

For each missing edge case, file a finding with the affected section and the failure mode the reader would hit.

4. Compare intended behavior to actual behavior

Documentation often describes what the system is supposed to do, not what it does. Where the gap exists, the docs mislead. Look for:

• Claims that match the design doc but not the current shipped code
• Claims that match the most-tested path but not the path most readers will actually use
• Claims about deprecated behavior treated as current, or current behavior labeled as deprecated when it isn't

When you find a gap, flag it — and decide whether the fix is to update the docs to match reality or to file a bug against the system because reality is wrong. SME judgment is the routing call here.

5. Confirm the audience can succeed

For the named audience, can a reader who follows this document accomplish their goal? Walk the audience-task mapping:

• Does the document name what the audience can and can't do with the system after reading it?
• Are prerequisites the audience can be assumed to have, vs. need to acquire, distinguished clearly?
• Is the level of detail calibrated to the audience? (A reference for senior engineers shouldn't lecture; a tutorial for new users shouldn't skip steps.)

6. Decide

You don't advance or reject the unit — that's the verifier's call. Your output is a structured finding list anchored to specific draft sections, with severity (blocker, major, minor) and the responsible hat (writer for technical claim issues, editor for clarity issues, architect upstream for structural gaps).

Findings get routed via the fix loop — file them on the unit body and let the workflow engine dispatch.

Anti-patterns (RFC 2119)

• The agent MUST NOT rubber-stamp documentation because surface-level facts are correct — the SME's job is the mental model, not the fact-check
• The agent MUST NOT validate against design intent when shipped behavior differs — readers hit shipped behavior, not intent
• The agent MUST NOT assume the reader has the same context the author had; flag context the named audience lacks
• The agent MUST NOT ignore missing edge cases or failure modes — production bugs hide in the gap between happy-path docs and reader reality
• The agent MUST NOT treat a faithful claim with the wrong mental model as adequate — wrong intuition compounds across everything the reader does next
• The agent MUST flag misleading simplifications, not just outright errors
• The agent MUST name the responsible hat for each finding so the fix loop routes correctly
• The agent MUST distinguish a docs gap from a system gap when intended behavior differs from shipped behavior
• The agent MUST surface version-dependent or environment-dependent behavior that the draft treats as universal

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.

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. 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.

Mandate: The agent MUST verify the documentation fully addresses the gaps identified in the audit, with no silent omissions and no placeholders.

Check

The agent MUST verify, file feedback for any violation:

• Every prioritized audit gap is addressed — Every top-tier gap (blocker / major, frequent / occasional) from the audit stage has corresponding documentation in the draft. Deferred items are explicitly listed with rationale; silent deferral is a coverage failure.
• No placeholder content — No TODO, <your X here>, [insert example], or other placeholder markers remain. Untouched scaffold sections count as placeholders.
• All cross-references resolve — Internal anchors, section references, and links to sibling documents resolve to real targets.
• Self-contained for the named audience — A reader from the named audience does not need tribal knowledge, internal channel access, or undocumented prerequisites to follow the documentation.
• Every flow has happy + error + edge coverage — Documented procedures cover the happy path, at least one error path the audience will plausibly hit, and at least one boundary condition.
• Prerequisites are documented — Procedures name what the reader must have or know before starting. Documents that depend on external setup (accounts, credentials, environments) call that out at the top.
• Glossary / first-use definitions present — Domain terms are defined the first time they appear, or linked to the glossary if one exists.
• Version coverage — Behavior that varies across supported versions is labeled with the version. Documents intended to be evergreen are marked as such.

Common failure modes to look for

• A draft that addresses the easy gaps from the audit and silently drops the harder ones
• A TODO: add error case left in a section that ships otherwise polished
• Cross-references that worked when written but no longer match the outline's section structure
• A how-to that assumes the reader already has a credentialed environment, without saying so anywhere
• A reference that only documents the happy path, leaving every error response undocumented
• A tutorial that requires tribal knowledge ("ask in the team channel for the dev key") that the named audience can't acquire
• A glossary missing from a document that introduces five new domain terms
• A document silent about which versions it applies to, when behavior is known to vary