Bug Report

Port provenance: adapted from the pinned upstream source at 984023ddac0d5e27624f2baacde6105e45de375f under MIT; see the repository parity ledger for the exact path and blob.

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 text search and file discovery 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 production/qa/bugs/[BUG-ID].md. Extract the reproduction steps and expected result.

1. Re-run reproduction steps — use text search and file discovery 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 with the available shell 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 production/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 $ai-game-studio:hotfix [BUG-ID].

Phase 2D: Close Mode

Read production/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 $ai-game-studio: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-tester
**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 production/qa/bugs/[BUG-ID].md to mark it Closed?"

After closing, check production/qa/bug-triage-*.md — if the bug appears in an open triage report, note: "Bug [ID] is referenced in the triage report. Run $ai-game-studio: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 production/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 $ai-game-studio:bug-triage to prioritize alongside existing open bugs
• If S1 or S2: run $ai-game-studio:hotfix [BUG-ID] for emergency fix workflow

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

• Run $ai-game-studio: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 $ai-game-studio:bug-report close [BUG-ID] — write the closure record and update status
• Run $ai-game-studio:bug-triage to refresh the open bug count and remove it from the active list

Codex portability

Use the search, file-editing, shell, user-input, and subagent capabilities available in the active Codex surface. Use PowerShell syntax on Windows and POSIX syntax on macOS/Linux; do not require a Unix compatibility layer on Windows. Inherit the active model and permission mode, and do not weaken approval or sandbox boundaries.