# issues (Unified Skill) ## Core Instructions (SKILL.md) #### Core Instructions (content/distilled/issues/SKILL.md) # Issues Router Route issue-tracking work to the right mode, then read that mode's instructions before acting. Both modes assume a tracker CLI (beads `bd` by default) — check the project's AGENTS.md for the tracker in use. ## Modes | Task signal | Mode | Read | |---|---|---| | turn an implementation plan into trackable issues | create-issues | `references/create-issues/SKILL.md` | | review existing issues for completeness, dependencies, executability | issue-review | `references/issue-review/SKILL.md` | ## Selection rules - Plan approved and needs to become work items → **create-issues**. - Issues exist and someone asks "are these ready/good/covered?" → **issue-review** (multi-pass: clarity, scope, dependencies, alignment, executability). - Creating issues from a plan that has not been reviewed? Suggest a plan review first. ## Procedure 1. Identify the mode from the table above. 2. Read the referenced file (resolve paths against this skill's directory); follow its templates, pass structure, and output format. --- #### Reference: references/create-issues/references/criteria.md # Issue Creation Criteria Use these criteria to evaluate whether a plan has been translated into strong tracer-bullet issues. ## High-Quality Issue Standards | Feature | Criteria | | :--- | :--- | | **Tracer-bullet shape** | Each issue is a thin vertical slice, not a horizontal layer ticket. | | **Independent value** | A completed issue is demoable, testable, or otherwise verifiable on its own. | | **Atomicity** | Each issue covers one logical capability. If it spans multiple unrelated behaviors, split it. | | **Actionable Title** | Short, specific, and domain-oriented. Prefer behavior over component names. | | **Traceability** | Contains a direct reference to the source plan/spec section or story. | | **Verifiability** | Acceptance criteria are binary and observable. | | **Quantified Must gate** | Hard acceptance criterion carries a unit and number (Planguage Must), never an adjective. | | **Machine-checkable Meter** | An exact runnable command (Meter) whose exit code decides the gate; verifiable at the ticket's `base_commit`. | | **Anti-goals** | Negative constraints name prohibited behaviors (test edits, dependency additions, API breaks) so agents can't cheat the gate. | | **Baseline anchored** | Measurable claims record the pre-work value and the HEAD SHA as `base_commit` metadata for staleness detection. | | **Dependency hygiene** | Only real blockers are encoded; parallel work is not serialized without reason. | | **Workflow Mandate** | Includes the mandatory TDD and Tidy First block. | | **Execution mode** | Slice is explicitly marked AFK or HITL. | ## Tracer-Bullet Heuristics Use these checks before publishing: - [ ] Does this issue deliver a narrow but complete path through relevant layers? - [ ] Could someone demo or verify this slice without waiting for a later ticket? - [ ] Is this a user-visible or system-verifiable outcome rather than plumbing-only work? - [ ] Could a fresh agent verify the Must gate by running the Meter command verbatim? - [ ] If the ticket is preparatory, is that preparatory work itself independently valuable? - [ ] Would splitting by backend/frontend/schema create worse horizontal tickets than the current slice? ## Dependency Reliability Checklist - [ ] All IDs captured from command output using variables. - [ ] Dependency commands reference the captured variables. - [ ] Blockers are real prerequisites, not just preferred order. - [ ] AFK/HITL designation is explicit. - [ ] Parallel work is left parallel where the tracker supports it. ## When to Stop & Ask - [ ] The plan is written as phases/layers only and cannot yet be sliced vertically. - [ ] Acceptance criteria are too vague to make binary. - [ ] File paths or impacted surfaces are unknown and need discovery. - [ ] The target tracker is not accessible via CLI/API. - [ ] Existing issues already cover part of the plan and would conflict with new tickets. - [ ] HITL slices need human approval before publishing. --- #### Reference: references/create-issues/references/templates.md # Issue Creation Templates Use these templates for proposed slice breakdowns, issue descriptions, and the final creation summary. ## Proposed Slice Review Template ```markdown 1. **[Title]** - **Type:** [AFK|HITL] - **Blocked by:** [None | Slice 1, Slice 2] - **User stories covered:** [Story A, Story B] - **Tracer-bullet rationale:** [Why this is a thin end-to-end slice] ``` ## Issue Description Template ```markdown ## Parent [Reference to parent plan/spec/issue, if applicable] ## What to build [Describe the end-to-end behavior of this slice in domain language.] **Context:** [Brief explanation tied to the source plan/spec] Ref: [Link to plan/spec file and section] **Files / Systems:** - `path/to/file1` - `path/to/file2` - `[subsystem or surface area if exact files are not yet known]` ## Verifiable Value Claim **Must (hard gate):** [Quantified threshold defining done, with unit and number — e.g. "P95 latency ≤ 250 ms at 100 req/sec"; never "fast" or "robust"] **Meter:** [Exact runnable command that verifies the Must gate — e.g. `pytest tests/val_claims/test_issue_NNN.py -q`; exit 0 = pass] **Baseline:** [Measured value before work starts — e.g. "P95 = 450 ms"; omit if not measurable] **Regression suite:** [Existing tests that must keep passing — e.g. `pytest tests/core/`] ## Acceptance Criteria - [ ] [Binary, observable criterion 1] - [ ] [Binary, observable criterion 2] - [ ] [Automated tests cover the slice end-to-end] - [ ] [When the slice creates source files or changes a file's contract: file-header criterion — new files carry Purpose/Responsibilities/Rationale; changed files update Rationale (see `file-headers`)] ## Blocked by - [Issue reference] Or: `None - can start immediately` --- **CRITICAL: Follow Test Driven Development and Tidy First workflows.** - Write tests *before* writing implementation code. - Clean up related code *before* adding new functionality. **Anti-goals (do NOT):** - [Prohibited behavior with obvious reward-hacking payoff — e.g. "modify, disable, or delete tests in `tests/core/`"] - [e.g. "add new dependencies or modify lockfiles"] - [e.g. "break public API / exported interfaces"] ``` ## Issue Creation Summary Template ```markdown ## Issue Creation Summary **System:** [e.g., GitHub/Beads] **Plan:** [path/to/plan.md] ### Approved Slice Set 1. **[Title]** — [AFK|HITL], blocked by [None|IDs] 2. **[Title]** — [AFK|HITL], blocked by [None|IDs] ### Summary - **Total Issues Created:** [count] - **Dependencies Defined:** [count] - **Labels Applied:** [e.g., needs-triage] - **Base Commit Anchored:** [git SHA recorded in `base_commit` metadata] ### Created Issues 1. **[ID] [Title]** - [Link/Reference] 2. **[ID] ...** ### Verdict: [ISSUES_CREATED | FAILED_TO_CREATE | WAITING_FOR_APPROVAL] **Rationale:** [1-2 sentences explaining the result] ``` --- #### Reference: references/create-issues/SKILL.md # Tracer-Bullet Issue Creation from Plan Break a reviewed plan into independently grabbable issues using tracer-bullet vertical slices. ## Role You are a Technical Project Manager. Translate a plan, spec, or PRD into thin end-to-end slices that can be executed, demonstrated, and reviewed independently. Preserve local workflow expectations like TDD and Tidy First. ## Procedure 1. **Gather context:** - Identify the source plan/spec. If none is provided, ask for it or list likely files. - Read it completely. - Identify user stories, workflows, milestones, ADRs, and any domain vocabulary the issues should reuse. 2. **Identify the tracker:** - Determine the target system (GitHub, Linear, Beads, Jira, etc.). - Check which CLI/API is available. - Confirm label vocabulary if the tracker uses triage labels. 3. **Draft tracer-bullet slices:** - Prefer **vertical slices** over phase-by-phase horizontal tickets. - Each issue should cut through all necessary layers for one narrow capability: storage/schema, business logic, interface, tests, and observability/docs when relevant. - A slice must be independently verifiable or demoable. - Mark each slice as: - **AFK** — can be implemented and merged without human intervention. - **HITL** — requires a human decision, approval, design review, copy review, policy signoff, etc. - Avoid tickets like “build backend”, “add UI”, or “refactor models first” unless the work is genuinely standalone. - **Title lint (hard rule — run on every drafted title before presenting):** a title must name a user-visible outcome (“CSV export works end-to-end”), not a layer. If a title names a layer or artifact — backend, frontend, API, route, button, serializer, schema, tests-only, docs-only, refactor-only — merge it into the outcome slice it serves. Layers differing is never sufficient reason to split: split by capability, never by layer. 4. **Review the proposed breakdown with the user:** - Re-run the title lint on every drafted title; merge any layer-named ticket into its outcome slice before presenting. - Present a numbered list before creating anything. - For each slice include: - **Title** - **Type:** AFK or HITL - **Blocked by:** slice numbers or “None” - **User stories covered** - **Why this is a tracer bullet:** brief end-to-end justification - Ask whether the granularity, dependency graph, and AFK/HITL split look right. - Iterate until approved. 5. **Prepare issue bodies:** - Use `references/templates.md`. - Every issue must include: - plan/spec traceability - end-to-end behavior description - concrete file paths or subsystems when knowable - binary acceptance criteria - a **file-header criterion** when the slice creates source files or changes a file's contract: new files open with `Purpose / Responsibilities / Rationale`; contract-changing edits update Rationale (see `file-headers`) - a **Verifiable Value Claim** where measurable: quantified **Must** gate (unit + number, no adjectives), a runnable **Meter** command, the measured **Baseline**, and the **regression suite** that must keep passing - **anti-goals** whenever the ticket touches tests, lockfiles, or public interfaces (prohibit test-assertion edits, dependency additions, API breaks) - explicit blocked-by field - TDD and Tidy First mandate 6. **Publish in dependency order:** - Create blockers first, then dependents. - Capture created IDs/URLs from stdout; never guess identifiers. - Apply tracker labels such as `needs-triage` when the project uses them. - Wire dependencies using actual captured identifiers or explicit body references. - Verify each creation step succeeded before continuing. - **After each successful creation**, extract the `**Files / Systems:**` bullet list from the issue description and store it as structured metadata together with a **base commit anchor** for staleness detection: ```bash base_sha=$(git rev-parse HEAD) bd update --metadata "{\"files\": [\"path/to/file1.py\", \"path/to/file2.py\"], \"base_commit\": \"$base_sha\"}" ``` `base_commit` is HEAD at ticket-creation time. Reviewers and claiming agents diff `base_commit..HEAD` against the ticket's `files` to detect out-of-date tickets (see `issue-review` skill, Pass 0 PRE-003, and `renew` skill **Claiming work** section). This enables automated file-conflict detection by concurrent agents. If the Files/Systems section is empty or contains only subsystem names without concrete paths, **stop and ask the user for specific file paths before publishing the ticket** — a ticket without concrete paths cannot participate in conflict detection and is incomplete. 7. **Final report:** - Summarize the approved slice set, created issues, labels, and dependency links. - Flag any deferred HITL items or unresolved ambiguity. ## Rules - **Tracer bullets first:** prefer many thin, complete slices over a few thick horizontal tickets. - **Independently valuable:** each issue should produce a testable behavior change, not just preparatory plumbing. - **Traceable:** reference the exact plan/spec section or story. - **Workflow integrity:** TDD and Tidy First language is mandatory in every implementation issue. - **No guessed IDs:** capture identifiers from actual command output. - **Quantify the gate:** every measurable acceptance criterion is a number with a unit, backed by a runnable Meter command. - **Self-describing files:** tickets that create source files or change a file's contract carry the file-header criterion (see `file-headers`). - **Name the cheats:** add anti-goals wherever the gate could be gamed (test edits, new deps, API breaks). - **Anchor staleness:** always record `base_commit` metadata at creation; never publish a ticket anchored to nothing. - **Stop and ask:** if the plan only supports horizontal decomposition, propose a vertical rewrite before publishing. ## References - **Templates:** `references/templates.md` - **Criteria:** `references/criteria.md` --- #### Reference: references/issue-review/references/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: references/issue-review/references/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: references/issue-review/references/pass-0-preflight.md # PASS 0: Pre-flight (Beads only) Run before all content passes. Mechanical checks that don't require reading issue bodies. **Check 1 — metadata.files coverage:** ```bash bd list --format json | python3 -c " import json, sys issues = json.load(sys.stdin) missing = [i['id'] for i in issues if not (i.get('metadata') or {}).get('files')] if missing: print('Missing metadata.files:', missing) " ``` Flag `[PRE-001] MEDIUM` for each ticket missing `metadata.files`. Fix: `bd update --set-metadata 'files=["path/to/file.py"]'` **Check 2 — shared-file architecture smell:** ```bash bd list --format json | python3 -c " import json, sys from collections import defaultdict issues = json.load(sys.stdin) owners = defaultdict(list) for i in issues: for f in (i.get('metadata') or {}).get('files', []): owners[f].append(i['id']) for f, ids in owners.items(): if len(ids) >= 3: print(f, '->', ids) " ``` Flag `[PRE-002] LOW` for any file claimed by 3+ open tickets. Recommendation: consider a decomposition ticket to split `` before these tickets run (see navari-a3cv pattern). If not decomposing now, add a co-modification note to all affected tickets. **Check 3 — stale base commit (freshness):** ```bash bd list --format json | python3 -c " import json, subprocess, sys issues = json.load(sys.stdin) head = subprocess.run(['git','rev-parse','HEAD'], capture_output=True, text=True).stdout.strip() for i in issues: meta = i.get('metadata') or {} base = meta.get('base_commit') if not base or base == head: continue files = meta.get('files') or [] changed = [] if files: changed = subprocess.run( ['git','diff','--name-only', f'{base}..HEAD', '--'] + files, capture_output=True, text=True).stdout.split() if changed: print(i['id'], 'STALE-TOUCHED', changed) else: print(i['id'], 'BEHIND-HEAD') " ``` Flag `[PRE-003] HIGH` for STALE-TOUCHED: files in the ticket's scope changed since `base_commit` — the description, acceptance criteria, or Meter may no longer apply. Flag `[PRE-004] LOW` for BEHIND-HEAD: repo moved but ticket files untouched — likely still valid, only re-anchor. Fix: re-validate the ticket content against the current tree, then re-anchor: ```bash sha=$(git rev-parse HEAD) bd update --metadata "{\"base_commit\": \"$sha\"}" ``` Tickets missing `base_commit` entirely: flag as part of PRE-001 remediation. **Prefix:** PRE-001, PRE-002, etc. --- #### Reference: references/issue-review/references/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: references/issue-review/references/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: references/issue-review/references/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: references/issue-review/references/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: references/issue-review/references/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? - Is there a machine-checkable Must gate (quantified, unit + number) backed by a runnable Meter command? - Are touched code files self-describing — Purpose/Responsibilities/Rationale header present and current (see `file-headers`)? - 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 - Qualitative acceptance criteria with no unit or threshold ("fast", "robust", "clean") — a Scale/Meter is missing - A Meter command that cannot run at the ticket's `base_commit` (stale claim) or that no fresh agent could execute verbatim - Missing anti-goals on tickets touching tests, lockfiles, or public interfaces (reward-hacking surface: nothing stops gaming the gate) - Tickets that create or reshape source files with no file-header acceptance criterion — undocumented files force every implementing agent to re-derive intent - No regression suite named (pass-to-pass coverage unspecified) - 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: references/issue-review/references/setup.md ## Gathering Issues to Review ### Beads ```bash bd list bd ready bd graph bd show bd dep tree bd dep cycles ``` ### GitHub Issues ```bash gh issue list --label "needs-review" --json number,title,body,labels gh issue view ``` ### Other systems - Export issues to JSON or CSV. - Use available CLI or API tooling. - Require issue data as input before reviewing. --- #### Reference: references/issue-review/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. For Beads trackers, run PASS 0 pre-flight checks first: `references/pass-0-preflight.md` 3. Run the content 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` 4. After each pass starting with pass 2, evaluate convergence using `references/convergence.md`. 5. If converged, stop. 6. 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 - self-describing: tickets that create or reshape source files carry the file-header criterion (see `file-headers`) — undocumented files force agents to re-derive intent - machine-verifiable value claims: quantified Must gate, runnable Meter, explicit anti-goals, and a `base_commit` anchor that reveals staleness ## 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.