<skill_overview> Advanced bd operations for managing complex task structures; bd is single source of truth, keep it accurate. </skill_overview>

<rigidity_level> HIGH FREEDOM - These are operational patterns, not rigid workflows. Adapt operations to your specific situation while following the core principles (keep bd accurate, merge don't delete, document changes). </rigidity_level>

<quick_reference>

Operation	When	Key Command
Split task	Task too large mid-flight	Create subtasks, add deps, close parent
Merge duplicates	Found duplicate tasks	Combine designs, move deps, close with reference
Change dependencies	Dependencies wrong/changed	bd dep remove then bd dep add
Archive epic	Epic complete, hide from views	bd close bd-X --reason "Archived"
Query metrics	Need status/velocity data	bd list + filters + wc -l
Cross-epic deps	Task depends on other epic	bd dep add works across epics
Bulk updates	Multiple tasks need same change	Loop with careful review first
Recover mistakes	Accidentally closed/wrong dep	bd update --status or bd dep remove

Core principle: Track all work in bd, update as you go, never batch updates. </quick_reference>

<when_to_use> Use this skill for advanced bd operations:

• Split task that's too large (discovered mid-implementation)
• Merge duplicate tasks
• Reorganize dependencies after work started
• Archive completed epics (hide from views, keep history)
• Query bd for metrics (velocity, progress, bottlenecks)
• Manage cross-epic dependencies
• Bulk status updates
• Recover from bd mistakes

For basic operations: See skills/common-patterns/bd-commands.md (create, show, close, update) </when_to_use>

<operations> ## Operation 1: Splitting Tasks Mid-Flight

When: Task in-progress but turns out too large.

Example: Started "Implement authentication" - realize it's 8+ hours of work across multiple areas.

Process:

Step 1: Create subtasks for remaining work

# Original task bd-5 is in-progress
# Already completed: Login form
# Remaining work gets split:

bd create "Auth API endpoints" --type task --priority P1 --design "
POST /api/login and POST /api/logout endpoints.
## Success Criteria
- [ ] POST /api/login validates credentials, returns JWT
- [ ] POST /api/logout invalidates token
- [ ] Tests pass
"
# Returns bd-12

bd create "Session management" --type task --priority P1 --design "
JWT token tracking and validation.
## Success Criteria
- [ ] JWT generated on login
- [ ] Tokens validated on protected routes
- [ ] Token expiration handled
- [ ] Tests pass
"
# Returns bd-13

bd create "Password hashing" --type task --priority P1 --design "
Secure password hashing with bcrypt.
## Success Criteria
- [ ] Passwords hashed before storage
- [ ] Hash verification on login
- [ ] Tests pass
"
# Returns bd-14

Step 2: Set up dependencies

# Password hashing must be done first
# API endpoints depend on password hashing
bd dep add bd-12 bd-14  # bd-12 depends on bd-14

# Session management depends on API endpoints
bd dep add bd-13 bd-12  # bd-13 depends on bd-12

# View tree
bd dep tree bd-5

Step 3: Update original task and close

bd edit bd-5 --design "
Implement user authentication.

## Status
✓ Login form completed (frontend)
✗ Remaining work split into subtasks:
  - bd-14: Password hashing (do first)
  - bd-12: Auth API endpoints (depends on bd-14)
  - bd-13: Session management (depends on bd-12)

## Success Criteria
- [x] Login form renders
- [ ] See subtasks for remaining criteria
"

bd close bd-5 --reason "Split into bd-12, bd-13, bd-14"

Step 4: Work on subtasks in order

bd ready  # Shows bd-14 (no dependencies)
bd update bd-14 --status in_progress
# Complete bd-14...
bd close bd-14

# Now bd-12 is unblocked
bd ready  # Shows bd-12

---

Operation 2: Merging Duplicate Tasks

When: Discovered two tasks are same thing.

Example:

bd-7: "Add email validation"
bd-9: "Validate user email addresses"
^ Duplicates

Step 1: Choose which to keep

Based on:

• Which has more complete design?
• Which has more work done?
• Which has more dependencies?

Example: Keep bd-7 (more complete)

Step 2: Merge designs

bd show bd-7
bd show bd-9

# Combine into bd-7
bd edit bd-7 --design "
Add email validation to user creation and update.

## Background
Originally tracked as bd-7 and bd-9 (now merged).

## Success Criteria
- [ ] Email validated on creation
- [ ] Email validated on update
- [ ] Rejects invalid formats
- [ ] Rejects empty strings
- [ ] Tests cover all cases

## Notes from bd-9
Need validation on update, not just creation.
"

Step 3: Move dependencies

# Check bd-9 dependencies
bd show bd-9

# If bd-10 depended on bd-9, update to bd-7
bd dep remove bd-10 bd-9
bd dep add bd-10 bd-7

Step 4: Close duplicate with reference

bd edit bd-9 --design "DUPLICATE: Merged into bd-7

This task was duplicate of bd-7. All work tracked there."

bd close bd-9

---

Operation 3: Changing Dependencies

When: Dependencies were wrong or requirements changed.

Example: bd-10 depends on bd-8 and bd-9, but bd-9 got merged and bd-10 now also needs bd-11.

# Remove obsolete dependency
bd dep remove bd-10 bd-9

# Add new dependency
bd dep add bd-10 bd-11

# Verify
bd dep tree bd-1  # If bd-10 in epic bd-1
bd show bd-10 | grep "Blocking"

Common scenarios:

• Discovered hidden dependency during implementation
• Requirements changed mid-flight
• Tasks reordered for better flow

---

Operation 4: Archiving Completed Epics

When: Epic complete, want to hide from default views but keep history.

# Verify all tasks closed
bd list --parent bd-1 --status open
# Output: [empty] = all closed

# Archive epic
bd close bd-1 --reason "Archived - completed Oct 2025"

# Won't show in open listings
bd list --status open  # bd-1 won't appear

# Still accessible
bd show bd-1  # Still shows full epic

Use archived for: Completed epics, shipped features, historical reference Use open/in-progress for: Active work Use closed with note for: Cancelled work (explain why)

---

Operation 5: Querying for Metrics

Velocity

# Tasks closed this week
bd list --status closed | grep "closed_at" | grep "2025-10-" | wc -l

# Tasks closed by epic
bd list --parent bd-1 --status closed | wc -l

Blocked vs Ready

# Ready to work on
bd ready
bd ready | grep "^bd-" | wc -l

# All open tasks
bd list --status open | wc -l

# Blocked = open - ready

Epic Progress

# Show tree
bd dep tree bd-1

# Total tasks in epic
bd list --parent bd-1 | grep "^bd-" | wc -l

# Completed tasks
bd list --parent bd-1 --status closed | grep "^bd-" | wc -l

# Percentage = (completed / total) * 100

For detailed metrics guidance: See resources/metrics-guide.md

---

Operation 6: Cross-Epic Dependencies

When: Task in one epic depends on task in different epic.

Example:

Epic bd-1: User Management
  - bd-10: User CRUD API

Epic bd-2: Order Management
  - bd-20: Order creation (needs user API)

# Add cross-epic dependency
bd dep add bd-20 bd-10
# bd-20 (in bd-2) depends on bd-10 (in bd-1)

# Check dependencies
bd show bd-20 | grep "Blocking"

# Check ready tasks
bd ready
# Won't show bd-20 until bd-10 closed

Best practices:

• Document cross-epic dependencies clearly
• Consider if epics should be merged
• Coordinate if different people own epics

---

Operation 7: Bulk Status Updates

When: Need to update multiple tasks.

Example: Mark all test tasks closed after suite complete.

# Get tasks
bd list --parent bd-1 --status open | grep "test:" > test-tasks.txt

# Review list
cat test-tasks.txt

# Update each
while read task_id; do
  bd close "$task_id"
done < test-tasks.txt

# Verify
bd list --parent bd-1 --status open | grep "test:"

Use bulk for:

• Marking completed work closed
• Reopening related tasks
• Updating priorities

Never bulk:

• Thoughtless changes
• Hiding problems (closing unfinished tasks)

---

Operation 8: Recovering from Mistakes

Accidentally closed task

bd update bd-15 --status open
# Or if was in progress
bd update bd-15 --status in_progress

Wrong dependency

bd dep remove bd-10 bd-8  # Remove wrong
bd dep add bd-10 bd-9     # Add correct

Undo design changes

# bd has no undo, restore from git
git log -p -- .beads/issues.jsonl | grep -A 50 "bd-10"
# Find previous version, copy

bd edit bd-10 --design "[paste previous]"

Epic structure wrong

1. Create new tasks with correct structure
2. Move work to new tasks
3. Close old tasks with reference
4. Don't delete (keep audit trail) </operations>

<examples> <example> <scenario>Developer closes duplicate without merging information</scenario> <code> # Found duplicates bd-7: "Add email validation" bd-9: "Validate user email addresses"

Developer just closes bd-9

bd close bd-9

Loses information from bd-9's design

bd-9 mentioned validation on update (bd-7 didn't)

Now that requirement is lost

Work on bd-7 completes, but misses update validation

Bug ships to production

</code>

<why_it_fails>

• Closed duplicate without reading its design
• Lost requirement mentioned only in duplicate
• Information not preserved
• Incomplete implementation ships
• bd not accurate source of truth </why_it_fails>

<correction> **Correct process:**

# Read BOTH tasks
bd show bd-7  # Only mentions validation on creation
bd show bd-9  # Mentions validation on update too

# Merge information
bd edit bd-7 --design "
Email validation for user creation and update.

## Background
Merged from bd-9.

## Success Criteria
- [ ] Validate on creation (from bd-7)
- [ ] Validate on update (from bd-9)  ← Preserved!
- [ ] Tests for both cases
"

# Then close duplicate with reference
bd edit bd-9 --design "DUPLICATE: Merged into bd-7"
bd close bd-9

What you gain:

• All requirements preserved
• bd remains accurate
• No information lost
• Complete implementation
• Audit trail clear </correction>

</example> <example> <scenario>Developer doesn't split large task, struggles through</scenario> <code> bd-15: "Implement payment processing" (started)

3 hours in, developer realizes:

- Need Stripe API integration (4 hours)

- Need payment validation (2 hours)

- Need retry logic (3 hours)

- Need receipt generation (2 hours)

Total: 11 more hours!

Developer thinks: "Too late to split, I'll power through"

Works 14 hours straight

Gets exhausted, makes mistakes

Ships buggy code

Has to fix in production

</code>

<why_it_fails>

• Didn't split when discovered size
• "Sunk cost" rationalization (already started)
• No clear stopping points
• Exhaustion leads to bugs
• Can't track progress granularly
• If interrupted, hard to resume </why_it_fails>

<correction> **Correct approach (split mid-flight):**

# 3 hours in, stop and split

bd edit bd-15 --design "
Implement payment processing.

## Status
✓ Completed: Payment form UI (3 hours)
✗ Split remaining work into subtasks:
  - bd-20: Stripe API integration
  - bd-21: Payment validation
  - bd-22: Retry logic
  - bd-23: Receipt generation
"

bd close bd-15 --reason "Split into bd-20, bd-21, bd-22, bd-23"

# Create subtasks with dependencies
bd create "Stripe API integration" ...  # bd-20
bd create "Payment validation" ...      # bd-21
bd create "Retry logic" ...             # bd-22
bd create "Receipt generation" ...      # bd-23

bd dep add bd-21 bd-20  # Validation needs API
bd dep add bd-22 bd-20  # Retry needs API
bd dep add bd-23 bd-22  # Receipts after retry works

# Work on one at a time
bd update bd-20 --status in_progress
# Complete bd-20 (4 hours)
bd close bd-20

# Take break
# Next day: bd-21

What you gain:

• Clear stopping points (can pause between tasks)
• Track progress granularly
• No exhaustion (spread over days)
• Better quality (not rushed)
• If interrupted, easy to resume
• Each subtask gets proper focus </correction>

</example> <example> <scenario>Developer adds dependency but doesn't update dependent task</scenario> <code> # Initial state bd-10: "Add user dashboard" (in progress) bd-15: "Add analytics to dashboard" (blocked on bd-10)

During bd-10 implementation, discover need for new API

bd create "Analytics API endpoints" ... # Creates bd-20

Add dependency

bd dep add bd-15 bd-20 # bd-15 now depends on bd-20 too

But bd-10 completes, closes

bd close bd-10

bd-15 shows as ready (bd-10 closed)

bd ready # Shows bd-15

Developer starts bd-15

bd update bd-15 --status in_progress

Immediately blocked - needs bd-20!

bd-20 not done yet

Have to stop work on bd-15

Time wasted

</code>

<why_it_fails>

• Added dependency but didn't document in bd-15
• bd-15's design doesn't mention bd-20 requirement
• Appears ready when not actually ready
• Wastes time starting work that's blocked
• Dependencies not obvious from task design </why_it_fails>

<correction> **Correct approach:**

# Create new API task
bd create "Analytics API endpoints" ...  # bd-20

# Add dependency
bd dep add bd-15 bd-20

# UPDATE bd-15 to document new requirement
bd edit bd-15 --design "
Add analytics to dashboard.

## Dependencies
- bd-10: User dashboard (completed)
- bd-20: Analytics API endpoints (NEW - discovered during bd-10)

## Success Criteria
- [ ] Integrate with analytics API (bd-20)
- [ ] Display charts on dashboard
- [ ] Tests pass
"

# Close bd-10
bd close bd-10

# Check ready
bd ready  # Does NOT show bd-15 (blocked on bd-20)

# Work on bd-20 first
bd update bd-20 --status in_progress
# Complete bd-20
bd close bd-20

# NOW bd-15 is truly ready
bd ready  # Shows bd-15

What you gain:

• Dependencies documented in task design
• Clear why task is blocked
• No false "ready" signals
• Work proceeds in correct order
• No wasted time starting blocked work </correction>

</example> </examples>

<critical_rules>

Rules That Have No Exceptions

1. Keep bd accurate → Single source of truth for all work
2. Merge duplicates, don't just close → Preserve information from both
3. Split large tasks when discovered → Not after struggling through
4. Document dependency changes → Update task designs when deps change
5. Update as you go → Never batch updates "for later"

Common Excuses

All of these mean: STOP. Follow the operation properly.

• "Task too complex to split" (Every task can be broken down)
• "Just close duplicate" (Merge first, preserve information)
• "Won't track this in bd" (All work tracked, no exceptions)
• "bd is out of date, update later" (Later never comes, update now)
• "This dependency doesn't matter" (Dependencies prevent blocking, they matter)
• "Too much overhead to split" (More overhead to fail huge task) </critical_rules>

<bd_best_practices> For detailed guidance on:

• Task naming conventions
• Priority guidelines (P0-P4)
• Task granularity
• Success criteria
• Dependency management

See: resources/task-naming-guide.md </bd_best_practices>

<red_flags> Watch for these patterns:

• Multiple in-progress tasks → Focus on one
• Tasks stuck in-progress for days → Blocked? Split it?
• Many open tasks, no dependencies → Prioritize!
• Epics with 20+ tasks → Too large, split epic
• Closed tasks, incomplete criteria → Not done, reopen </red_flags>

<verification_checklist> After advanced bd operations:

• bd still accurate (reflects reality)
• Dependencies correct (nothing blocked incorrectly)
• Duplicate information merged (not lost)
• Changes documented in task designs
• Ready tasks are actually unblocked
• Metrics queries return sensible numbers
• No orphaned tasks (all part of epics)

Can't check all boxes? Review operation and fix issues. </verification_checklist>

<integration> **This skill covers:** Advanced bd operations

For basic operations:

• skills/common-patterns/bd-commands.md

Related skills:

• hyperpowers:writing-plans (creating epics and tasks)
• hyperpowers:executing-plans (working through tasks)
• hyperpowers:verification-before-completion (closing tasks properly)

CRITICAL: Use bd CLI commands, never read .beads/issues.jsonl directly. </integration>

<resources> **Detailed guides:** - [Metrics guide (cycle time, WIP limits)](resources/metrics-guide.md) - [Task naming conventions](resources/task-naming-guide.md) - [Dependency patterns](resources/dependency-patterns.md)

When stuck:

• Task seems unsplittable → Ask user how to break it down
• Duplicates complex → Merge designs carefully, don't rush
• Dependencies tangled → Draw diagram, untangle systematically
• bd out of sync → Stop everything, update bd first </resources>