Tech debt fix

Tech Debt Fix

Overview

This skill reads a findings.md produced by tech-debt-audit and orchestrates fixes. It does NOT fix everything — the senior-engineer persona it adopts is deliberate about what gets auto-applied, what requires per-finding consent, and what it refuses to touch without a human.

The skill:

1. Asks the user whether to modify code directly or produce patches only.
2. Groups findings so no two groups touch the same file — enabling safe parallelism.
3. Dispatches fixes per group: a sub-agent per group (if the harness supports sub-agents), or sequential processing.
4. Creates one branch per group.
5. Opens a PR per group.
6. Never merges.

When to Use

Trigger on any of:

• User chose "fix" after the audit finished (path 2 from the audit skill summary).
• User directly invokes this skill pointing at an existing findings.md.
• User has picked this skill explicitly from the using-tech-debt-skills router.

Do NOT use this skill when:

• findings.md does not exist or doesn't conform to the schema — run tech-debt-audit first.
• The user is just reviewing findings — use the audit skill's output directly, or tech-debt-tickets.
• The repo has uncommitted changes and the user hasn't stashed/committed them. Stop and ask — the first thing this skill does is branch, and dirty working trees produce surprising branches.

Persona Adopted

This skill adopts the senior-engineer persona defined at agents/senior-engineer/SKILL.md. Read that file before proceeding. The persona's Process Discipline, Red Flags, and When-to-Decline rules are binding.

If the harness supports sub-agents: the senior-engineer stays at the top level and dispatches per-group implementers (adopting the senior-engineer persona within a narrow group scope). See docs/harness-compatibility.md for which harnesses support this.

If the harness does not support sub-agents: the senior-engineer processes groups sequentially, one group at a time, still one branch per group.

Hard Guardrails (non-negotiable)

Before any fix work begins, internalize these. They apply regardless of user instruction:

• Never merge. Open PRs only.
• Never force-push. Regular pushes only. If an amend is needed, stop and ask.
• Never work on main / master / trunk. Every change is on a feature branch.
• Never modify files outside the detected repo root.
• Never auto-apply fixes to files under: auth/, crypto/, payments/, migrations/, or any path matching a project's own sensitive-area list. Surface these as proposed patches for human review, even when auto_fixable: true.
• Never perform major-version dependency bumps autonomously. Propose patches; human confirms.
• Never delete code without existing test coverage, or without explicit per-finding user approval.
• Never fix a finding the audit marked risk_if_unfixed: <severe> or where severity: critical without per-finding confirmation. Prepare the patch on a branch; do NOT push or PR; surface to the user.
• Never edit findings.md. The audit owns that file.

These are not configurable. The user can ask for something in scope but cannot opt out of these rules.

Process

1. Pre-flight checks

Before anything:

• Confirm findings.md path and validate against schema §4 (same validation as the tickets skill). Abort on any schema failure.
• Confirm repo is a git repo with a clean working tree. If not, ask the user to commit / stash first.
• Confirm the default branch name (usually main). The skill will never target it for commits.
• Confirm any uncommitted .gitignore additions are saved (some workflows stage .gitignore as part of a fix).

2. Ask: direct modification or patches only?

Present the user with two modes. Do not assume.

I can work in one of two modes:

  1. DIRECT — I'll create branches, make commits, push, and open PRs.
     You review each PR and merge when ready.
     Recommended for most cases.

  2. PATCHES ONLY — I'll produce diff files in `tech-debt-patches/`, one per group.
     You apply them manually. No branches, commits, or PRs.
     Recommended when: no git remote, shared branch workflow, or evaluating the skill.

Which mode? (1 or 2)

Lock the mode for the session. Ask again if the user requests a change.

3. Load and triage findings

Parse findings.md. Classify each finding:

• Tier A — Auto-candidate. ALL of: auto_fixable: true, severity: low or medium (never high or critical), not touching guardrail paths, not a major dep bump. These can batch-apply with group-level review only.
• Tier B — Per-finding consent. Everything not-Tier-A and not-Tier-C. Specifically this catches: any finding with auto_fixable: false; any finding with severity: high regardless of auto_fixable; any finding touching a guardrail path; any major dep bump. Show the user the fix plan for each; wait for confirmation.
• Tier C — Human-first. severity: critical OR any finding tagged with secrets, rotation-required, or similar. The skill prepares context but does not modify code autonomously. Present full plan, ask for human to lead.

Rationale for the high-severity rule: a high-severity finding that looks mechanically auto-fixable (e.g., a version-pin sweep) still benefits from the user seeing the plan first. The cost of a confirmation prompt is seconds; the cost of auto-applying a high-severity change and discovering it broke prod is much larger. When in doubt about which tier, pick the more cautious one.

Show the classification summary:

Findings classification:
  Tier A (batch-apply, group review):   <n>  [list of IDs]
  Tier B (per-finding consent needed):  <n>  [list of IDs]
  Tier C (human leads):                 <n>  [list of IDs]

Proceed with Tier A in auto mode, Tier B with per-finding prompts, Tier C skipped from this run?
(Or choose to review each tier separately.)

4. Group Tier A by non-overlapping file sets

For Tier A only (Tier B and C are handled per-finding):

1. Extract the file(s) touched by each finding's suggested fix. Include files explicitly named AND files the fix inherently touches (e.g., package-lock.json is touched whenever package.json changes).
2. Build groups by the union-find / connected-components algorithm: two findings are in the same group if their file sets overlap. Transitively.
3. Produce group names as slugs: tech-debt/<lead-category>-<short-scope>, e.g., tech-debt/deps-api, tech-debt/docs-root.
4. Print the groups:

Group 1 — tech-debt/deps-api (3 findings, 2 files)
  TD-001, TD-002, TD-003 → apps/api/package.json, package-lock.json
Group 2 — tech-debt/docs-readme (2 findings, 1 file)
  TD-011, TD-014 → README.md
Group 3 — tech-debt/dead-legacy (1 finding, 1 file)
  TD-038 → apps/api/src/legacy/exporter.ts

5. Confirm grouping with the user before dispatch. A user might ask to merge two small groups, split one, or exclude a file.

5. Dispatch Tier A fixes

For each group (in severity-descending order, so the most impactful fixes land first):

If the harness supports sub-agents:

• Spawn a sub-agent with scope narrowed to the group's files and findings. Give it the senior-engineer persona with an explicit group scope.
• The sub-agent: checks out a new branch <group-name>, applies the fixes, runs any per-language verify step (npm run check, dotnet build, pytest, etc. — ask at group start), commits per finding with a descriptive message, pushes, opens a PR (draft, with a description citing the finding IDs).
• Parent waits for return; records result.
• Concurrency limit: default 4 groups in flight at once. Configurable via user input; never 0 or >8 without explicit user request.

If the harness does not support sub-agents:

• Process groups sequentially.
• For each group: create branch, apply fixes, verify, commit, push, open PR (draft). Then move on.

Patch mode (mode 2 from step 2):

• No branches, commits, or pushes. For each group, produce a single .patch file in tech-debt-patches/<group-name>.patch using git diff format. No PR.
• Each patch file opens with a Subject: [tech-debt] TD-NNN — <title> line followed by a short rationale, matching git format-patch convention — so the file is a ready-to-use commit message if the user applies with git am or pipes it into a manual commit.
• After generating all Tier A patches, write a summary.md in the output directory listing the patch files, the tier-classification table, and any Tier B/C findings that will need separate handling. This makes the patches-mode run self-documenting.

6. Handle Tier B per-finding

For each Tier B finding, sequentially:

1. Show the fix plan: the diff that would be applied, the branch name, the rationale.
2. Ask: "Apply this? (y / n / skip)".
3. On y: proceed on a branch named tech-debt/<finding-id>-<slug>. One finding, one branch, one PR.
4. On n: record as "declined"; don't revisit.
5. On skip: record as "deferred"; don't block other findings.

Tier B findings do NOT parallelize. Per-finding consent is the rate-limiting step.

Ordering with Tier A: if a Tier B finding's file set overlaps a Tier A group that's already been dispatched or applied, handle the Tier B finding AFTER the Tier A group's PR has been merged (or patches applied). This avoids proposing a diff against a pre-Tier-A state that the user will need to manually rebase. When surfacing Tier B findings to the user, note any such dependency: "TD-XYZ touches apps/api/package.json, which was also changed in Tier A group tech-debt/deps-api — recommend resolving that group first."

7. Handle Tier C (human-first)

For each Tier C finding:

1. Produce a written plan: what the fix would look like, what risks attach, what human-only steps are required (credential rotation, communication to stakeholders, CI secrets update, etc.).
2. Do NOT apply the fix.
3. Store the plan as tech-debt-plans/<finding-id>-plan.md next to the findings file.
4. Alert the user to each Tier C finding individually — don't batch them.

8. Produce a summary

Fix run complete.

Mode: <DIRECT | PATCHES>

Tier A:
  Groups attempted: <n>
  Branches created: <n>
  PRs opened: <n>
  Findings resolved: <n>
  Verify-step failures (blocked merge): <n> → [list]

Tier B:
  Applied: <n>
  Declined: <n>
  Deferred: <n>

Tier C:
  Plans written: <n>  → tech-debt-plans/
  Findings touched: 0 (by design)

Next steps:
  - Review PRs and merge when ready.
  - Address Tier B deferred findings when you have time.
  - Lead the Tier C remediation with the written plans as a starting point.

findings.md was NOT modified. Re-run tech-debt-audit after merges to regenerate.

9. Do NOT re-run the audit automatically

Even if all findings appear resolved, do not invoke tech-debt-audit to regenerate findings.md. The user decides when to re-audit; they may want to review PRs first.

Rationalizations

Excuse	Rebuttal
"CI is green; I can merge this PR myself and save the human a step."	No. Merging is a human decision. Always.
"This finding touches auth/, but it's a tiny typo fix."	Guardrails don't have a "but it's small" exemption. Propose the patch; let the human confirm.
"Two fixes both touch package.json — I'll run them in parallel; they'll probably just merge cleanly."	"Probably" is not a grouping strategy. If the file overlaps, sequence or merge into one group.
"The dep bump is only one major version — surely that's okay to auto-apply."	No. Major-version bumps are human-reviewed regardless of apparent scope.
"I'll edit findings.md to strike through the ones I fixed."	No. The audit file is frozen. Re-audit generates a fresh one.
"The sub-agents finished their groups; let me merge them into a combined PR for efficiency."	No. One branch per group; one PR per group. Combining loses provenance.
"This Tier C finding is obvious; I'll just do it as Tier A."	Tiers reflect risk. If the severity is critical or the tags match human-first criteria, it stays Tier C.
"The test suite is slow; I'll skip verification and trust the diff looks right."	No. Each group runs the verification step. If it's slow, announce that and wait; don't skip.
"A Tier B finding is stuck on user input; I'll just apply it and surface later."	No. Tier B blocks on consent; that's what tier B means.

Red Flags

Stop and reset if:

• You're about to commit on main / master / trunk.
• You're about to force-push anything.
• You're editing findings.md.
• You're writing to a path outside the repo root.
• A sub-agent's scope blurred — it's now touching files not in its group.
• A Tier C finding is halfway to being applied without a human in the loop.
• You notice a secret during a fix and your first instinct is anything other than "stop, redact, alert."
• Verification step fails on a group and you're about to land the PR anyway.
• The user's answer to "direct or patches?" is ambiguous and you picked one without confirming.
• Two groups share a file and you're proceeding without re-grouping.

Verification

The skill is done when ALL of these are true:

• findings.md schema validation passed before any work started.
• Working tree was clean before branches were created.
• Every change lives on a branch matching the tech-debt/* pattern.
• No commit was made on main / master / trunk.
• No force-push occurred.
• No file was modified outside the repo root.
• Every Tier A group has its own branch and PR (or patch file in patches mode).
• Every Tier B finding that wasn't declined has its own branch and PR.
• No Tier C finding was auto-applied.
• findings.md is byte-identical to its pre-run state.
• Summary shown to the user with Tier-wise breakdown and next-steps.
• No secret values appear in any committed file or PR description.

If any item fails, stop, surface the failure, and do not report the skill complete.

---

Version History

• 1.0 (current) — Reads findings.md per schema v1.0. Tiered dispatch (A/B/C) with non-overlapping file grouping. Parallel sub-agent dispatch on supporting harnesses; sequential fallback elsewhere. Patches-only mode for review-first workflows.