ags-bug-report

name	ags-bug-report
description	Creates a structured bug report from a description, or analyzes code to identify potential bugs. Ensures every bug report has full reproduction steps, severity assessment, and context.
argument-hint	[description] | analyze [path-to-file]
user-invocable	true
allowed-tools	Read, Glob, Grep, Write, 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.

Phase 0: Prerequisites

Artifact	Created by	If missing
.ags/project/bugs/ directory	this skill (auto-create)	Auto-create — not a STOP.
CLAUDE.md	template	STOP. "Project not initialized. Run /ags-start."

If STOP triggers, exit verdict BLOCKED.

---

Phase 1: Parse Arguments

Determine the mode from the argument:

• No keyword → Description Mode: generate a structured bug report from the provided description
• analyze [path] → Analyze Mode: read the target file(s) and identify potential bugs
• verify [BUG-ID] → Verify Mode: confirm a reported fix actually resolved the bug
• close [BUG-ID] → Close Mode: mark a verified bug as closed with resolution record

If no argument is provided, ask the user for a bug description before proceeding.

---

Phase 2A: Description Mode

1. Parse the description for key information: what broke, when, how to reproduce it, and what the expected behavior is.

2. Search the codebase for related files using Grep/Glob to add context (affected system, likely files).

3. Draft the bug report:

# Bug Report

## Summary
**Title**: [Concise, descriptive title]
**ID**: BUG-[NNNN]
**Severity**: [S1-Critical / S2-Major / S3-Minor / S4-Trivial]
**Priority**: [P1-Immediate / P2-Next Sprint / P3-Backlog / P4-Wishlist]
**Status**: Open
**Reported**: [Date]
**Reporter**: [Name]

## Classification
- **Category**: [Gameplay / UI / Audio / Visual / Performance / Crash / Network]
- **System**: [Which game system is affected]
- **Frequency**: [Always / Often (>50%) / Sometimes (10-50%) / Rare (<10%)]
- **Regression**: [Yes/No/Unknown -- was this working before?]

## Environment
- **Build**: [Version or commit hash]
- **Platform**: [OS, hardware if relevant]
- **Scene/Level**: [Where in the game]
- **Game State**: [Relevant state -- inventory, quest progress, etc.]

## Reproduction Steps
**Preconditions**: [Required state before starting]

1. [Exact step 1]
2. [Exact step 2]
3. [Exact step 3]

**Expected Result**: [What should happen]
**Actual Result**: [What actually happens]

## Technical Context
- **Likely affected files**: [List of files based on codebase search]
- **Related systems**: [What other systems might be involved]
- **Possible root cause**: [If identifiable from the description]

## Evidence
- **Logs**: [Relevant log output if available]
- **Visual**: [Description of visual evidence]

## Related Issues
- [Links to related bugs or design documents]

## Notes
[Any additional context or observations]

---

Phase 2B: Analyze Mode

1. Read the target file(s) specified in the argument.

2. Identify potential bugs: null references, off-by-one errors, race conditions, unhandled edge cases, resource leaks, incorrect state transitions.

3. For each potential bug, generate a bug report using the template above, with the likely trigger scenario and recommended fix filled in.

---

Phase 2C: Verify Mode

Read .ags/project/qa/bugs/[BUG-ID].md. Extract the reproduction steps and expected result.

1. Re-run reproduction steps — use Grep/Glob to check whether the root cause code path still exists as described. If the fix removed or changed it, note the change.
2. Run the related test — if the bug's system has a test file in tests/, run it via Bash and report pass/fail.
3. Check for regression — grep the codebase for any new occurrence of the pattern that caused the bug.

Produce a verification verdict:

• VERIFIED FIXED — reproduction steps no longer produce the bug; related tests pass
• STILL PRESENT — bug reproduces as described; fix did not resolve the issue
• CANNOT VERIFY — automated checks inconclusive; manual playtest required

Ask: "May I update .ags/project/qa/bugs/[BUG-ID].md to set Status: Verified Fixed / Still Present / Cannot Verify?"

If STILL PRESENT: reopen the bug, set Status back to Open, and suggest re-running /ags-hotfix [BUG-ID].

---

Phase 2D: Close Mode

Read .ags/project/qa/bugs/[BUG-ID].md. Confirm Status is Verified Fixed before closing. If status is anything else, stop: "Bug [ID] must be Verified Fixed before it can be closed. Run /ags-bug-report verify [BUG-ID] first."

Append a closure record to the bug file:

## Closure Record
**Closed**: [date]
**Resolution**: Fixed — [one-line description of what was changed]
**Fix commit / PR**: [if known]
**Verified by**: qa-lead
**Closed by**: [user]
**Regression test**: [test file path, or "Manual verification"]
**Status**: Closed

Update the top-level **Status**: Open field to **Status**: Closed.

Ask: "May I update .ags/project/qa/bugs/[BUG-ID].md to mark it Closed?"

After closing, check .ags/project/qa/bug-triage-*.md — if the bug appears in an open triage report, note: "Bug [ID] is referenced in the triage report. Run /ags-bug-triage to refresh the open bug count."

---

Phase 3: Save Report

Present the completed bug report(s) to the user.

Ask: "May I write this to .ags/project/qa/bugs/BUG-[NNNN].md?"

If yes, write the file, creating the directory if needed. Verdict: COMPLETE — bug report filed.

If no, stop here. Verdict: BLOCKED — user declined write.

---

Phase 4: Next Steps

After saving, suggest based on mode:

After filing (Description/Analyze mode):

• Run /ags-bug-triage to prioritize alongside existing open bugs
• If S1 or S2: run /ags-hotfix [BUG-ID] for emergency fix workflow

After fixing the bug (developer confirms fix is in):

• Run /ags-bug-report verify [BUG-ID] — confirm the fix actually works before closing
• Never mark a bug closed without verification — a fix that doesn't verify is still Open

After verify returns VERIFIED FIXED:

• Run /ags-bug-report close [BUG-ID] — write the closure record and update status
• Run /ags-bug-triage to refresh the open bug count and remove it from the active list

---

Combined Review Loop (parallel external Codex)

Per .ags/rules/review-workflow.md. Authoring + internal review runs in parallel with external Codex inside one loop. Each iteration:

1. Resolve severity floor: iter 1-2 → keep all severities; iter 3-4 → critical/high; iter 5+ → critical only.
2. Persist current draft to .ags/project/reviews/.tmp/bug-report-[id]-iter[N]-draft.md.
3. Spawn in one message, in parallel:
   • All internal reviewer Tasks (qa-lead).
   • /ags-external-review custom [draft-path] --embedded-parallel --iteration [N] --min-severity [floor] — Codex unavailable returns skipped: codex-unavailable; aggregator logs skip in decisions-log and continues with internal pool only.
4. Aggregator (qa-lead) merges findings from internal + Codex, drops nitpicks + below-floor.
5. Loop exit: filtered set empty → proceed to write approval. Non-empty → surface aggregated kept findings, user revises draft, N++, repeat.

No iteration cap. No user-confirm gate before external — it runs every iteration automatically.