/file-tech-debt

name: file-tech-debt
description: Files a new tech-debt GitHub issue for an out-of-scope code-review finding. Builds the dedup key, skips an open or declined-closed match, else creates the labeled issue and touches the debt-count sentinel. Trigger on asks like "file a tech-debt issue", "record this as tech-debt", "file this finding as debt". Do NOT trigger on draining, fixing, listing, or prioritizing existing debt (that's `/gaia-debt`), nor on general "clean up the code" or "fix this bug" asks that aren't about filing a new tracked issue.

File a tech-debt issue

This skill is the single source of truth for turning one out-of-scope finding (a real problem spotted while reviewing something else, and therefore not fixed in place) into a durable, deduplicated GitHub issue. It covers building the key, checking for a prior match, filing when there is none, and nudging the debt-count display to refresh. It does not decide *which* findings are out-of-scope, does not fix anything, and takes the caller's word on whether a finding is security-sensitive (section 0), it only files.

**Callers own their own bookkeeping around this recipe.** Some callers record their own disposition-ledger entry and gate their own downstream state on it after filing succeeds; others file and stop. That bookkeeping is caller-specific and lives in the caller, not here. Follow the steps below exactly as written; do not invent a bookkeeping record, a completion flag, or a run-tracking step of your own on top of them, that would duplicate (or fight with) whatever the caller already does.

Contents: 0. Run the filing script; 1. Build the dedup key; 2. Check for an existing match (dedup); 3. Idempotency: skip if a match exists; 4. Otherwise, file the issue; 5. Issue body schema; 6. Labels; 7. Difficulty grade; 8. Touch the debt-count staleness sentinel.

0. Run the filing script

Every caller files through the script and never runs `gh issue create` itself:

bash .gaia/scripts/file-tech-debt.sh file --finding <finding.json> --outcome-file <outcome.jsonl> [--repo <owner/name>] [--disposition file|divert]

<!-- gaia:maintainer-only:start --> GAIA maintainers: before filing a finding on a harness path, Read `.claude/maintainers/harness-triage-threshold.md`; one it waives is never filed, only listed under `## Waived below triage threshold (not filed)` in the PR body. <!-- gaia:maintainer-only:end -->

Execute it; do not read it for the mechanics. Its header owns the outcome line, the stdout words, the exit codes, the screened fields (`security`, `severity`, `finding_class`) and the label fields (the difficulty grade rides in `grade`, never `difficulty`); the `file` branch also requires non-empty `member`, `path`, `line`, `title`, `failure_mode` and `suggested_fix`. Steps 1 to 8 below are the reference the script implements, for a caller that needs to understand a filing or a label rather than reproduce one.

The caller owns one judgment: the finding's boolean `security` flag, true when the content reads as an exploitable weakness (missing authentication or authorization, injection, secret exposure, SSRF, path traversal, unsafe deserialization, crypto misuse). Everything else is mechanical and fails safe toward diverting:

• **Security first.** A security-class finding (flag true, absent or non-boolean; severity `critical`; secret-shaped text; an absent or malformed `finding_class`) never reaches a public or internal issue. It files only when repository visibility reads exactly `PRIVATE` before the probe and again immediately before the first write. Any other answer, including a failed read, writes a redacted record under `.gaia/local/audit/security/` and reports a count and that path, nothing more. `holistic/unclassified` is a valid class and never a trigger.
• **Authorship.** A finding that is not security-class and whose site this branch wrote is refused with outcome `refused-authored`: no issue is created, and the two routes are to fix it on the branch or record it as an accepted residual. The script's header owns the stdout words and exits.
• **Backend probe.** `absent` (no repository, unauthenticated, Issues disabled, no write permission) files nothing and records outcome `absent`. `transient` (timeout, rate limit, 5xx) files nothing, records outcome `transient`, and keeps the finding in a retry directory beside the outcome file for the next round. `present` goes on to dedup and filing.
• **A match is not a filing.** When dedup (step 2) finds an issue already carrying the finding, the script creates nothing, prints `matched <n>` and records outcome `matched`. Report it as already tracked by `#<n>`, never as a new issue.
• **Verify after filing.** The script re-reads the created issue by number and records `failed` when its body lacks the wrapped key.
• **An investigate grade.** Set `severity` to `investigate` and add two non-empty strings, `investigate_question` and `investigate_settled_by` (step 5 says what each must say). The script writes the research block from them, refuses the filing by name when either is empty or when either is set on another grade, and refuses it as `failed investigate-cap` when the open investigate queue is full, with the check's report on stderr naming the open investigations to resolve instead.

Honest limits: an issue filed while the repository is PRIVATE becomes public if its visibility later flips, and a caller that sets `security` to false on a real weakness defeats the flag, which is why the severity and content triggers sit beside it.

1. Build the dedup key

Every filed issue's body carries exactly one dedup-key line: a single HTML comment, byte-for-byte in this form:

<!-- gaia-debt-key: v1 class=<finding_class> path=<repo-relative-posix-path> line=<integer> -->

• `v1` is the schema version. Bump it only for a breaking change to the key's shape, not for routine use.
• `<finding_class>` is the finding's seeded class, or `holistic/unclassified` when th