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

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

All technical debt items live in 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 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, 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 specifies that the skill must ask "May I write the re-prioritized register back to 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 (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 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, which maps /tech-debt → docs/tech-debt-register.md.

Code Examples

Sample Debt Register Entry

When approved, the skill writes entries to docs/tech-debt-register.md using this table format:

| 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

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

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

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.

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.

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