vocabulary-audit-beads

name	vocabulary-audit-beads
description	Audit UI terminology and create Beads issues from the findings. Converts terminology drift, overloaded terms, and vague labels into trackable Beads tasks with priorities and dependencies.
argument-hint	[scope] [--include-minor]
disable-model-invocation	true

Run a Vocabulary Audit on the current prototype, then create Beads issues from the findings so they become trackable tasks.

This is an add-on to vocabulary-audit. Run the full audit first, produce the complete artifact, then pipe findings into Beads.

---

Phase 1: Run the Vocabulary Audit

Audit and normalize interface language for this scope:

$ARGUMENTS

Use ultrathink. Use the current prototype, components, routes, docs, and visible copy. Extract all important terms that affect understanding.

Output

Write docs/hci/glossary.md unless the user asked for another path. Create the directory if it does not exist.

Required sections

1. Canonical glossary
2. Terms to merge or ban
3. Status vocabulary
4. Action vocabulary
5. Naming problems and recommendations

Tables to include

Canonical terms

| Term | Type (noun/verb/status) | Exact meaning | Where used | Notes |

Terms to avoid

| Avoid this term | Use instead | Reason |

Status model

| Status | Meaning | Entered when | Exited when |

What to look for

• same concept with multiple names
• vague verbs like "handle", "manage", "process"
• inconsistent status labels
• labels that require domain knowledge the user may not have
• UI copy that does not match the underlying conceptual model

Synthesis

End with:

• the five most damaging terminology inconsistencies
• concepts that are overloaded or ambiguous across the system
• priority terms to standardize before next implementation cycle

Quality bar

Prefer language that is:

• concrete
• consistent
• distinguishable from nearby concepts
• aligned with the user's mental model

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 bd

If bd is not found: Stop here. Output the Vocabulary Audit 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: /vocabulary-audit-beads

If bd is found: Continue to Step 2.

Step 2 -- Initialize Beads (if needed)

Check if the repo is already initialized:

bd ready --json

If that fails (no .beads/ directory, not initialized):

bd init --stealth

Use --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 audit:

bd create "Vocabulary Audit: <branch> — <scope>" -p 1 --json

Capture 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 (terminology drift, overloaded terms, vague labels):

MAJOR findings -- always create:

Same concept with multiple names causing confusion, and vague critical labels:

bd create "[MAJOR] <finding-title>" -p 0 --json

MINOR findings -- create only if the user passed --include-minor. Otherwise skip and note them in the output.

Minor label inconsistencies and jargon that could be simplified:

bd create "[MINOR] <finding-title>" -p 2 --json

For 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 --json

---

Output

Return a combined report with two sections:

Section A: Vocabulary Audit

1. Canonical glossary
2. Terms to merge or ban
3. Status vocabulary
4. Action vocabulary
5. Naming problems and recommendations
6. Synthesis

Section B: Beads Integration Summary

1. Status: initialized | already-initialized | skipped (with reason)
2. Parent bead: <id> -- <title>
3. Created beads: table of Bead ID | Severity | Finding Title | Priority
4. Skipped findings: list with reasons (e.g., "MINOR, --include-minor not set")
5. Next actions: output of bd ready --json