bug-to-pr

Files (2)

• SKILL.md
• counsel-protocol.md · reference/

SKILL.md (first lines)

# Bug-to-PR Pipeline v1.0 — End-to-End Bug Resolution

Orchestrate the full lifecycle from bug report to a reviewed, ready-to-merge fix PR. This skill chains existing tools and adds new capabilities between them. It mirrors the discipline of `/prd-to-pr` but every stage is purpose-built for debugging and fixing rather than building new features.

## When to Use This Skill

Activate when user:
- Says "bug to PR", "fix this bug", "debug and fix", "resolve this issue"
- Reports a bug and expects a delivered fix PR
- Pastes an error, stack trace, or reproduction steps and wants it resolved end-to-end

Do NOT activate for:
- New features → use `/prd-to-pr`
- PR review only → use `/pr-handoff-to-codex`
- Code simplification only → use `/simplify`
- Quick one-line fixes the user can obviously describe → just fix it directly

## Core Principles

**The Checklist Discipline**
Good software development is an art and a science. Think of it like modern aviation — the systems that have achieved true greatness use checklists religiously. Even a great pilot like Sully ran checklists before landing the plane and in decision-making. This pipeline is our checklist. Every stage runs. Every time. No exceptions.

**ALL 8 STAGES ARE MANDATORY**
No stage may be skipped, abbreviated, or "optimized away" regardless of perceived simplicity, time pressure, or context compaction. A "simple" bug still gets counsel review. A "small" fix still gets simplification. An "obvious" fix still gets Codex adversarial review. The stages exist because human judgment about what's "simple enough to skip" is unreliable — the checklist removes that failure mode. Bugs that look simple are the ones that cause regressions.

**Diagnosis Before Treatment**
Never jump to a fix. Reproduce first, diagnose second, plan third, implement fourth. The most dangerous bug fixes are the ones that "obviously" address the problem but actually treat a symptom.

**Minimal Fix, Maximum Confidence**
Bug fixes should be surgical. Change the minimum necessary to resolve the root cause. No "while we're here" refactoring, no scope creep. But testing must be expansive — cover the fix, the regression, and the blast radius.

**Claude Code for Implementation, Codex for Review**
Implementation uses Claude Code's multi-agent teams (TeamCreate, file ownership, wave execution). Review uses Codex's autonomous fix-apply-test loop.

**Opus 4.6 Everything**
All Claude Code agents run at Opus 4.6. No exceptions. No cost-saving downgrades.

## Pipeline Overview (8 Stages — ALL MANDATORY)

```
Stage 1: Bug Triage & Reproduction     → Interactive diagnosis + GitHub issue (MANDATORY)
Stage 2: Root Cause Analysis            → Systematic debugging with evidence (MANDATORY)
Stage 3: Fix Strategy Counsel           → Opus 4.6 + Codex 5.4 extra high adversarial review (MANDATORY)
Stage 4: Targeted Implementation        → Claude Code agent teams (MANDATORY)
Stage 5: Simplification Pass            → /simplify (MANDATORY)
Stage 6: Create PR + Codex Review       → /pr-handoff-to-codex (MANDATORY)
Stage 7: Copilot Feedback Review        → Check & apply GitHub Copilot suggestions (MANDATORY)
Stage 8: Self-Healing Deploy            → /self-healing-deploy (MANDATORY)
```

> **No-skip rule**: If context compaction occurs mid-pipeline, check pipeline state and resume from the next incomplete stage. If a stage can no longer run as designed, flag it to the user and adapt — but never silently skip it.

---

## Stage 1: Bug Triage & Reproduction

**Owned by**: this skill (bug-to-pr)

Before anything else, the bug must be understood and reproducible. No reproduction = no confidence in any fix.

### 1.1: Gather Bug Context

Use **AskUserQuestion** to collect:

1. **Symptoms**: What is the user observing? Error messages, unexpected behavior, crashes?
2. **Reproduction Steps**: How to trigger the bug? (If unknown, that's fine — we'll find them.)
3. **Environment**: Which environment? (`dev`, `staging`, `prod`). Which platform? (iOS, Backend, Both)
4. **Frequency**: Always, intermittent, or one-time?
5. **Severity**: Blocking, degraded, cosmetic?
6. **Recent Changes**: Did this start after a specific deploy or code change?
7. **Evidence**: Logs, stack traces, screenshots, error codes?

If the user already provided this information in their message, extract it — don't re-ask what's already known.

### 1.2: Scope Detection

Based on the symptoms and affected areas, detect scope:

| Signal | Scope |
|--------|-------|
| iOS crash, UI glitch, Swift error | `SCOPE_IOS` |
| API error, 500, backend log | `SCOPE_BACKEND` |
| Infrastructure, deploy, config | `SCOPE_GCP_INFRA` |
| "It works on iOS but the API returns wrong data" | `SCOPE_IOS` + `SCOPE_BACKEND` |

### 1.3: Reproduce the Bug

Based on scope, attempt reproduction:

**Backend bugs**:
```bash
# Check recent logs for the error
gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="<YOUR_SERVICE_NAME>" AND severity>=ERROR' \
  --limit=50 --format='table(timestamp,textPayload,jsonPayload.message)'

# Start local server and reproduce
dotnet run --project Infrastructure/<YOUR_API_PROJECT>/<YOUR_API_PROJECT>.GCP.csproj -- --urls http://localhost:7270

# Hit the affected endpoint
curl -v http://localhost:7270/{affected-endpoint}
```

**iOS bugs**:
```bash
# Build and check for compile-time issues
cd <YOUR_APP> && xcodebuild -project <YOUR_APP>.xcodeproj -scheme "<YOUR_APP> Dev" \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=latest' build 2>&1 \
  | python3 ../FULLSTACK_SCRIPTS/format-build-log.py

# Run existing tests to see if any already fail
cd <YOUR_APP> && xcodebuild test -project <YOUR_APP>.xcodeproj -scheme "<YOUR_APP> Dev" \
  -destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=latest' \
  -only-testing:<YOUR_APP>Tests/{RelevantTestClass} 2>&1 \
  | python3 ../FULLSTACK_SCRIPTS/format-build-log.py
```

**Cross-stack bugs**:
- Reproduce the backend component first (easier to isolate)
- Then verify the iOS client behavior matches expectations

From bzellman/earp-kit, MIT.

More from bzellman/earp-kit