By name: issue-review description: Review issues for completeness and dependencies disable-model-invocation: true
Iterative Issue Tracker Review (Rule of 5)
Perform thorough issue review using the Rule of 5 - iterative refinement until convergence.
Setup
Gathering Issues to Review
For Beads:
bd list # All issues
bd ready # Unblocked issues
bd graph # Dependency visualization
bd show <id> # Individual issue details
bd dep tree # Dependency tree
bd dep cycles # Check for circular dependencies
For GitHub Issues:
gh issue list --label "needs-review" --json number,title,body,labels
gh issue view <number>
For other systems:
- Export issues to JSON/CSV
- Use API or CLI tools
- Provide issue data as input
Process
Perform 5 passes, each focusing on different aspects. After each pass (starting with pass 2), check for convergence.
PASS 1 - Completeness & Clarity
Focus on:
- Title clearly describes the work
- Description has enough context to implement
- File paths and changes are concrete (not vague)
- Success criteria or tests are defined
- No ambiguous or vague language
- Acceptance criteria clear
Output format:
PASS 1: Completeness & Clarity
Issues Found:
[CLRT-001] [CRITICAL|HIGH|MEDIUM|LOW] - Issue ID/Number
Title: [Issue title]
Description: [What's unclear or incomplete]
Evidence: [Why this is a problem]
Recommendation: [How to fix - specific command or action]
[CLRT-002] ...
What to look for:
- Vague titles: "Fix auth" (fix what?)
- No description or minimal description
- "Implement X" without saying how or where
- Missing file paths
- No verification steps
- Unclear done criteria
For Beads:
# Fix issues found
bd edit <id> description # Update description
bd update <id> --title="New clear title"
For GitHub:
gh issue edit <number> --title "New title"
gh issue edit <number> --body "New description"
PASS 2 - Scope & Atomicity
Focus on:
- Each issue represents one logical unit of work
- Issues not too large (should complete in one session)
- Issues not too small (trivial changes bundled appropriately)
- Clear boundaries between issues
- No overlapping scope between issues
- Each issue independently valuable
Prefix: SCOPE-001, SCOPE-002, etc.
What to look for:
- "Implement entire authentication system" (too large)
- "Fix typo in README line 42" (maybe too small, could bundle)
- Two issues both say "update user model"
- Issue requires changes across 10+ files
- Issue mixes refactoring with feature work
For Beads:
# Split large issues
bd create --title="Phase 1: ..." --description="..."
bd create --title="Phase 2: ..." --description="..."
bd dep add phase2-id phase1-id # phase2 depends on phase1
# Merge small issues
bd close small-issue-1 --reason="merged into main-issue"
bd update main-issue --description="Now includes work from small-issue-1"
PASS 3 - Dependencies & Ordering
Focus on:
- Dependencies correctly defined
- No missing dependencies (B needs A but not linked)
- No circular dependencies (A→B→C→A)
- Critical path is sensible
- Parallelizable work not falsely serialized
- Dependency rationale is clear
Prefix: DEP-001, DEP-002, etc.
What to look for:
- Issue requires another to be done but not linked
- Circular dependency chains
- Everything depends on one issue (bottleneck)
- No dependencies when clear order exists
- Dependencies prevent parallel work unnecessarily
For Beads:
# Check for problems
bd dep cycles # Find circular dependencies
bd dep tree # Visualize dependencies
# Fix dependencies
bd dep add <blocked-id> <blocker-id> # Add missing dependency
bd dep remove <blocked-id> <blocker-id> # Remove incorrect dependency
For GitHub:
# Use labels and issue references
gh issue edit <number> --add-label "blocked-by-#123"
# Or reference in description: "Depends on #123"
PASS 4 - Plan & Spec Alignment
Focus on:
- Issues trace back to plan phases
- Plan references in descriptions
- Related specs linked where applicable
- TDD approach clear (tests defined before impl)
- All plan phases have corresponding issues
- Issue breakdown matches plan structure
Prefix: ALIGN-001, ALIGN-002, etc.
What to look for:
- Plan has 5 phases but only 3 issues
- Issue doesn't reference source plan
- Plan says "test first" but issue doesn't mention tests
- Spec requirements not covered by any issue
- Issue contradicts plan approach
For Beads:
# Add plan reference
bd update <id> --description="...
Ref: plans/2026-01-12-feature.md#phase-2"
For GitHub:
gh issue edit <number> --body "...
Related Plan: `plans/2026-01-12-feature.md#phase-2`"
PASS 5 - Executability & Handoff
Focus on:
- Can be picked up by any developer/agent
- No implicit knowledge required
- Verification steps clear and specific
- Handoff points defined for multi-issue work
- Priority and labels appropriate
- Estimation realistic (if used)
Prefix: EXEC-001, EXEC-002, etc.
What to look for:
- "You know what to do" (no, they don't)
- Assumes knowledge of previous conversations
- "Test it" without saying how
- No verification steps
- Priority/labels missing or incorrect
Convergence Check
After each pass (starting with pass 2), report:
Convergence Check After Pass [N]:
1. New CRITICAL issues: [count]
2. Total new issues this pass: [count]
3. Total new issues previous pass: [count]
4. Estimated false positive rate: [percentage]
Status: [CONVERGED | ITERATE | NEEDS_HUMAN]
Convergence criteria:
- CONVERGED: No new CRITICAL, <10% new issues vs previous pass, <20% false positives
- ITERATE: Continue to next pass
- NEEDS_HUMAN: Found blocking issues requiring human judgment
If CONVERGED before Pass 5: Stop and report final findings.
Final Report
After convergence or completing all passes:
## Issue Tracker Review Final Report
**System:** [Beads/GitHub/Linear/Jira]
**Scope:** [All issues / Milestone X / Labels Y]
### Summary
Total Issues Reviewed: [count]
Issues Found by Severity:
- CRITICAL: [count] - Must fix before work starts
- HIGH: [count] - Should fix before work starts
- MEDIUM: [count] - Consider addressing
- LOW: [count] - Nice to have
Convergence: Pass [N]
### Top 3 Most Critical Findings
1. [DEP-001] Circular dependency detected
Issues: #42 → #43 → #44 → #42
Impact: Cannot start any of these issues
Fix: `bd dep remove 42 44` to break cycle
2. [SCOPE-002] Issue too large to complete
Issue: #38 "Implement authentication system"
Impact: Unmanageable scope, blocks other work
Fix: Split into 5 issues for each plan phase
3. [CLRT-003] Missing implementation details
Issue: #29 "Update API"
Impact: Cannot implement without more info
Fix: Add file paths, endpoints, and success criteria
### Recommended Actions
Provide specific commands for fixes:
**Beads Commands:**
```bash
# Fix circular dependency
bd dep remove 42 44
# Split large issue
bd create --title="Phase 1: Auth tokens" --description="..."
bd create --title="Phase 2: Auth middleware" --description="..."
bd dep add phase2-id phase1-id
bd close 38 --reason="split into phase issues"
# Update missing details
bd edit 29 description
# Then add: Files: api/routes.ts, api/handlers.ts; Tests: api/routes.test.ts
GitHub Commands:
gh issue edit 29 --body "...
Files to change:
- api/routes.ts
- api/handlers.ts
- api/routes.test.ts
Success criteria:
- [ ] Tests pass
- [ ] Endpoints return correct status codes"
Verdict
[READY_TO_WORK | NEEDS_UPDATES | NEEDS_REPLANNING]
Rationale: [1-2 sentences explaining the verdict]
Issue Quality Assessment
- Clarity: [Excellent|Good|Fair|Poor] - [brief comment]
- Scope: [Excellent|Good|Fair|Poor] - [brief comment]
- Dependencies: [Excellent|Good|Fair|Poor] - [brief comment]
- Completeness: [Excellent|Good|Fair|Poor] - [brief comment]
## Rules
1. **Reference specific issues** - Use issue IDs/numbers precisely
2. **Provide actionable commands** - Show exact commands to fix issues
3. **Check actual content** - Don't assume, verify with issue details
4. **Prioritize correctly**:
- CRITICAL: Blocks all work (circular deps, missing info)
- HIGH: Blocks specific work or causes confusion
- MEDIUM: Could be clearer but workable
- LOW: Minor improvements
5. **If converged before pass 5** - Stop and report