majiayu000 Core principle: Track all work in bd, update as you go, never batch updates.
For basic operations: See skills/common-patterns/bd-commands.md (create, show, close, update)
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
- Create new tasks with correct structure
- Move work to new tasks
- Close old tasks with reference
- Don't delete (keep audit trail)
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
# 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
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
# 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
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
# 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
- Keep bd accurate → Single source of truth for all work
- Merge duplicates, don't just close → Preserve information from both
- Split large tasks when discovered → Not after struggling through
- Document dependency changes → Update task designs when deps change
- 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)
See: resources/task-naming-guide.md
- 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
- 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.
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.
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