ags-bug-triage

name	ags-bug-triage
description	Read all open bugs in .ags/project/qa/bugs/, re-evaluate priority vs. severity, assign to sprints, surface systemic trends, and produce a triage report. Run at sprint start or when the bug count grows enough to need re-prioritization.
argument-hint	[sprint | full | trend]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, Edit, AskUserQuestion

Language: Talk to user in language from .ags/project/user-interaction.md. Fall back to English if file missing. Files on disk always English per .ags/rules/user-interaction.md.

Bug Triage

Processes open bug backlog into prioritised, sprint-assigned action list. Distinguishes severity (impact?) from priority (urgency?), detects systemic trends, ensures no critical bug lost between sprints.

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

When to run:

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

---

0. Prerequisites

Artifact	Created by	If missing
.ags/project/bugs/ with ≥1 bug file	/ags-bug-report	STOP. "No bugs to triage. Run /ags-bug-report first."
Active epic in .ags/project/stage.md	/ags-create-epics	WARN: cannot map bugs to active epic.

If STOP triggers, exit verdict BLOCKED.

---

1. Parse Arguments

Modes:

• /ags-bug-triage sprint — triage against the current sprint; assign fixable bugs to the sprint backlog; defer the rest
• /ags-bug-triage full — full triage of all bugs regardless of sprint scope
• /ags-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. .ags/project/qa/bugs/*.md — individual bug report files (preferred format)
2. .ags/project/qa/bugs.md — single consolidated bug log (fallback)
3. Any .ags/project/qa/qa-plan-*.md "Bugs Found" table (last resort)

If no bug files found:

"No bug files found in .ags/project/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.

Step 2b — Load sprint context

Read the most recently modified file in .ags/project/epics/ 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 .ags/rules/coding.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)

Severity	Definition
S1 — Critical	Game crashes, data loss, or complete feature failure. Cannot proceed past this point.
S2 — High	Major feature broken but game is still playable. Significant wrong behaviour.
S3 — Medium	Feature degraded but a workaround exists. Minor wrong behaviour.
S4 — Low	Visual glitch, cosmetic issue, typo. No gameplay impact.

Priority (urgency of the fix)

Priority	Definition
P1 — Fix this sprint	Blocks QA, blocks release, or is regression from last sprint
P2 — Fix soon	Should be resolved before the next major milestone
P3 — Backlog	Would be good to fix, but no active blocking impact
P4 — Won't fix / Deferred	Accepted risk or out of scope for current product scope

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

# Bug Triage Report

> **Date**: [date]
> **Mode**: [sprint | full | trend]
> **Generated by**: /ags-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-NNN | [system] | S[1-4] | [one-line description] | [sprint] | [story path] |

---

## P2 Bugs — Fix Soon

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

---

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

| ID | System | Severity | Summary | Disposition |
|----|--------|----------|---------|-------------|
| BUG-NNN | [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, then ask:

"May I write this triage report to .ags/project/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 /ags-help to see current capacity."
• If regression bugs exist: "Regressions found — consider re-opening the affected stories in sprint tracking and running /ags-smoke-check to re-gate."
• If no P1 bugs exist: "No P1 bugs — build is in good shape for QA hand-off." Verdict: COMPLETE — triage report written.

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

---

Collaborative Protocol

• Never close or mark Won't Fix without user approval — surface as P4 candidates, ask confirmation
• Never auto-assign to sprint at capacity — flag overflow, let sprint owner decide
• Severity objective; priority is team decision — present severity as recommendations, not mandates
• Trend data informational — do not block work on trends alone; surface as observations