information-architecture-beads
Skill19 starsChanged 6 days agoMITView on GitHub
Review information architecture and create Beads issues from the findings. Converts orphan screens, mislabeled navigation, and grouping problems into trackable Beads tasks with priorities and dependencies.
- Installs packages
In this repository67 other files it gives its agents.
- accessibility-precheckSkill
- cognitive-friction-detectorSkill
- cognitive-walkthrough-beadsSkill
- cognitive-walkthroughSkill
- conceptual-model-beadsSkill
- conceptual-modelSkill
- consistency-audit-beadsSkill
- consistency-auditSkill
- error-and-time-metrics-analyzerSkill
- failure-path-audit-beadsSkill
- failure-path-auditSkill
- field-study-plannerSkill
- heuristic-eval-beadsSkill
- heuristic-evalSkill
- high-fidelity-prototype-plannerSkill
- information-architectureSkill
- interaction-type-selectorSkill
- journey-map-beadsSkill
- journey-mapSkill
- low-fidelity-prototype-plannerSkill
- mental-model-checkerSkill
- persona-synthesizerSkill
- prototype-hci-pack-beadsSkill
- prototype-hci-packSkill
- representative-task-writerSkill
- satisfaction-questionnaire-writerSkill
- state-model-beadsSkill
- state-modelSkill
- task-analysis-writerSkill
- usability-test-plannerSkill
- vocabulary-audit-beadsSkill
- vocabulary-auditSkill
- wireframe-criticSkill
- accessibility-precheckSkill
- cognitive-friction-detectorSkill
- cognitive-walkthrough-beadsSkill
- cognitive-walkthroughSkill
- conceptual-model-beadsSkill
- conceptual-modelSkill
- consistency-audit-beadsSkill
- consistency-auditSkill
- error-and-time-metrics-analyzerSkill
- failure-path-audit-beadsSkill
- failure-path-auditSkill
- field-study-plannerSkill
- heuristic-eval-beadsSkill
- heuristic-evalSkill
- high-fidelity-prototype-plannerSkill
- information-architecture-beadsSkill
- information-architectureSkill
- interaction-type-selectorSkill
- journey-map-beadsSkill
- journey-mapSkill
- low-fidelity-prototype-plannerSkill
- mental-model-checkerSkill
- persona-synthesizerSkill
- prototype-hci-pack-beadsSkill
- prototype-hci-packSkill
- representative-task-writerSkill
- satisfaction-questionnaire-writerSkill
- The first 60 shown.
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 9 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 6
Run an Information Architecture Review on the current prototype, then create Beads issues from the findings so they become trackable tasks.
- Distinctive: line 18
Use ultrathink. Work from the repo, routes, navigation components, page layouts, menus, and any existing sitemap or docs.
- Very specific: line 21
Write docs/hci/information-architecture.md unless the user asked for another path.
- Distinctive: line 22
Create the directory if it does not exist.
- Distinctive: line 27
Create a hierarchical map of all screens, pages, or views in the system.
- Distinctive: line 52
Document how users move between screens:
- Distinctive: line 97
Create Mermaid diagrams for:
- Distinctive: line 113
If a user would need to memorize a path, the architecture has a problem.
- Very specific: line 128
Check if the bd CLI is available:
- Very specific: line 134
If
bdis not found: Stop here. Output the IA Review only, and append: - Distinctive: line 151
Check if the repo is already initialized:
- Very specific: line 157
If that fails (no .beads/ directory, not initialized):
- Very specific: line 163
Use --stealth so Beads metadata is not committed to the main repo.
- Distinctive: line 167
Create one parent issue to group all findings from this review:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Run an Information Architecture Review on the current prototype, then create Beads issues from the findings so they become trackable tasks.
This is an add-on to information-architecture. Run the full review first, produce the complete artifact, then pipe findings into Beads.
Phase 1: Run the Information Architecture Review
Define the information architecture for this scope:
$ARGUMENTS
Use ultrathink. Work from the repo, routes, navigation components, page layouts, menus, and any existing sitemap or docs. Infer missing structure conservatively and mark assumptions.
Output
Write docs/hci/information-architecture.md unless the user asked for another path.
Create the directory if it does not exist.
Required sections
1) Sitemap
Create a hierarchical map of all screens, pages, or views in the system.
Format as an indented list or Mermaid diagram:
Home
├── Dashboard
├── Projects
│ ├── Project List
│ ├── Project Detail
│ │ ├── Settings
│ │ ├── Members
│ │ └── Activity
│ └── Create Project
├── Settings
│ ├── Profile
│ ├── Notifications
│ └── Security
└── Admin
├── Users
└── SystemFor each node include: route/path, purpose, primary action.
2) Navigation model
Document how users move between screens: | Navigation element | Type (global nav, sidebar, breadcrumb, tab, link, button) | What it connects | Always visible? |
Identify:
- primary navigation (always visible)
- secondary navigation (contextual)
- tertiary navigation (in-page)
- escape hatches (how to get back/out)
3) Grouping analysis
For each group of items in the navigation or layout, answer:
- Why are these grouped together?
- Would a new user expect this grouping?
- Are there items that belong in a different group?
- Are there groups that should be split or merged?
| Group | Items | Grouping logic | Potential confusion |
4) Label audit
For every navigation label, page title, and section heading: | Label | What it actually leads to | Clear to new user? | Alternative label |
Flag:
- labels that are too vague ("Settings", "More", "Manage")
- labels that overlap ("Admin" vs "Settings" vs "Configuration")
- labels that use internal jargon
- labels that do not match the page content
5) Action placement
For each primary action in the system: | Action | Where it lives now | Where users would look for it | Mismatch? |
Check:
- Can the user find the action without hunting?
- Is it at the right level of the hierarchy?
- Is it near the objects it acts on?
- Are destructive actions separated from safe actions?
6) Depth and breadth analysis
- How deep is the deepest path? (clicks from home to leaf)
- How wide is the widest level? (items at the same level)
- Are there screens only reachable through non-obvious paths?
- Are there orphan screens with no navigation path?
Diagrams
Create Mermaid diagrams for:
- sitemap (tree structure)
- navigation flow (how screens connect)
Synthesis
End with:
- screens that are hard to find
- groupings that will confuse new users
- labels that need to change
- actions that are in the wrong place
- depth problems (too deep or too shallow)
- recommendations for restructuring
Quality bar
- Reference actual routes, file paths, and component names.
- The IA should make it obvious where everything lives and how to get there.
- If a user would need to memorize a path, the architecture has a problem.
Deliverable style
- Clear headings
- Markdown tables
- Mermaid diagrams where useful
- Direct language
- No filler
Phase 2: Beads Integration
Step 1 -- Detect Beads
Check if the bd CLI is available:
command -v bdIf bd is not found: Stop here. Output the IA Review only, and append:
## Beads Integration: Skipped
`bd` CLI not found. To install Beads and create trackable issues from this review:
pip install beads-cli
# or see https://github.com/steveyegge/beads
Then re-run: /information-architecture-beadsIf bd is found: Continue to Step 2.
Step 2 -- Initialize Beads (if needed)
Check if the repo is already initialized:
bd ready --jsonIf that fails (no .beads/ directory, not initialized):
bd init --stealthUse --stealth so Beads metadata is not committed to the main repo.
Step 3 -- Create parent issue
Create one parent issue to group all findings from this review:
bd create "IA Review: <branch> — <scope>" -p 1 --jsonCapture the parent issue ID from the JSON output. Store scope and summary:
bd update <parent-id> --description "<1-2 sentence scope summary>" --acceptance "<quality bar from the review>" --notes "Review date: <today>. Scope: <arguments>."Step 4 -- Create child issues per finding
For each finding (orphan screens, mislabeled navigation, deep paths, grouping problems):
MAJOR findings -- always create:
Orphan screens, inaccessible features, and misleading labels:
bd create "[MAJOR] <finding-title>" -p 0 --jsonMINOR findings -- create only if the user passed --include-minor. Otherwise skip and note them in the output.
Suboptimal grouping and slightly deep paths:
bd create "[MINOR] <finding-title>" -p 2 --jsonFor each created issue, update with structured fields (do NOT use bd edit):
bd update <child-id> --description "<what/why + evidence>" --notes "<location and context>" --acceptance "<fix recommendation or verification>"Then link child to parent:
bd dep add <child-id> <parent-id>Step 5 -- Show next actions
bd ready --jsonOutput
Return a combined report with two sections:
Section A: Information Architecture Review
- Sitemap
- Navigation model
- Grouping analysis
- Label audit
- Action placement
- Depth and breadth analysis
- Diagrams
- Synthesis and recommendations
Section B: Beads Integration Summary
- Status: initialized | already-initialized | skipped (with reason)
- Parent bead:
<id>--<title> - Created beads: table of Bead ID | Severity | Finding Title | Priority
- Skipped findings: list with reasons (e.g., "MINOR, --include-minor not set")
- Next actions: output of
bd ready --json
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

