Tech debt

While Claude works on one change, it often notices a real problem somewhere else: in a caller of the function it edited, in a test next to the file, in a page of the wiki. Fixing that problem in the same pull request would mix unrelated work into the change and make it harder to review. Ignoring it loses it. GAIA does neither: it records the problem as a tech-debt issue on GitHub, so it gets fixed later, on its own branch, with its own review.

This page covers how that debt is created. Two maintenance commands then work through it:

• /gaia-debt fixes tech-debt issues.
• /gaia-residue reviews the findings that were recorded without being filed, and turns the ones that matter into tech-debt issues.

Where each finding the audit raises ends up:

Where an audit finding ends up

Where debt comes from

Debt is found and filed as part of everyday work. The Code Audit Team reviews every pull request GAIA merges, so debt turns up while a SPEC’s plan runs, during an ad-hoc change, during a /gaia-debt fix, and during a dependency update that changes code. Some maintenance commands file it too, and you can ask for it at any time.

Source	What it files
The Code Audit Team	Problems a member finds outside the pull request’s own change, in a file it opened while reviewing it
The audit loop	The findings left open when you choose Stop and file the remainder at a branch checkpoint
/gaia-cleanse	Problems outside what it may change, such as an instruction file that contradicts the wiki
/gaia-wiki	Lint findings in files outside the wiki, which a wiki branch cannot change
/gaia-residue	A recorded residual you choose to Promote
You	Anything you ask for, such as “file this as tech-debt”

The audit only files problems in files it opened to review the change, such as a caller, a test, or an importer of something the change exports. It never searches the rest of the codebase for debt.

What gets recorded instead of filed

Not every finding outside the change becomes an issue. Two kinds are recorded in the pull request’s description instead, so the backlog does not fill with debt the change itself is about to touch again:

• Accepted residuals, under ## Accepted residuals (recorded, not fixed): findings in the change’s own scope that a reviewer accepted as a known trade-off instead of fixing.
• Waived findings, under ## Out-of-scope machinery findings (recorded, not filed): a non-security finding in GAIA’s own audit files (the scripts, hooks, and reviewer instructions that run the audit), or in a file the pull request already changes. Filing these would only re-surface the same finding on the next pull request that touches the file. A finding the change itself caused is never waived, and neither is one the change points to in a comment as “handled elsewhere”.

Both are residue. Each entry carries a key, so the same finding is not recorded twice. Once a residual is 30 days old, /gaia-residue asks you to dismiss it, keep it for later, or promote it to a tech-debt issue.

Why not file everything

A review that files every finding it sees quickly buries the backlog. The next pull request that touches the same file finds the same problem again, and the issue count grows faster than anyone can fix it. Once the backlog is too long to read, nobody reads it, and real problems hide among the noise.

Waiving and recording keep the backlog small enough to work through:

• The backlog holds only fixable work. A finding in a file the pull request already changes, or in GAIA’s own audit files, would come back on the next pull request that touches it. Waiving it breaks that loop instead of filing the same problem over and over.
• Each review stays about its change. Trade-offs inside the change are accepted with a reason instead of filed, so the review does not stall on a judgment call the author already made.
• Nothing is lost. Every waived or accepted finding is written into the pull request with a key. After 30 days, /gaia-residue puts each one back in front of you to dismiss, keep, or promote to an issue, so a trade-off that turned out to matter still gets fixed.

How an issue is filed

Every source files through the same file-tech-debt skill. You can trigger it yourself by asking Claude to file something as tech debt. It:

• Prevents duplicates. Each issue carries a hidden key naming the kind of finding, the file, and the line. A finding that already has an open issue, or one closed as not planned or labelled wontfix, is not filed again.
• Labels the issue with tech-debt, a severity, and a footprint (how much code the fix touches), plus a difficulty when the filer read the cited code. See Labels.
• Checks the issue before creating it. The labels and key are checked first. If they are badly formed, Claude corrects them before the issue is created, instead of leaving it for /gaia-debt to trip over later.
• Writes a self-contained body: the file and line, what goes wrong, and a suggested fix.

When GitHub has a temporary problem (a timeout or a rate limit), the finding is kept and retried on the next audit round. When there is no issue tracker to file to (no GitHub repository, gh not signed in, Issues turned off, or no write access), nothing is filed, and the run reports it.

Security findings

A security-sensitive finding (missing authentication, injection, an exposed secret, and the like) is filed only when the repository is private, checked twice, the second time just before the issue is created. Otherwise it is written to a local record with secrets removed, under .gaia/local/audit/security/, and you are told only how many there were and where the records are. When it is unclear whether a finding is security-sensitive, it is treated as if it is.

Note

An issue filed while the repository is private becomes public if you later make the repository public. Review your open tech-debt issues before you change its visibility.

Investigate issues

When a finding’s severity cannot be judged yet, it is filed as severity:investigate. The issue must state the open question and what would settle it. At most three can be open at once. When three are already open, Claude grades a new finding itself from the code instead of filing a fourth. /gaia-debt never offers an investigate issue until it has a real severity. To re-grade one, see /gaia-debt.

Working through the debt

• When tech-debt issues are open, the statusline shows 🐛 /gaia-debt (N issues). Run /gaia-debt to fix the most severe, oldest issues first, one issue or a batch of related ones per run.
• When 5 or more residuals are 30 days old, the statusline shows 🧹 /gaia-residue (N residuals). Run /gaia-residue to decide each one.
• When the same kind of finding keeps coming back, /gaia-codify proposes a guard so it stops recurring.