Doc Architecture Review

Documentation Architecture Review

Evaluate whether documentation is organized so that readers can find what they need, understand where they are, and navigate efficiently. The output is an architecture assessment with specific restructuring recommendations — not new content.

When to Use

• When restructuring or reorganizing documentation
• When adding a new section or doc type to an existing set
• When users report "I know it's documented somewhere but can't find it"
• When the doc set has grown organically and needs rationalization
• After doc-completeness-audit identifies gaps — before filling them, ensure the structure

can accommodate new content

• Periodic review of navigation and discoverability

Quick Reference

---

Workflow Overview

Phase 0: Personas    → Establish the doc set's primary 1-3 personas
Phase 1: Map         → Build the current doc structure map (incl. link graph)
Phase 2: Evaluate    → Score against IA heuristics, parameterized by personas + doc type
Phase 3: Model       → Compare structure to user mental models per persona
Phase 4: Report      → Produce the architecture review with per-persona findings

---

Phase 0: Establish Personas

A "good" architecture is good for someone specific. Without personas, the heuristics apply a default standard that systematically misjudges docs serving non-default audiences (a flat reference doc scored as "poorly hierarchical" because it doesn't follow Quick Start → advanced).

Step 0a — Identify the doc set's audiences

Read the doc set's entry pages (README, index.md, landing pages) and the highest-traffic top-level docs. Identify which 1–3 personas from references/personas.md are the primary readers. Common patterns:

Step 0b — Draft persona profiles

For each identified persona, copy the profile from references/personas.md verbatim. Don't paraphrase — the explicit profile is what calibrates downstream sub-agents. If a persona almost fits but a dimension differs, define a custom persona using the same five-field structure.

Step 0c — Note conflicts

If the doc set serves more than one persona with conflicting needs (e.g., Onboarding User wants narrative, API Looker-Up wants terseness), note this explicitly. The synthesis report will surface where current structure favors one persona at the cost of another.

Output: A persona block (1–3 personas + any conflict notes) that feeds every downstream sub-agent prompt.

---

Phase 1: Map the Current Structure

Build a complete picture of the documentation architecture.

Step 1a: Physical Structure

Generate the file tree of all documentation:

find docs/ site/ -name '*.md' -o -name '*.html' | sort

Record:

• Directory hierarchy and nesting depth
• File count per directory
• Naming conventions (kebab-case, snake_case, mixed)

Step 1b: Navigation Structure

Identify every way a reader can navigate:

Step 1c: Entry Points

Identify how readers arrive:

• Direct — typing a URL or bookmarking
• Search — site search or external search engine
• Navigation — sidebar, breadcrumb, landing page links
• Cross-reference — link from another doc page
• External — README, GitHub, blog post, error message linking to docs

Map which pages are reachable from each entry point. Pages unreachable from common entry points are effectively invisible.

Step 1d: Link Graph (mechanical)

Run the bundled link graph analyzer to extract deterministic facts about inter-doc linking:

python3 skills/doc-architecture-review/scripts/link_graph.py --scope all --json > graph.json

# Or human-readable:
python3 skills/doc-architecture-review/scripts/link_graph.py --scope all

The script produces:

• Orphans — pages with no inbound links (excluding entry points like

index.md and README.md). Direct input to Heuristic 1 (Findability).

• Dead-ends — pages with no outbound links. Content silos.
• Reciprocity ratio — fraction of edges that have a back-link. Direct

input to Heuristic 4 (Cross-Linking Quality).

• Hubs — pages with high in-degree. Natural reference targets.
• Broken links — internal links that don't resolve. Direct input to

Heuristic 4.

These are mechanical facts, not judgments. The judgment-heavy parts of Heuristics 1 and 4 (are links contextual? do navigation labels use user language?) are evaluated by sonnet sub-agents in Phase 2.

Output: A structure map with physical hierarchy, navigation paths, entry points, and the link graph JSON.

---

Phase 2: Evaluate Against IA Heuristics

Assess the structure against seven heuristics. Load references/ia-heuristics.md for detailed scoring criteria.

Mechanical vs judgment split

For a doc set of any meaningful size, the orchestrator can't read every page to score every heuristic — that strains the context window and produces patchy evaluation. Phase 2 splits work:

• Mechanical part — driven by the Phase 1d link graph JSON. Orphan

counts, reciprocity ratio, broken-link counts, hub identification: these are facts, not judgments. The orchestrator reads the JSON and assigns scores deterministically.

• Judgment part — dispatched to general-purpose + sonnet sub-agents

organized by heuristic. Each agent receives a focused slice of the doc set and returns specific findings with citations.

Sonnet sub-agent dispatch

Three judgment-heavy heuristics warrant dedicated agents. Each agent's prompt inlines the persona block from Phase 0 and the relevant doc-type criteria from references/ia-heuristics.md. The agent scores per-persona, not against a generic default.

Agent 1 — Findability narrative review (Heuristic 1):

subagent_type: "general-purpose"
model: "sonnet"
description: "Findability narrative review"

Prompt template:

Read landing pages, navigation configs (_config.yml, front-matter
nav_order/parent), and the orphans list from the link graph JSON.

Personas (from Phase 0):
<INLINE PERSONA BLOCK — full profile per persona, not summary>

Doc-type criteria for Heuristic 1:
<INLINE Heuristic 1 section from references/ia-heuristics.md>

For each persona, score Findability 1-5 and identify specific failures:
- Are navigation labels in this persona's language?
- Are entry points appropriate for how this persona arrives?
- Are orphans concentrated in a doc type that fails this persona's task?

Output per-persona scores plus findings. When personas conflict (e.g.,
nav labels in one's language fail another), surface the conflict
explicitly rather than averaging.

Agent 2 — Cross-linking quality review (Heuristic 4):

subagent_type: "general-purpose"
model: "sonnet"
description: "Cross-link quality review"

Prompt template:

Read 5-10 representative pages across doc types. Read the link graph
JSON's reciprocity statistics.

Personas (from Phase 0):
<INLINE PERSONA BLOCK>

Doc-type criteria for Heuristic 4:
<INLINE Heuristic 4 section from references/ia-heuristics.md — note
the per-doc-type linking patterns table>

For each persona, score Cross-Linking 1-5. Distinguish:
- Are links contextual (explain why to follow)? Low priority for
  Looker-Up reference scanning, high priority for Onboarding User
  exploration.
- Does linking density match the doc type's pattern?
- Are there mutual links between related concepts (high reciprocity)
  where appropriate?

Agent 3 — Pattern consistency review (Heuristic 5, per-doc-type dispatch):

For each doc type present (reference, tutorial, guide, explanation, ADR, runbook, README), dispatch one sonnet agent with all docs of that type:

subagent_type: "general-purpose"
model: "sonnet"
description: "Consistency review for <doc-type>"

Prompt template:

Examine all <DOC_TYPE> docs in the set: <LIST_OF_PATHS>.

Persona affected (from Phase 0):
<INLINE PERSONA BLOCK for this doc type's primary persona>

Expected template for <DOC_TYPE> per references/ia-heuristics.md
Heuristic 5:
<INLINE template signals row>

Identify the implicit template — common section headings, structural
conventions — and flag pages that deviate. For each deviation:
- Is it intentional (handles a special case the template doesn't
  cover)? Note the reason.
- Is it accidental (older page; different author; conventions hadn't
  settled)? Flag for harmonization.

Score 1-5 for within-type consistency.

Heuristic scoring

Heuristic 1: Findability

Can readers locate information without knowing where it lives?

Check:

• Orphaned pages (no inbound links, not in navigation)
• Dead ends (pages with no outbound links to related content)
• Search coverage (are all pages indexed? do headings use searchable terms?)
• Navigation labels (do they use user language or developer jargon?)

Heuristic 2: Hierarchy Coherence

Does the nesting make sense? Can a reader predict where to find something?

Check:

• Depth — flag anything nested >3 levels
• Breadth — flag directories with >10 immediate children (consider subcategories)
• Sibling coherence — are items at the same level truly peers?
• Naming — do directory names describe contents from the reader's perspective?

Heuristic 3: Progressive Disclosure

Does the doc set layer information from simple to complex?

Check:

• Quick start exists and is prominently linked
• Getting started path is linear and completable in <15 minutes
• Advanced topics are separated from basics, not interleaved
• Each doc states its prerequisites
• Cross-references point readers to deeper material, not shallower

Heuristic 4: Cross-Linking Quality

Do links between pages create useful connections or noise?

Check:

• Link density — pages with zero outbound links, pages with >20
• Reciprocity — if A links to B, does B link back (where appropriate)?
• Context — links explain why the reader would follow them, not just "click here"
• Anchor precision — links go to the right section, not just the right page
• Broken links — links that resolve to 404 or wrong content

Heuristic 5: Consistency of Patterns

Do similar pages follow similar structures?

Check:

• Do all reference pages have the same sections?
• Do all tutorials follow the same progression?
• Do all guides have prerequisites and next steps?
• Are metadata conventions (front matter, titles, descriptions) consistent?

Heuristic 6: Separation of Concerns

Are different doc types (reference, tutorial, guide, explanation) kept distinct?

Check:

• Pages that mix "how to" with "what it is" with "API details"
• Tutorials that double as reference (readers can't scan for a specific flag)
• Reference pages that include narrative explanations better suited to guides
• Use the Diataxis framework as a lens: tutorials, how-to guides, reference, explanation

Heuristic 7: Maintenance Burden

Is the structure sustainable as docs grow?

Check:

• Is there a clear directory/category for new feature docs?
• Are naming conventions documented and followed?
• Would doubling the doc set break the navigation?
• Are there catch-all directories growing without bounds?

---

Phase 3: Mental Model Comparison

Compare the documentation structure to how users actually think about the product.

User Mental Models

Identify the primary mental models users bring:

Most doc sets serve multiple models. The question is: which model does the navigation reflect, and does it match the primary user need?

Mismatch Indicators

• Users search for task-based terms but docs are organized by feature
• Getting started guide assumes feature knowledge the reader doesn't have yet
• Navigation uses internal terminology that users don't recognize
• Users land on the right page but can't find the right section

---

Phase 4: Produce the Architecture Review

Report Format

# Documentation Architecture Review

**Review date:** YYYY-MM-DD
**Scope:** [doc set reviewed]
**Total pages:** N
**Max depth:** N levels
**Orphaned pages:** N
**Personas evaluated:** [comma-separated list from Phase 0]

---

## Personas

[Inline the Phase 0 persona block — full profile per persona, plus any conflict notes]

---

## Summary

[2-3 sentences: overall architecture assessment, per-persona where relevant]

Heuristic scores per persona:

| Heuristic | Persona A | Persona B | Persona C | Notes |
|-----------|-----------|-----------|-----------|-------|
| Findability | N/5 | N/5 | N/5 | [one line, surface persona conflicts] |
| Hierarchy Coherence | N/5 | N/5 | N/5 | [one line] |
| Progressive Disclosure | N/5 or N/A | N/5 or N/A | N/5 or N/A | [N/A is valid for reference/ADR — see rubric] |
| Cross-Linking Quality | N/5 | N/5 | N/5 | [one line] |
| Consistency of Patterns | N/5 | N/5 | N/5 | [one line] |
| Separation of Concerns | N/5 | N/5 | N/5 | [one line] |
| Maintenance Burden | N/5 | N/5 | N/5 | [one line] |
| **Per-persona total** | **N/35** | **N/35** | **N/35** | |

Architecture grade per persona: [A / B / C / D / F]

When grades differ across personas, that's a finding, not a defect to
average away. Flag the structural bias toward whichever persona scores
highest.

---

## Structure Map

[File tree with annotations: orphan markers, depth warnings, misplacement flags]

---

## Critical Findings

### [Finding title]
**Heuristic:** [which]
**Impact:** [who is affected and how]
**Evidence:** [specific examples — pages, paths, search queries]
**Recommendation:** [specific restructuring action]

---

## Navigation Path Analysis

### Path: New User Onboarding
**Entry point:** [where they start]
**Goal:** [what they need to accomplish]
**Actual path:** [pages they traverse]
**Friction points:** [where they get lost or stuck]
**Ideal path:** [what it should be]

### Path: [Another key user journey]
...

---

## Orphaned Pages

| Page | Why It's Orphaned | Recommendation |
|------|-------------------|----------------|
| [path] | [no inbound links / not in nav] | [add to nav / link from X / archive] |

---

## Mental Model Alignment

**Primary user model:** [task / feature / role / chronological]
**Current structure model:** [which model the nav reflects]
**Alignment:** [match / partial / mismatch]
**Recommendation:** [restructure, add alternative navigation, or accept the gap]

---

## Restructuring Recommendations

Ordered by impact:

1. [Highest impact structural change]
2. [Second highest]
3. ...

---

## Strengths

[What's working well in the current architecture]

---

Integration with Other Doc Skills

doc-maintenance         →  Structural health (links, orphans, folders)
doc-claim-validator     →  Semantic accuracy (do claims match code?)
doc-completeness-audit  →  Topic coverage (is everything documented?)
doc-quality-review      →  Prose quality (is it well-written?)
doc-architecture-review →  Information architecture (is it findable?)

Run this skill after doc-completeness-audit — you need to know what's missing before evaluating whether the structure can accommodate it. Run before filling gaps, so new content lands in the right place.

---

Anti-Patterns

• Do not reorganize during the review — produce findings, not a new file tree
• Do not treat your preferred structure as the "correct" one — evaluate against user needs
• Do not evaluate archived docs (docs/archive/) — they are historical
• Do not confuse "I know where things are" with "a new user would know" — test with fresh eyes
• Do not recommend restructuring for its own sake — the cost of moving docs (broken links,

muscle memory, bookmarks) must be justified by the improvement

• Do not ignore the cost of change — a mediocre-but-stable structure may be better than

a perfect structure that requires moving 50 pages

---

Bundled Resources

References

• references/ia-heuristics.md — Detailed scoring criteria and examples for each heuristic

Information Architecture Heuristics — Doc-Type-Aware Criteria

Detailed scoring criteria for each IA heuristic, parameterized by doc type. A "good" architecture for a reference doc looks different from a "good" architecture for a tutorial — applying a single rubric across both produces systematic misjudgment.

Pair this file with references/personas.md. Each heuristic specifies which personas it matters most for; the doc-type criteria say what 5/5 looks like for that combination.

Doc types

These types appear throughout the heuristics below. Each has a characteristic shape that informs scoring.

A doc set typically contains multiple types. Evaluate each type against its own criteria; the synthesis identifies cross-type problems (misplaced docs, type-mixing).

---

Heuristic 1: Findability

Core question: Can the target persona locate this content without already knowing where it lives?

Per-doc-type criteria for 5/5

Diagnostic checks (universal)

• Orphan analysis — pages with zero inbound links. Excludes README/index entry points. (scripts/link_graph.py produces this.)
• Search effectiveness — do headings match queries the relevant persona would type? Test specifically: an Incident Responder searching the alert text, an Onboarding User searching "how to install"
• Multiple discovery paths — high-value pages should have ≥2 paths (nav + cross-link, or nav + search hit)
• Navigation labeling — labels reflect persona language, not internal jargon

Persona-specific failure modes

• Onboarding User: front door doesn't surface quick start; terms are jargon
• Looker-Up: deep links don't work; reference content embedded in tutorial prose
• Incident Responder: runbook URL not in alert; alert text doesn't match heading
• Operator: config docs scattered; missing config items

Scoring

---

Heuristic 2: Hierarchy Coherence

Core question: Can the target persona predict where to find something?

Per-doc-type criteria for 5/5

Why depth differs by doc type

A reference doc going 3 levels deep means the Looker-Up has to know the category before they can find the symbol. A tutorial needs phase hierarchy because order matters. A runbook should be 2 levels because scenarios cluster naturally. Forcing reference into tutorial-style depth, or flattening a tutorial into reference-style, both fail.

Diagnostic checks

• Depth test — flag deviations from the type's expected depth
• Sibling coherence — items at the same level should be the same kind
• Predictability test — given a topic, can the persona guess the directory? Hesitation = ambiguity
• Category overlap — same topic in two directories signals unclear hierarchy

Persona-specific failure modes

• Looker-Up: reference nested deeper than necessary; category guesswork required
• Onboarding User: tutorial flattened; phase boundaries invisible
• Incident Responder: runbook scenarios too granular (50 specific scenarios) or too broad (3 catch-all docs)

Scoring

Apply the type-appropriate depth from the table above:

---

Heuristic 3: Progressive Disclosure

Core question: Does the doc set layer information appropriately for its readers? This heuristic applies very differently by doc type.

Per-doc-type criteria

Common misjudgment to avoid

A reference doc with no Quick Start section is correctly structured, not deficient. Scoring it 2/5 because "advanced topics are interleaved with basics" misreads what reference structure is for. Score N/A or focus on reference-appropriate criteria (completeness, scannability) instead.

Diagnostic checks (apply only when doc type uses progressive disclosure)

• Quick Start prominence — for tutorial/guide/README sets, can the

reader find quick start in <10 seconds from the front door?

• Linear path completability — can a fresh reader complete the

getting-started path in <15 minutes?

• Prerequisites stated — each tutorial/guide names what the reader

must already know

• Forward references — flag tutorials that reference concepts

before introducing them

Persona-specific failure modes

• Onboarding User: doc set lacks visible Quick Start; advanced before basics
• Looker-Up: reference forced into "intro / basics / advanced" structure that slows lookup
• Incident Responder: runbook starts with "understanding the system" before the procedure

Scoring

---

Heuristic 4: Cross-Linking Quality

Core question: Do links between pages create useful connections for the relevant personas?

Per-doc-type criteria for 5/5

Mechanical inputs (from link_graph.py)

• Reciprocity ratio (mutual link pairs / total directed edges)
• Link density per doc (avg outbound links per page)
• Hub identification (in-degree distribution)

Qualitative checks (sonnet sub-agent)

• Contextual links — do links explain why the reader would follow them, or are they "click here" / dumped lists?
• Anchor precision — do links go to the right section, not just the right page?
• Relevance per persona — does the linked-to content serve the linking persona's task?

Persona-specific failure modes

• Looker-Up: reference pages with no cross-links to related symbols (forces back-and-forth between pages)
• Onboarding User: tutorial links jump to advanced reference too eagerly
• Architect Debugger: ADRs that don't link to the code they affect or the ADRs they supersede

Scoring

---

Heuristic 5: Consistency of Patterns

Core question: Do similar pages follow similar structures?

Per-doc-type criteria for 5/5

For each doc type, all instances of that type should follow a consistent template. The templates differ by type but consistency within type is universal.

Diagnostic checks

• Template adherence per type — for each doc type, identify the implicit template and flag deviations
• Frontmatter consistency — same fields, same conventions
• Heading hierarchy consistency — ## vs ### use, capitalization
• Code block conventions — language tags, indentation

When deviation is acceptable

A doc that intentionally deviates from the template for a documented reason is not a finding. Score the deviation only if the agent can identify no reason for the difference.

Scoring

---

Heuristic 6: Separation of Concerns

Core question: Are different doc types kept distinct, or do individual pages mix types?

What "separation" means per type

Diataxis as a lens

The Diataxis framework (tutorial / how-to guide / reference / explanation) is useful here. Single pages that try to be three of these at once — the README that's also tutorial that's also reference — are the dominant failure mode. Persona-mismatched mixing is the second.

Persona-specific failure modes

• Looker-Up reading reference: narrative explanations slow lookup
• Onboarding User reading tutorial: parameter exhaustiveness drowns the journey
• Incident Responder reading runbook: background context wastes seconds during incidents
• Architect Debugger reading ADR: how-to instructions instead of decision rationale

Diagnostic checks

• Page audit — for each page, identify its declared type and check for content of other types
• Hybrid detection — pages that combine 3+ types are almost always doing too much
• Persona impact — score the cost of the mixing per persona

Scoring

---

Heuristic 7: Maintenance Burden

Core question: Is the structure sustainable as the doc set grows?

Per-doc-type criteria for 5/5

Diagnostic checks

• Adding a new doc — does any new feature have an obvious home in the existing structure?
• Naming conventions — are they documented and followed?
• Catch-all directories — are any directories growing unbounded (e.g., docs/misc/)?
• Doubling test — would a 2x doc-set break the navigation or hierarchy?

Persona-specific impact

• Maintenance burden is felt mostly by Contributor, but its symptoms surface to all personas as stale docs
• A doc set that's hard to maintain produces stale content that fails every persona

Scoring

---

Aggregating per-persona scores

When evaluating a doc set against multiple personas, score each heuristic per-persona, not as a single average. The synthesis surfaces conflicts:

Heuristic 2 (Hierarchy Coherence)
  For Looker-Up: 5/5 (flat reference structure, predictable lookup)
  For Onboarding User: 2/5 (no learning path; expected to navigate flat
    structure without guidance)
  Synthesis: structure biased toward Looker-Up. If Onboarding User is
    a primary persona, recommend layering a Quick Start above the
    flat reference.

Per-persona scoring is what makes the audit useful when audiences conflict. A single average score hides the bias and produces recommendations that help one persona at the cost of another.

Personas Library

Concrete reader profiles for evaluating documentation. Use these — don't invent fuzzier ones — when a sub-agent needs to score a doc against specific reader needs.

A "good" hierarchy or progressive disclosure looks different for each persona below. A reference doc that works for the API Looker-Up may fail the Onboarding User entirely; that's not a defect, it's a persona mismatch. The skill flags persona mismatches as findings, not as universal errors.

This file is shared with doc-quality-review. When updating personas here, sync the change to that skill's references/personas.md to keep evaluation consistent across the doc-* family.

How to use this library

1. In Phase 0, identify the 1–3 personas that the doc set serves primarily. A doc set serving more than 3 simultaneously is usually doing too much; flag that as an architectural finding. 2. In agent prompts, inline the relevant personas verbatim. Don't summarize — sub-agents calibrate better with the explicit profile than with a one-line audience label. 3. In findings, name the persona affected. "Findability fails for Incident Responder because alert text doesn't match runbook headings" beats "findability is poor." 4. For multi-persona docs, evaluate per-persona. The synthesis surfaces conflicts ("works for expert lookup, fails new user onboarding — current bias is toward expert").

Personas

Onboarding User

Evaluates positively:

• Quick start visible from the front door, completable in <15 minutes
• Each step explains why, not just what, so the mental model builds
• Clear "what's next" pointer at the end of each stage
• Vocabulary is introduced before use
• Examples are complete (no "fill in your own X" without showing what X looks like)

Evaluates negatively:

• Front door overwhelms with everything at once (no quick-start prominence)
• Required prerequisites aren't stated
• Jargon used before definition
• Examples reference undefined variables or omit setup
• Quick start doesn't actually work end-to-end

API Looker-Up

Evaluates positively:

• Direct URL per symbol (deep-linkable)
• Flat or shallow hierarchy — no required reading order
• Tables for parameter listings
• Type signatures upfront, examples below
• Cross-links to related symbols

Evaluates negatively:

• Reference content embedded in tutorial prose
• Required reading of multiple sections to find one fact
• Missing edge cases (what if the parameter is null? what does it return on failure?)
• Inconsistent template across reference pages — has to relearn the layout

Incident Responder

Evaluates positively:

• Scenario-keyed entry (alert text matches runbook heading)
• Worst-case / most-common failure first, not last
• Steps are imperative, copy-pasteable
• Decision points clearly marked ("if X, do A; if Y, do B")
• Rollback path stated explicitly

Evaluates negatively:

• Background / "why" content before the procedure
• Discovery flow that requires understanding the system to find the right runbook
• Steps phrased as suggestions ("you might want to check…")
• Buried prerequisites
• Multiple runbooks for related scenarios with no cross-links

Architect Debugger

Evaluates positively:

• Architecture docs that explain the design and what alternatives were rejected
• Diagrams that match the code (citable file:line for each box)
• ADRs that capture constraints and reasoning, not just decisions
• Honest discussion of known limitations
• Cross-links between conceptual docs and the code that implements them

Evaluates negatively:

• Marketing-style "we built X because it's amazing" (no constraint discussion)
• Diagrams that don't match the code
• Implementation details with no design rationale
• Missing ADRs for non-obvious choices

Contributor

Evaluates positively:

• CONTRIBUTING.md surfaces dev setup, test commands, style rules in one place
• Clear conventions doc (file naming, commit format, PR shape)
• Examples of well-formed contributions to model on
• Explicit ownership of areas (who reviews what)

Evaluates negatively:

• Conventions scattered across many docs
• "We use $TOOL" without explaining how to run it locally
• PR feedback that cites unwritten rules
• Outdated dev setup that doesn't match current code

Operator

Evaluates positively:

• Complete configuration reference (every env var and config key documented)
• Concrete deployment recipes for common platforms
• Migration paths between versions, with explicit data/state implications
• Monitoring and alerting recommendations
• Capacity / scaling guidance with real numbers

Evaluates negatively:

• "Configure as needed" with no list of what's configurable
• Deployment docs that assume a specific platform without saying so
• Missing upgrade notes between versions
• No rollback guidance
• Vague capacity planning

When to define a custom persona

These six cover most projects. Define a custom persona only when:

• The doc set serves a clearly distinct audience not represented (e.g.,

a regulator reviewing for compliance, an auditor checking security controls, a researcher cross-referencing methodology)

• A core persona above almost fits but a specific dimension differs

significantly (e.g., a low-expertise operator who needs more hand-holding than the standard Operator persona above)

Custom personas use the same five-field structure plus the two "evaluates positively / negatively" lists. Add them inline in the relevant report — don't try to maintain a project-specific persona library here unless the project is large enough that the six standard ones are routinely insufficient.

Multi-persona conflicts

A single doc legitimately serving multiple personas faces structural conflicts. Common conflicts and how to surface them:

Don't pretend conflicts don't exist. The most common architectural failure is silently optimizing for one persona while claiming to serve all of them.