# issue-review (Unified Skill)

## Core Instructions (SKILL.md)

# Tracer-Bullet Issue Review (Rule of 5)

Review an issue set in five passes, with special attention to whether tickets are true tracer-bullet vertical slices.

## Setup

Read `references/setup.md` for tracker-specific collection commands before reviewing.

## Procedure

1. Gather the issue set to review plus the source plan/spec/parent issue when available.
2. Run the passes in order:
   - Pass 1: `references/pass-1-clarity.md`
   - Pass 2: `references/pass-2-scope.md`
   - Pass 3: `references/pass-3-dependencies.md`
   - Pass 4: `references/pass-4-alignment.md`
   - Pass 5: `references/pass-5-executability.md`
3. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`.
4. If converged, stop.
5. Produce the final report using `references/final-report.md`.

## Review Lens

Treat the best issue sets as:
- thin vertical slices rather than layer tickets
- independently verifiable or demoable
- minimal but sufficient dependency graphs
- explicit about AFK vs HITL work
- traceable back to stories, plans, or specs

## Rules

- Reference issue IDs precisely.
- Verify issue content before flagging a problem.
- Prioritize blockers over cosmetic cleanup.
- Suggest exact tracker edits or commands when practical.
- Call out horizontal decomposition explicitly: backend-only, schema-only, UI-only, or refactor-only tickets that should be folded into a tracer bullet.


---

## Reference: convergence.md

## Convergence Check

After each pass starting with pass 2, report:

```text
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]
```

Criteria:
- `CONVERGED`: no new CRITICAL issues, <10% new issues vs previous pass, <20% false positives
- `ITERATE`: continue
- `NEEDS_HUMAN`: blocking judgment call required


---

## Reference: final-report.md

## Final Report Template

```text
## Issue Tracker Review Final Report

System: [Beads/GitHub/Linear/Jira]
Scope: [All issues / Milestone / Label set]
Source: [Plan/spec/parent issue if known]

### Summary

Total Issues Reviewed: [count]

Issues Found by Severity:
- CRITICAL: [count]
- HIGH: [count]
- MEDIUM: [count]
- LOW: [count]

Convergence: Pass [N]

### Tracer-Bullet Assessment

- Slice quality: [Excellent|Good|Fair|Poor]
- Horizontal-ticket leakage: [None|Low|Moderate|High]
- AFK/HITL clarity: [Excellent|Good|Fair|Poor]

### Top 3 Most Critical Findings

1. [ID] [Finding]
   - Impact: [Why it blocks or degrades execution]
   - Fix: [Exact command or edit]

2. [ID] [Finding]
   - Impact: [Why it matters]
   - Fix: [Exact command or edit]

3. [ID] [Finding]
   - Impact: [Why it matters]
   - Fix: [Exact command or edit]

### Recommended Actions

- Provide exact tracker commands where practical.
- Collapse horizontal tickets into tracer bullets when possible.
- Include file paths, tests, and plan/story references when missing.

### Verdict

[READY_TO_WORK | NEEDS_UPDATES | NEEDS_REPLANNING]

Rationale: [1-2 sentences]

### Issue Quality Assessment

- Clarity: [Excellent|Good|Fair|Poor]
- Scope: [Excellent|Good|Fair|Poor]
- Dependencies: [Excellent|Good|Fair|Poor]
- Completeness: [Excellent|Good|Fair|Poor]
```


---

## Reference: pass-1-clarity.md

## Pass 1: Completeness and Clarity

Focus on:
- Clear title
- Sufficient context
- Concrete file paths and changes
- Success criteria or tests
- Unambiguous done criteria

Watch for:
- Vague titles
- Minimal descriptions
- "Implement X" without where or how
- Missing verification steps

Output:

```text
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]
```


---

## Reference: pass-2-scope.md

## Pass 2: Scope, Atomicity, and Tracer-Bullet Shape

Focus on:
- One logical capability per issue
- Thin vertical slices instead of horizontal layer tickets
- Issues small enough to finish in one focused session
- Clear boundaries with no overlap
- Independent demo or verification value

Watch for:
- Oversized epics disguised as issues
- Backend-only / schema-only / UI-only tickets that should be part of one slice
- Preparatory plumbing tickets with no standalone value
- Trivial issues that should be bundled into a slice
- Refactor + feature bundles with unclear boundaries

Questions to ask:
- If this issue lands alone, is anything real now possible or testable?
- Does it cut through the necessary layers for one outcome?
- Would splitting it by component create worse tickets?

Prefix findings with `SCOPE-`.


---

## Reference: pass-3-dependencies.md

## Pass 3: Dependencies and Ordering

Focus on:
- Correct dependency links
- Missing prerequisites
- Circular dependencies
- Avoidable serialization
- Sensible critical path
- Whether the issue graph reflects tracer bullets rather than phase gates

Watch for:
- Hidden blockers
- Cycles
- Artificial bottlenecks from horizontal decomposition
- Missing rationale for dependencies
- Tickets blocked only because the work was split by layer instead of by outcome

Questions to ask:
- Could these issues run in parallel if they were sliced vertically?
- Is a dependency real, or an artifact of poor decomposition?
- Are HITL issues isolated so AFK work can continue around them?

Prefix findings with `DEP-`.


---

## Reference: pass-4-alignment.md

## Pass 4: Plan, Story, and Spec Alignment

Focus on:
- Traceability to plan/spec sections or user stories
- Coverage of the intended workflow end-to-end
- Alignment between the chosen issue breakdown and the source material
- Explicit tests before implementation
- AFK/HITL classification when relevant

Watch for:
- Missing plan or story references
- Gaps where a user story is only partially covered across layer tickets
- Specs with no corresponding issue
- Issues that contradict the intended implementation approach
- Breakdown by phase/component when the source material describes user outcomes

Prefix findings with `ALIGN-`.


---

## Reference: pass-5-executability.md

## Pass 5: Executability and Handoff

Focus on:
- Can another developer or agent pick this up immediately?
- Are verification steps concrete and end-to-end?
- Are priorities and labels sensible?
- Are HITL handoff points explicit?
- Is it clear what demo, test, or observable behavior proves completion?

Watch for:
- Hidden conversational context
- "You know what to do"
- Missing verification commands or test references
- HITL work masquerading as AFK
- Tickets that cannot be closed without information from another issue not listed as a blocker

Prefix findings with `EXEC-`.


---

## Reference: setup.md

## Gathering Issues to Review

### Beads

```bash
bd list
bd ready
bd graph
bd show <id>
bd dep tree
bd dep cycles
```

### GitHub Issues

```bash
gh issue list --label "needs-review" --json number,title,body,labels
gh issue view <number>
```

### Other systems

- Export issues to JSON or CSV.
- Use available CLI or API tooling.
- Require issue data as input before reviewing.


---