From duet
Evaluate and improve how information is organized for findability. Use when the user asks to "organize this", "restructure docs", "improve navigation", "where should this go", "review file structure", struggles to place content, or when documentation grows beyond a single page.
npx claudepluginhub tslateman/claude-plugins --plugin duetThis skill uses the workspace's default tool permissions.
Information architecture is the structural design of shared information environments. When someone asks "where does this go?" or "I can't find anything" — that's an IA problem.
Guides strict Test-Driven Development (TDD): write failing tests first for features, bugfixes, refactors before any production code. Enforces red-green-refactor cycle.
Guides systematic root cause investigation for bugs, test failures, unexpected behavior, performance issues, and build failures before proposing fixes.
Guides A/B test setup with mandatory gates for hypothesis validation, metrics definition, sample size calculation, and execution readiness checks.
Information architecture is the structural design of shared information environments. When someone asks "where does this go?" or "I can't find anything" — that's an IA problem.
Grounded in Rosenfeld, Morville & Arango's Information Architecture (4th ed.) and the Diataxis documentation framework. See references/rosenfeld-morville.md for the core systems.
If someone can't find what they need, or you can't decide where something belongs, use this skill.
Every information space has four structural systems. Evaluate each when reviewing or designing.
How content is grouped and classified.
Exact schemes — unambiguous, mutually exclusive:
Ambiguous schemes — subjective, require judgment:
Rule: Choose one primary scheme per level. Mixing schemes at the same level confuses navigation.
When reviewing a project's organization, evaluate whether the taxonomy is sound:
Card sort heuristic: If three people disagree on where an item belongs, the categories are ambiguous. Rename or restructure until placement is obvious.
What things are called — the names users scan to orient themselves.
How people move through the space.
Depth rule: Three clicks (or three levels) to any content. If deeper, the hierarchy needs flattening or the content needs relocating.
How people find specific things without browsing.
signal-contract.md not doc-7.md)When the content is documentation, apply the Diataxis framework to classify pages:
| Mode | Orientation | Purpose | Form |
|---|---|---|---|
| Tutorial | Learning | Teach through doing | Lesson |
| How-to | Task | Solve a specific problem | Recipe |
| Explanation | Understanding | Clarify concepts | Discussion |
| Reference | Information | Describe the machinery | Austere, exact |
Each page serves one mode. Mixing tutorial prose into a reference page degrades both. When a page feels unfocused, it likely conflates two modes.
Inventory the information space:
For each system, ask:
| System | Question |
|---|---|
| Organization | Is the grouping scheme consistent at each level? |
| Labeling | Can a reader predict content from the label? |
| Navigation | Can someone reach any content in three steps? |
| Search | Do file names and headings match search terms? |
Structure output as:
## IA Review
### Structure Issues
- [Issue] — [Why it hurts findability] → [Recommended fix]
### Navigation Gaps
- [Missing path] — [Who needs it] → [Where to add it]
### Labeling Problems
- `[current label]` → `[better label]` — [Why]
### Content Gaps
- [Missing topic] — [Who needs it, when]
READMEs that accumulate everything eventually fail. When a README exceeds ~200 lines, extract:
docs/setup.md (how-to)docs/architecture.md (explanation)docs/api.md (reference)docs/tutorial.md (tutorial)The README becomes a signpost: project description, quick start, and links to the rest.
A docs/ with 20+ files at one level signals missing hierarchy. Group by topic or audience, not by creation date.
More than three directory levels for documentation means the taxonomy is too fine-grained. Flatten by merging related pages or promoting important content.
Content exists but nothing links to it. It might as well not exist. Every page needs at least one navigation path leading to it.
When deciding where new content goes:
/naming — IA labeling problems are naming problems/design — IA is structural design for information/prose — Clear writing makes content findable through scanningskills/FRAMEWORKS.md — Full framework index