tmsjngx0/enrich

Enrich

Promote a lightweight future-iteration bead to a self-contained, implementation-ready description. Uses the bead-enricher agent to explore the codebase and generate full 6-layer descriptions.

When to Use

• Starting a new iteration: enrich the next batch of lightweight beads
• A previously-blocked task is now unblocked and ready to implement
• After /plan-decompose created lightweight future tasks

Usage

# Enrich a single bead
/enrich mindcontext-mgmt-nzas.3

# Enrich all ready (unblocked) future beads in an epic
/enrich --epic mindcontext-mgmt-nzas --ready

Step 1: Read the Bead

br show <bead-id>

Extract:

• Title
• Current (lightweight) description
• Labels (verify iteration:future is present)
• Dependencies (verify all blockers are resolved)

If the bead does NOT have iteration:future label:

⚠️ <bead-id> is not a lightweight bead. Already enriched?

Ask user to confirm before proceeding.

If the bead has unresolved blockers:

⚠️ <bead-id> has unresolved dependencies: <blocker-ids>
   Enrich anyway? (enriched description may be inaccurate)

Step 2: Launch Enricher Agent

Launch bead-enricher as a background agent with:

• Title: bead title
• Context: lightweight description + any parent epic context
• File hints: extract from lightweight description's "Rough Deliverables" if present

Use subagent_type: "mindcontext-core:bead-enricher" and run_in_background: true.

Wait for completion with TaskOutput(task_id, block=true, timeout=180000).

Step 3: Update the Bead

Parse the enricher output. If TDD mode (two beads returned with ---BEAD-SEPARATOR---):

1. Create a test bead:

br create "Test: <title>" -t task -p 1 \
  --parent <same-parent> \
  --labels "type:test" \
  -d "<test bead description>"

2. Update the original bead with enriched impl description:

br update <bead-id> -d "<enriched impl description>"
br label remove <bead-id> "iteration:future"
br label add <bead-id> "type:impl"
br dep add <bead-id> <test-bead-id>

3. Update priority from P3 to P2:

br update <bead-id> -p 2

4. Create a TIDY bead (Refactor phase):

Extract the test file path from the test bead description and the modified files from the impl description. Build the TIDY bead from this information — no enricher agent needed.

br create "Tidy: <title>" -t task -p 2 \
  --parent <same-parent> \
  --labels "type:tidy" \
  -d "## Tidy Bead (Refactor Phase)

**Implementation Bead ID**: <bead-id>
**Test Bead ID**: <test-bead-id>
**Test File**: \`<test-file-path>\`

This bead runs AFTER implementation passes tests.
After tidy, ALL existing tests MUST still pass.

---

## Goal
Review and clean up <title> implementation for code quality.

## Actions
1. Run \`/simplify\` on modified files
2. Check file size (< 200 lines warning, < 300 hard limit)
3. Check function size (< 20 lines warning, < 30 hard limit)
4. Check nesting depth (≤ 2 ideal, 3 warning, 4+ fix)
5. Run linter
6. Remove dead code, unused imports

## Exit Criteria
\`\`\`bash
<typecheck/compile/lint command from project context>
<test run command from impl bead exit criteria>
\`\`\`

### Checklist
- [ ] /simplify run on all modified files
- [ ] No file exceeds 300 lines
- [ ] No function exceeds 30 lines
- [ ] Linter passes with no new warnings
- [ ] All existing tests still pass"

5. Set TIDY dependency:

br dep add <tidy-bead-id> <bead-id>

Full TDD chain: TEST → IMPL → TIDY

If single bead (non-testable or skip-tdd):

1. Update the bead description:

br update <bead-id> -d "<enriched description>"
br label remove <bead-id> "iteration:future"

2. Add non-testable label:

br label add <bead-id> "no-test:<reason>"

Step 4: Report Result

✅ Enriched <bead-id>: <title>
   Description: lightweight → self-contained (<N> lines)
   Test bead: <test-bead-id> (if created)
   Tidy bead: <tidy-bead-id> (if created)
   Labels: iteration:future → type:impl
   Priority: P3 → P2
   Chain: TEST → IMPL → TIDY
   Ready: <yes/no>

--epic --ready Mode

When --epic <epic-id> --ready is provided:

1. List all beads under the epic with iteration:future label:

br list --parent <epic-id> --labels "iteration:future"

2. Filter to only those with no unresolved blockers (check deps)

3. Enrich each one sequentially (not parallel — enricher needs codebase context that may change between enrichments)

4. Report summary:

✅ Enriched <N> beads in <epic-id>:
   - <bead-1>: <title> (+ test <test-id> + tidy <tidy-id>)
   - <bead-2>: <title> (non-testable)
   Remaining lightweight: <M> beads

Important Notes

• Never run git push or br sync
• The enricher agent runs in background — main context preserved
• Enriched descriptions reflect CURRENT codebase state (not plan-time state)
• This is the key advantage over upfront decomposition: descriptions are always fresh