How to Track and Triage Bugs in the Development Pipeline: A Complete Guide for Claude Code Game Studios

The Claude Code Game Studios framework provides a gated, Markdown-based system where bugs flow through creation, triage, verification, and closure using slash commands like /bug-report and /bug-triage, ensuring critical defects cannot pass phase gates until resolved.

The Donchitos/Claude-Code-Game-Studios repository treats bugs as first-class artifacts that move through the same collaborative, gated pipeline as design and code. This article explains how to track and triage bugs in the development pipeline using the framework's built-in skills, automated quality gates, and human-in-the-loop decision points.

Creating Bug Reports with the /bug-report Skill

The bug-report skill transforms informal bug observations into auditable, structured documentation. Located at .claude/skills/bug-report/SKILL.md, this skill is invoked via the /bug-report slash command.

When executed, the skill prompts for:

• A concise description of the issue
• Step-by-step reproduction instructions
• Environment details (OS, engine version, build type)
• Initial severity assessment

The skill then writes a Markdown file to production/qa/bugs/[BUG-ID].md, assigning a unique identifier (e.g., BUG-001) that serves as the canonical reference throughout the development lifecycle.

# Bug Report: Crash on Boss Arena Entry

**ID:** BUG-001  
**Status:** Open  
**Severity:** High  
**Created:** 2024-01-15

## Description

Game crashes when the player enters the boss arena.

## Reproduction Steps

1. Load level "BossCave"
2. Press Start
3. Crash occurs

## Environment

- OS: Windows 10
- Engine: Godot 4.6
- Build: Debug

Automating Bug Triage with /bug-triage

Once created, bugs enter the triage queue managed by the bug-triage skill defined in .claude/skills/bug-triage/SKILL.md. The /bug-triage command scans all open bug files in production/qa/bugs/ and presents them in priority order to the QA lead or designated triage owner.

During triage, the skill updates the bug file's frontmatter with:

• Status: Triaged
• Priority: Critical, High, Medium, or Low
• Assignee: The developer or team responsible
• Target Sprint: The sprint milestone for resolution

This process ensures that every bug has clear ownership and timeline commitments before entering active development.

# Launch triage interface

/bug-triage

# Interactive output:

# Open Bugs:

#  • BUG-001 – Crash on boss arena (Severity: High, Owner: unassigned)

#  • BUG-002 – Texture flickering in menu (Severity: Low, Owner: unassigned)

#

# Select: BUG-001

# Set Severity: Critical

# Assign to: gameplay-programmer

# Target Sprint: sprint-03

#

# Result: Updates BUG-001.md headers with Status: Triaged, Priority: Critical, Assignee: gameplay-programmer

Verification and Closure Workflow

The framework enforces a rigorous verification step before bugs can be archived. Using /bug-report verify [BUG-ID], the system validates that:

• The fix has been merged into the main branch
• The bug file status is explicitly set to Verified Fixed
• A regression test has been added to prevent recurrence

Only after successful verification can the /bug-report close [BUG-ID] command execute. This generates a closure summary, archives the bug file, and updates release notes automatically.

# Verify the fix is complete and tested

/bug-report verify BUG-001
> Checking merge status... [OK]
> Checking status field... [Verified Fixed]
> Checking regression test... [Found: test_boss_arena_load]
> Output: "Bug VERIFIED-FIXED. Ready to close."

# Archive the bug

/bug-report close BUG-001
> Generated closure summary
> Archived to production/qa/bugs/archive/BUG-001.md
> Updated release notes

Integration with Phase Gates and Quality Controls

Bugs are deeply integrated into the framework's quality gates. Each /gate-check command runs a bug-audit sub-check that scans for any bugs marked as Blocking. If blocking bugs remain open, the gate returns FAIL, preventing the team from proceeding to the next development phase.

The control manifest and story-readiness checks automatically surface open bugs affecting a story's scope. According to docs/WORKFLOW-GUIDE.md, this ensures critical defects are never inadvertently missed during sprint planning or release preparation.

Additionally, the QA lead configuration in .claude/agents/qa-lead.md includes the bug-report skill in the default skill set, ensuring triage capabilities are always available to quality assurance personnel.

Summary

• Bug Creation: Use /bug-report to generate structured Markdown files in production/qa/bugs/ with unique identifiers and environment details.
• Triage Process: Execute /bug-triage to assign priority, owners, and sprint targets, updating headers in the bug files.
• Verification Gates: Require /bug-report verify to confirm fixes and regression tests before /bug-report close archives the bug.
• Pipeline Integration: Phase gates (/gate-check) automatically fail if Blocking bugs remain open, enforcing quality standards.
• Source Authority: All bug workflows are defined in .claude/skills/bug-report/SKILL.md and .claude/skills/bug-triage/SKILL.md.

Frequently Asked Questions

What file format does the Claude Code Game Studios bug tracker use?

The system uses Markdown files stored in production/qa/bugs/. Each bug is a separate .md file containing YAML frontmatter for metadata (ID, Status, Priority, Assignee) and Markdown sections for descriptions and reproduction steps. This approach makes bugs diffable, reviewable in pull requests, and portable across tools.

How do I prevent a release with critical bugs using the gate system?

The framework automatically prevents progression when Blocking bugs exist. When you run /gate-check, the system executes a bug-audit sub-check that scans all open bugs. If any bug has its severity marked as Blocking, the gate returns FAIL, halting the pipeline until the blocker is resolved and verified via /bug-report verify.

What is the difference between /bug-report and /bug-triage?

/bug-report is used to create, verify, and close individual bug artifacts. It handles the lifecycle of a single bug from initial documentation through archival. /bug-triage is a queue management command that presents all open bugs in priority order, allowing the QA lead to批量 set severity levels, assign owners, and schedule sprints across the entire backlog.

Where are bug reports stored in the repository?

Bug reports are stored in the production/qa/bugs/ directory as individual Markdown files named [BUG-ID].md (e.g., BUG-001.md). Once closed, bugs are typically archived to production/qa/bugs/archive/, maintaining a complete audit trail while keeping the active workspace clean.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}