From nickcrew-claude-ctx-plugin
Evaluates documentation information architecture: navigation paths, discoverability, progressive disclosure, cross-linking, mental model alignment. Use when restructuring docs, adding sections, or fixing findability issues.
npx claudepluginhub nickcrew/claude-cortexThis skill uses the workspace's default tool permissions.
Evaluate whether documentation is organized so that readers can find what they need,
Provides patterns for documentation hierarchy, navigation, page structures, information density, tables vs lists, and content organization. Useful for planning docs structure and splitting content.
Assesses documentation quality across readability, consistency, audience fit, and prose clarity. Produces scored reviews with actionable findings before releases or doc reviews.
Reviews documentation for content quality including logical flow, user journey alignment, scannability, conciseness, fluff removal, and customer focus. Use for organization checks, peer reviews, or tightening verbose content.
Share bugs, ideas, or general feedback.
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.
doc-completeness-audit identifies gaps — before filling them, ensure the structure
can accommodate new content| Resource | Purpose | Load when |
|---|---|---|
references/ia-heuristics.md | Information architecture evaluation heuristics | Always (Phase 2) |
Phase 1: Map → Build the current doc structure map
Phase 2: Evaluate → Assess against IA heuristics
Phase 3: Model → Compare structure to user mental models
Phase 4: Report → Produce the architecture review with recommendations
Build a complete picture of the documentation architecture.
Generate the file tree of all documentation:
find docs/ site/ -name '*.md' -o -name '*.html' | sort
Record:
Identify every way a reader can navigate:
| Navigation type | Where to find it |
|---|---|
| Sidebar / table of contents | _config.yml nav, front matter nav_order/parent, SUMMARY.md |
| Landing pages | index.md files — read each one for link lists |
| In-page cross-references | [text](link) and {% link %} references between pages |
| Breadcrumbs | Theme configuration or layout templates |
| Search | Search configuration, indexed content |
| Previous/Next links | Auto-generated or manual nav_order sequencing |
Identify how readers arrive:
Map which pages are reachable from each entry point. Pages unreachable from common entry points are effectively invisible.
Output: A structure map with physical hierarchy, navigation paths, and entry points.
Assess the structure against seven heuristics. Load references/ia-heuristics.md
for detailed scoring criteria.
Can readers locate information without knowing where it lives?
| Score | Criteria |
|---|---|
| 5 | Multiple discovery paths to every page. Search works. Navigation reflects user goals |
| 3 | Most content findable via navigation or search. Some pages only reachable by direct link |
| 1 | Content buried. No search. Navigation reflects implementation, not user needs |
Check:
Does the nesting make sense? Can a reader predict where to find something?
| Score | Criteria |
|---|---|
| 5 | Clean, predictable hierarchy. Each level represents a meaningful grouping. Max 3 levels deep |
| 3 | Generally logical but some surprises. Occasional misplaced content. 4 levels in places |
| 1 | Arbitrary nesting. Related content scattered. Deep hierarchies (5+). Categories overlap |
Check:
Does the doc set layer information from simple to complex?
| Score | Criteria |
|---|---|
| 5 | Clear learning path. Quick start → guides → reference → advanced. Each layer self-sufficient |
| 3 | Some layering exists but not explicit. Reader may hit advanced content before basics |
| 1 | All content at same depth. No distinction between introductory and advanced material |
Check:
Do links between pages create useful connections or noise?
| Score | Criteria |
|---|---|
| 5 | Links are contextual, bidirectional where appropriate, and create meaningful paths |
| 3 | Links exist but some are one-directional, orphaned, or link to the wrong section |
| 1 | Few cross-links. Pages are isolated. No "See also" or "Related" patterns |
Check:
Do similar pages follow similar structures?
| Score | Criteria |
|---|---|
| 5 | Clear templates per doc type. All reference pages look alike. All tutorials follow the same flow |
| 3 | Some patterns visible but not universal. Newer docs follow conventions, older ones don't |
| 1 | Every page is a snowflake. No discernible pattern across similar content types |
Check:
Are different doc types (reference, tutorial, guide, explanation) kept distinct?
| Score | Criteria |
|---|---|
| 5 | Clear separation. Reference is reference. Tutorials are tutorials. No hybrid pages |
| 3 | Mostly separated but some pages mix types (reference data inside a tutorial) |
| 1 | No separation. Single pages try to be reference, tutorial, and explanation simultaneously |
Check:
Is the structure sustainable as docs grow?
| Score | Criteria |
|---|---|
| 5 | Adding a new doc page requires no restructuring. Clear home for every doc type |
| 3 | Most new content has a natural home. Occasional need to reorganize |
| 1 | Every new page requires debate about where it goes. Structure is at capacity |
Check:
Compare the documentation structure to how users actually think about the product.
Identify the primary mental models users bring:
| Model type | Structure | Example |
|---|---|---|
| Task-based | "I want to do X" | Organized by workflow: install → configure → deploy |
| Feature-based | "I want to learn about X" | Organized by component: agents, skills, rules, hooks |
| Role-based | "I'm a [role]" | Organized by audience: user guide, admin guide, developer guide |
| Chronological | "What do I do first?" | Organized by sequence: getting started → daily use → advanced |
Most doc sets serve multiple models. The question is: which model does the navigation reflect, and does it match the primary user need?
# Documentation Architecture Review
**Review date:** YYYY-MM-DD
**Scope:** [doc set reviewed]
**Total pages:** N
**Max depth:** N levels
**Orphaned pages:** N
---
## Summary
[2-3 sentences: overall architecture assessment]
Heuristic scores:
| Heuristic | Score | Key Finding |
|-----------|-------|-------------|
| Findability | N/5 | [one line] |
| Hierarchy Coherence | N/5 | [one line] |
| Progressive Disclosure | N/5 | [one line] |
| Cross-Linking Quality | N/5 | [one line] |
| Consistency of Patterns | N/5 | [one line] |
| Separation of Concerns | N/5 | [one line] |
| Maintenance Burden | N/5 | [one line] |
| **Overall** | **N/35** | |
Architecture grade: [A (30-35) / B (24-29) / C (18-23) / D (12-17) / F (<12)]
---
## 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]
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.
docs/archive/) — they are historicalreferences/ia-heuristics.md — Detailed scoring criteria and examples for each heuristic