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

> Learn how to track and triage bugs in your development pipeline with Claude Code Game Studios' unique gated system. Ensure critical defects are resolved before release.

- Repository: [Donchitos/Claude-Code-Game-Studios](https://github.com/Donchitos/Claude-Code-Game-Studios)
- Tags: how-to-guide
- Published: 2026-04-16

---

**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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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.

```markdown

# 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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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.

```bash

# 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.

```bash

# 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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/bug-report/SKILL.md) and [`.claude/skills/bug-triage/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.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`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/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.