Document merge command and AI duplicate detection workflow (bd-29)

- Add comprehensive merge command documentation to README.md
- Add AI agent duplicate detection workflow to AGENTS.md
- Include command syntax, examples, and best practices
- Close bd-29

Amp-Thread-ID: https://ampcode.com/threads/T-95a37593-fd67-4e99-bc84-ace580b4776d
Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
2025-10-22 11:48:12 -07:00
parent a7ce986555
commit 4ef995b0e4
3 changed files with 127 additions and 1 deletions

View File

@@ -445,6 +445,65 @@ bd rename-prefix kw-
bd list # Shows kw-* issues
```
### Merging Duplicate Issues
Consolidate duplicate issues into a single issue while preserving dependencies and references:
```bash
# Merge bd-42 and bd-43 into bd-41
bd merge bd-42 bd-43 --into bd-41
# Merge multiple duplicates at once
bd merge bd-10 bd-11 bd-12 --into bd-10
# Preview merge without making changes
bd merge bd-42 bd-43 --into bd-41 --dry-run
# JSON output
bd merge bd-42 bd-43 --into bd-41 --json
```
**What the merge command does:**
1. **Validates** all issues exist and prevents self-merge
2. **Closes** source issues with reason `Merged into bd-X`
3. **Migrates** all dependencies from source issues to target
4. **Updates** text references across all issue descriptions, notes, design, and acceptance criteria
**Example workflow:**
```bash
# You discover bd-42 and bd-43 are duplicates of bd-41
bd show bd-41 bd-42 bd-43
# Preview the merge
bd merge bd-42 bd-43 --into bd-41 --dry-run
# Execute the merge
bd merge bd-42 bd-43 --into bd-41
# ✓ Merged 2 issue(s) into bd-41
# Verify the result
bd show bd-41 # Now has dependencies from bd-42 and bd-43
bd dep tree bd-41 # Shows unified dependency tree
```
**Important notes:**
- Source issues are permanently closed (status: `closed`)
- All dependencies pointing to source issues are redirected to target
- Text references like "see bd-42" are automatically rewritten to "see bd-41"
- Operation cannot be undone (but git history preserves the original state)
- Not yet supported in daemon mode (use `--no-daemon` flag)
**AI Agent Workflow:**
When agents discover duplicate issues, they should:
1. Search for similar issues: `bd list --json | grep "similar text"`
2. Compare issue details: `bd show bd-41 bd-42 --json`
3. Merge duplicates: `bd merge bd-42 --into bd-41`
4. File a discovered-from issue if needed: `bd create "Found duplicates during bd-X" --deps discovered-from:bd-X`
See [AGENTS.md](#ai-agent-integration) for complete AI integration workflow.
### Labels
Add flexible metadata to issues for filtering and organization: