# How to Create and Manage Technical Debt Tracking in Claude Code Game Studios

> Learn how to create and manage technical debt tracking for your projects using a centralized markdown register and explicit approval protocols at Claude Code Game Studios. Improve your workflow today.

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

---

**Claude Code Game Studios treats technical debt as a first-class artifact that is discovered, recorded, prioritized, and reported via the `/tech-debt` skill using a centralized markdown register and an explicit "May I write?" approval protocol.**

Technical debt tracking in the Donchitos/Claude-Code-Game-Studios repository follows a structured, collaborative workflow designed to prevent silent accumulation of legacy issues. The system centers on a single source of truth—the [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md) file—managed by a dedicated Claude skill that enforces user approval before any modifications. This approach ensures that every debt item is intentional, prioritized, and assigned to a specific owner and sprint.

## The Centralized Debt Register at [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md)

All technical debt items live in **[`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md)**, a markdown file created on-demand that serves as the project's single ledger. Each entry follows a structured table format with six required fields:

- **ID**: A short unique label (e.g., `TD-001`)
- **Severity**: Classified as `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`
- **Component**: The code path or system affected
- **Description**: Context explaining why the debt exists and any hard deadlines
- **Owner**: The person or sub-agent responsible for remediation
- **Target Sprint**: The sprint when repayment is scheduled

## Discovering Debt with the `/tech-debt` Skill

The **`/tech-debt` skill** defined in [`.claude/skills/tech-debt/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/tech-debt/SKILL.md) automates debt discovery by scanning the repository for common markers. Unlike passive comment detection, this skill actively identifies patterns that indicate architectural or code-level debt requiring eventual repayment.

### Scanning for FIXME, TODO, and Legacy Patterns

According to the skill specification, the scanner detects:

- `FIXME` comments (described as "bugs disguised as debt")
- `TODO` items with technical context
- Files containing legacy or prototype code identified through heuristics

The scan behavior is exercised and validated in the analysis test specification located at `CCGS Skill Testing Framework/skills/analysis/tech-debt.md`.

## The Collaborative Write Protocol

Claude Code Game Studios enforces a strict **"May I write ...?"** protocol before any file modification. Before appending new entries or updating existing rows in [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md), the skill prompts:

```

May I write these findings to `docs/tech-debt-register.md`?

```

This requirement aligns with **AN3 – No auto-write** from the `CCGS Skill Testing Framework/quality-rubric.md`, which explicitly forbids the skill from writing to the debt register without explicit user confirmation. The prompt appears at lines 45-59 of the skill specification file.

## Prioritizing and Reporting

Once captured, debt items require active management to prevent the register from becoming stale data.

### Re-prioritization Workflow

The skill supports re-prioritizing items based on severity, looming deadlines, or sprint capacity. Like initial discovery, this operation requires explicit approval. Line 77 of [`.claude/skills/tech-debt/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/tech-debt/SKILL.md) specifies that the skill must ask "May I write the re-prioritized register back to [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md)?" before overwriting the file.

### Read-Only Reporting Mode

For sprint planning and retrospectives, use `/tech-debt report` to generate a read-only summary. This mode outputs counts per severity level and trend analysis without modifying the filesystem, making it safe to run at the start of each sprint.

## Integration in the Development Workflow

Technical debt tracking is woven into the broader development lifecycle. The [`docs/WORKFLOW-GUIDE.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/WORKFLOW-GUIDE.md) (lines 801-928) explicitly mandates that debt discovered during reviews be logged to the register. Additionally, the **lead-programmer agent** defined in [`.claude/agents/lead-programmer.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/agents/lead-programmer.md) lists `tech-debt` among its core skills, ensuring architectural oversight includes debt management. The relationship between the skill and the register is visualized in [`docs/examples/skill-flow-diagrams.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/examples/skill-flow-diagrams.md), which maps `/tech-debt` → [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md).

## Code Examples

### Sample Debt Register Entry

When approved, the skill writes entries to [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md) using this table format:

```markdown
| ID   | Severity | Component               | Description                                   | Owner      | Target Sprint |
|------|----------|-------------------------|-----------------------------------------------|------------|---------------|
| TD-001 | HIGH   | src/gameplay/legacy_input.gd | Legacy input system prevents proper VR mapping. Refactor before VR release. | lead-programmer | Sprint 7 |

```

### Invoking the Skill Commands

```bash

# Scan the codebase and propose new debt items

/tech-debt scan

# Prioritize existing items by severity

/tech-debt prioritize --by severity

# Generate read-only report for sprint planning

/tech-debt report

```

### Sample Report Output

Running `/tech-debt report` produces output similar to:

```text
Technical Debt Summary (Sprint 6)
├─ HIGH: 3 items
├─ MEDIUM: 5 items
└─ LOW: 12 items
Trend: ↓ (debt reduced 15% vs previous sprint)

```

## Summary

- **Centralize** all technical debt in [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md) using a standardized table format with ID, Severity, Component, Description, Owner, and Target Sprint fields.
- **Discover** debt automatically using the `/tech-debt` skill, which scans for `FIXME`, `TODO`, and legacy code patterns as defined in [`.claude/skills/tech-debt/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/tech-debt/SKILL.md).
- **Collaborate** through the explicit "May I write ...?" protocol enforced by the AN3 quality rule, ensuring user approval before every file modification.
- **Prioritize** and re-prioritize items by severity or sprint capacity, again requiring explicit write confirmation.
- **Report** regularly using the read-only `/tech-debt report` command to track trends and inform sprint planning without risking data integrity.

## Frequently Asked Questions

### What file format does the technical debt register use?

The register uses a markdown table format stored in [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md). This allows human-readable editing while maintaining structure for parsing by the `/tech-debt` skill.

### How does the system prevent unauthorized automatic writes to the debt register?

The system implements the **AN3 – No auto-write** rule from `CCGS Skill Testing Framework/quality-rubric.md`. Every write operation requires the skill to prompt "May I write ...?" and receive explicit user approval before modifying [`docs/tech-debt-register.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/docs/tech-debt-register.md).

### What markers does the `/tech-debt` skill scan for?

The skill scans for `FIXME` comments (treated as bugs disguised as debt), `TODO` items with technical context, and files containing legacy or prototype code detected through heuristics, as specified in [`.claude/skills/tech-debt/SKILL.md`](https://github.com/Donchitos/Claude-Code-Game-Studios/blob/main/.claude/skills/tech-debt/SKILL.md).

### How is technical debt prioritized in Claude Code Game Studios?

Items are prioritized based on severity levels (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`), deadlines, and sprint capacity. The `/tech-debt prioritize` command reorders the register accordingly, but requires user confirmation via the "May I write ...?" prompt before committing changes.