Bug Triage

!bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys automation

Automation mode: Resolve modes.automation (project.local.yaml → project.yaml → default collaborative). Every AskUserQuestion call and every file write follows .claude/docs/automation-modes.md (collaborative asks always · guided major-only · autonomous logs and proceeds; automation_always_ask categories always prompt).

Bug Triage

This skill processes the open bug backlog into a prioritised, sprint-assigned action list. It distinguishes between severity (how bad is the impact?) and priority (how urgently must we fix it?), detects systemic trends, and ensures no critical bug is lost between sprints.

Output: production/qa/bug-triage-[date].md

When to run:

• Sprint start — assign open bugs to the new sprint or backlog
• After /team-qa completes and new bugs have been filed
• When the bug count crosses 10+ open items

1. Parse Arguments

Modes:

• /bug-triage sprint — triage against the current sprint; assign fixable bugs to the sprint backlog; defer the rest
• /bug-triage full — full triage of all bugs regardless of sprint scope
• /bug-triage trend — trend analysis only (no assignment); read-only report
• No argument — run sprint mode if a current sprint exists, else full mode

2. Load Bug Backlog

Step 2a — Discover bug files

Glob for bug reports in priority order:

1. production/qa/bugs/*.md — individual bug report files (preferred format)
2. production/qa/bugs.md — single consolidated bug log (fallback)
3. Any production/qa/qa-plan-*.md "Bugs Found" table (last resort)

If no bug files found:

"No bug files found in production/qa/bugs/. If bugs are tracked in a different location, adjust the glob pattern. If no bugs exist yet, there is nothing to triage."

Stop and report. Do not proceed if no bugs exist. Verdict: COMPLETE — no bug files in production/qa/bugs/; nothing to triage.

In trend mode, do not read full bug bodies. Trend metrics (volume, severity mix, by-system, by-date) are computable from the header fields alone:

Copy code
Grep pattern="\*\*(Severity|Priority|Status|System|Category|Reported)\*\*" glob="production/qa/bugs/*.md" output_mode="content"

(Bug-report fields are bolded — **Severity**:, - **System**: — so match the **field** form, not a bare line-start Field:.) Full bug bodies are needed only for the priority-vs-severity re-evaluation in sprint/full modes; trend is a read-only report and skips it. (The one deviation check that needs a story's status — "bug filed against a Complete story" — is a targeted story-status grep either way, not a bug-body read.)

Step 2b — Load sprint context

Read the most recently modified file in production/sprints/ to understand:

• Current sprint number / name
• Stories in scope (for assignment target)
• Sprint capacity constraints (if noted)

If no sprint file exists: note "No sprint plan found — assigning to backlog only."

Step 2c — Load severity reference

Read .claude/docs/coding-standards.md for severity/priority definitions if they exist. If they do not exist, use the standard definitions in Step 3.

3. Classify Each Bug

For each bug, extract or infer:

Severity (impact of the bug)

Priority (urgency of the fix)

Assignment

For each P1/P2 bug in sprint mode:

• Identify which story or epic the fix belongs to
• Check whether the current sprint has remaining capacity
• If capacity exists: assign to sprint (Sprint: [current])
• If capacity is full: flag as Priority overflow — consider pulling from sprint

For full mode: assign all P1 to current sprint, P2 to next sprint estimate, P3+ to backlog.

Deviation check

Flag bugs that suggest systematic problems:

• 3+ bugs from the same system in the same sprint → "Potential design or implementation quality issue in [system]"
• 2+ S1/S2 bugs in the same story → "Story may need to be reopened and re-reviewed before shipping"
• Bug filed against a story marked Complete → "Regression in completed story — story should be re-opened in sprint tracking"

4. Trend Analysis

After classifying all bugs, generate trend metrics:

Volume trends

• Total open bugs: [N]
• Opened this sprint: [N]
• Closed this sprint: [N]
• Net change: [+N / -N]

System hot spots

• Which system has the most open bugs?
• Which system has the highest S1/S2 ratio?

Age analysis

• How many bugs are older than 2 sprints?
• Are any S1/S2 bugs un-assigned (sprint = none)?

Regression indicator

• Any bugs filed against previously-completed stories?
• Count: [N] regression bugs (story reopened implied)

5. Generate Triage Report

markdownCopy code
# Bug Triage Report

> **Date**: [date]
> **Mode**: [sprint | full | trend]
> **Generated by**: /bug-triage
> **Open bugs processed**: [N]
> **Sprint in scope**: [sprint name, or "N/A"]

---

## Triage Summary

| Priority | Count | Notes |
|----------|-------|-------|
| P1 — Fix this sprint | [N] | [N] assigned to sprint, [N] overflow |
| P2 — Fix soon | [N] | Scheduled for next sprint |
| P3 — Backlog | [N] | Deferred |
| P4 — Won't fix | [N] | Accepted risk |

**Critical (S1/S2) unfixed count**: [N]

---

## P1 Bugs — Fix This Sprint

| ID | System | Severity | Summary | Assigned to | Story |
|----|--------|----------|---------|-------------|-------|
| BUG-NNNN | [system] | S[1-4] | [one-line description] | [sprint] | [story path] |

---

## P2 Bugs — Fix Soon

| ID | System | Severity | Summary | Target Sprint |
|----|--------|----------|---------|---------------|
| BUG-NNNN | [system] | S[1-4] | [one-line description] | Sprint [N+1] |

---

## P3/P4 Bugs — Backlog / Won't Fix

| ID | System | Severity | Summary | Disposition |
|----|--------|----------|---------|-------------|
| BUG-NNNN | [system] | S4 | [one-line description] | Backlog |

---

## Systemic Issues Flagged

[List any patterns from Step 3 deviation check, or "None identified."]

---

## Trend Analysis

**Volume**: [N] open / [+N] net change this sprint
**Hot spot**: [system with most bugs]
**Regressions**: [N] bugs against completed stories
**Aged bugs (>2 sprints old)**: [N]

[If N aged S1/S2 bugs > 0:]
> ⚠️ [N] high-severity bugs have been open for more than 2 sprints without
> assignment. These represent accepted risk that should be explicitly reviewed.

---

## Recommended Actions

1. [Most urgent action — usually "fix P1 bugs before QA hand-off"]
2. [Second action — usually "investigate [hot spot system] quality"]
3. [Third action — optional improvement]

6. Write and Gate

Present the report in conversation. If any bug is a P4 candidate, first ask "Are these acceptable as Won't Fix?" and keep its disposition P4 candidate until the user answers. Then ask:

"May I write this triage report to production/qa/bug-triage-[date].md?"

Write only after approval.

After writing:

• If any S1 bugs are unassigned: "S1 bugs must be assigned before the sprint can be considered healthy. Run /sprint-status to see current capacity."
• If regression bugs exist: "Regressions found — consider re-opening the affected stories in sprint tracking and running /smoke-check to re-gate."
• If no P1 bugs exist: "No P1 bugs — build is in good shape for QA hand-off."

Then, whether or not P1 bugs exist: Verdict: COMPLETE — triage report written.

If user declined write: Verdict: BLOCKED — user declined write.

Collaborative Protocol

• Never close or mark bugs Won't Fix without user approval — surface them as P4 candidates and ask: "Are these acceptable as Won't Fix?"
• Never auto-assign to a sprint at capacity — flag overflow and let the sprint owner decide what to pull
• Severity is objective; priority is a team decision — present severity classifications as recommendations, not mandates
• Trend data is informational — do not block work on trend findings alone; surface them as observations