/do-issue

name: do-issue
description: Implement issues (GitHub/GitLab/Bitbucket) using progressive analyze-specify-plan-implement workflow
usage: /do-issue <issue-number | issue-url | space-delimited-list> [--dry-run] [--from <step>] [--to <step>] [--scope auto|minor|medium|major]

Do Issue(s)

A progressive workflow for implementing issues from the detected git platform (GitHub, GitLab, or Bitbucket), following the attune pattern: **analyze** → **specify** → **plan** → **implement** → **validate** → **complete**

When To Use

Use this command when you need to:

• Implementing fixes for one or more issues (GitHub, GitLab, or Bitbucket)
• Progressive issue resolution with validation
• Addressing a particular issue or ticket that is referenced

When NOT To Use

• Simple changes that don't need the full workflow
• Work already completed through another sanctum command

Quick Reference

/do-issue 42                  # Full workflow for issue #42
/do-issue 42 --from plan      # Skip analysis/specify, start at planning
/do-issue 42 --to plan        # Stop after planning (dry run)
/do-issue 42 --scope minor    # Auto-skip steps for minor fixes
/do-issue 42 43 44            # Multiple issues with dependency analysis

Workflow Steps Overview

| Step | Purpose | Skip When | |------|---------|-----------| | **1. Analyze** | Fetch issue, understand requirements | Already familiar with issue | | **2. Specify** | Clarify acceptance criteria | Criteria are clear | | **3. Plan** | Break down into tasks, identify dependencies | Single obvious fix | | **4. Implement** | Apply code changes with TDD | Just need validation | | **5. Validate** | Run tests, quality gates | Already validated | | **6. Complete** | Update issue, create PR | Just needed implementation |

Intelligent Step-Skipping

The workflow auto-detects scope and suggests step-skipping:

**Minor scope** (typo fix, config change):

• Skip: Analyze, Specify, Plan
• Run: Implement → Validate → Complete

**Medium scope** (single feature, clear requirements):

• Skip: Specify (if criteria clear)
• Run: Analyze → Plan → Implement → Validate → Complete

**Major scope** (multi-file, complex requirements):

• Run all steps

# Detect scope automatically
/do-issue 42 --scope auto

# Override with explicit scope
/do-issue 42 --scope minor
/do-issue 42 --scope medium
/do-issue 42 --scope major

---

Step 1: Analyze (Discovery & Context)

**Purpose**: Understand the issue and gather all relevant context.

**Skip when**: You're already familiar with the issue (e.g., you just created it).

1.1 Fetch Issue Details

# GitHub
gh issue view ISSUE_NUMBER --json number,title,body,labels,state,assignees
gh issue view ISSUE_NUMBER --comments

# GitLab
glab issue view ISSUE_NUMBER

1.2 Understand Requirements

Extract from the issue:

• **Problem statement**: What's broken or missing?
• **Expected behavior**: What should happen?
• **Acceptance criteria**: How do we know it's fixed?
• **Related context**: Links, screenshots, error logs

1.3 Check Related Issues

# GitHub
gh issue list --search "related keywords" --json number,title
gh issue view ISSUE_NUMBER --json milestone,project

# GitLab
glab issue list --search "related keywords"
glab issue view ISSUE_NUMBER

1.4 Verify Finding Against Current HEAD (auto-promoted issues)

**Purpose**: Auto-promoted findings (labels `improvement:auto-promoted`, `source:discussion`) reference a PR-era state of the code. Later work often resolves the finding incidentally, leaving a phantom-open issue. Before implementing, confirm the finding is still outstanding.

A 2026-05 sweep of one such backlog found 8 of 11 issues already resolved: blindly "fixing" them would have added duplicate frontmatter, redundant tests, and a renamed-back field. Verify first.

For each issue, parse the `Where:` location from the body and check it against the working tree. The shared `plugins/abstract/scripts/finding_verifier.py` module does this (it also backs the promotion gate, so the gate and `/do-issue` agree on what "stale" means):

# Quick manual check: does the cited location still exist, and is the
# concern's signature still present?
WHERE="plugins/foo/skills/bar/SKILL.md:20-22"   # from the issue body
FILE="${WHERE%%:*}"
[ -e "$FILE" ] || echo "Location gone -- finding likely resolved by refactor"
rg -n "the concern's grep signature" "$FILE" || echo "Signature absent -- likely resolved"

Honest boundary: file existence is a high-precision staleness signal, but a present file does not prove the concern remains. Read the content to confirm. Classify each issue as:

• **outstanding**: implement it (continue to Step 2+)
• **already resolved**: comment with the file/line evidence and close;

do not implement

• **uncertain**: surface to the user, do not auto-close

**Step 1 Output**: Issue understanding, context gathered, and each auto-promoted finding classified outstanding / resolved / uncertain

---

Step 2: Specify (Clarify Requirements)

**Purpose**: Ensure acceptance criteria are clear and testable.

**Skip when**: Issue already has clear acceptance criteria in Given-When-Then format.

2.1 Extract Acceptance Criteria

If the issue has explicit criteria, extract them:

**Acceptance Criteria from Issue:**
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

2.2 Clarify Ambiguous Requirements

If criteria are unclear, add clarifying comments to the issue:

# GitHub
gh issue comment ISSUE_NUMBER --body "$(cat <<'EOF'
## Clarification Questions

Before implementing, I'd like to clarify:

1. **[Ambiguous point]**: Should this be X or Y?
2. **[Missing detail]**: What happens when Z?

Please confirm so I can proceed with the correct approach.
EOF
)"

2.3 Generate Testable Criteria

Convert vague requirements to testable acceptance criteria:

**Testable Acceptance Criteria:**
- [ ] Given [context], when [action], the