Outline

Ask review

Structure the documentation with clear information architecture

Hats
2
Review Agents
1
Review
Ask
Unit Types
Outline
Inputs
Audit

Dependencies

Auditaudit-report

Hat Sequence

1

Architect

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.

Produces: Document outline with section hierarchy, purpose statements per section, audience annotations, and cross-reference plan.

Reads: Audit gap analysis, intent problem statement, existing documentation structure.

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
2

Outline Reviewer

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.

Produces: Outline review with structural feedback — missing paths, redundant sections, navigation concerns, and suggested reordering.

Reads: Architect's outline, audit gap analysis via the unit's ## References section.

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

Review Agents

Structure

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

Outline

Criteria Guidance

Good criteria examples:

  • "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 examples:

  • "Outline is structured"
  • "Sections are organized"
  • "Architecture is clear"

Completion Signal (RFC 2119)

Document outline MUST exist with a logical information architecture. Each section MUST have a defined purpose and audience. The outline-reviewer MUST have validated that the structure serves the reader's workflow — task-oriented navigation, progressive disclosure, and no orphaned sections.