Using Tech Debt Skills

Using Tech Debt Skills

Overview

This is the meta-skill for the tech-debt skill pack. It doesn't audit, write tickets, or fix code itself — it routes the user to the right workflow skill based on what they actually want.

The pack has three workflow skills and three personas; this router helps the user (and the agent) pick the right starting point without reading every SKILL.md first.

When to Use

Trigger on any of:

• User says "tech debt", "technical debt", "debt audit", "debt review", or "debt cleanup".
• User says "look at this codebase and tell me what's broken" and isn't scoped to a specific bug.
• User says "clean up this codebase" or "prioritize what to work on".
• User has pasted the installed pack and asked "what do I do next?"
• Any new session where the user is unclear which of the three workflow skills to invoke.

Do NOT use this skill when the user has already picked a workflow explicitly (e.g., "run tech-debt-audit against this repo"). Go straight to that skill.

Routing

Ask the user one question — or infer from context — and route accordingly.

The three paths

       You want to…                         …invoke this skill
       ─────────────                        ─────────────────
  1.   Know what debt exists.        →      tech-debt-audit
       (Produce findings.md.)

  2.   Turn an existing findings.md  →      tech-debt-tickets
       into tickets the team can
       work on.

  3.   Start fixing the debt in      →      tech-debt-fix
       an existing findings.md,
       with human-in-the-loop.

Decision tree

Does findings.md already exist at the project root (or at a known path)?
│
├── No
│   → Run tech-debt-audit. It produces findings.md, then offers the
│     downstream fork (tickets or fix). The user doesn't need to come
│     back to this router.
│
└── Yes
    │
    ├── User wants to share the work with their team,
    │   file it for backlog planning, or send to stakeholders?
    │   → Run tech-debt-tickets.
    │
    ├── User wants to start applying fixes now?
    │   → Run tech-debt-fix.
    │
    └── User just wants to re-read or re-review findings?
        → Stop. Open findings.md for them.

Ambiguous intent — ask one question

If the user says something like "help me with tech debt" with no more detail, ask:

Tech debt workflow — pick one:

  1. AUDIT — I'll sweep the codebase across 10 categories and
     produce a findings.md report. No fixes, no tickets yet.
     (Use this if you don't already have a recent findings.md.)

  2. TICKETS — I'll convert an existing findings.md into ticket
     markdown files, ready to paste into Jira / GitHub / GitLab / Linear.

  3. FIX — I'll read an existing findings.md and apply fixes
     on branches (or produce patches). Never auto-merges;
     respects guardrails for sensitive paths.

Which?

Wait for the answer. Do not guess.

What the Pack Contains

For orientation, the full pack has:

Workflow skills (skills/):

• using-tech-debt-skills — this file; the router.
• tech-debt-audit — produces findings.md.
• tech-debt-tickets — produces ticket markdown from findings.md.
• tech-debt-fix — applies fixes from findings.md on branches, per-tier.

Personas (agents/):

• debt-evaluator — adopted by tech-debt-audit.
• technical-writer — adopted by tech-debt-tickets.
• senior-engineer — adopted by tech-debt-fix.

Supporting material:

• references/ — one checklist per audit category (10 files).
• templates/findings.schema.md — the contract between skills.
• templates/ticket.template.md + ticket-template.example.md — ticket format + override guide.
• docs/harness-compatibility.md — which capabilities work in which AI coding harness.
• docs/getting-started.md — install + first-run.

Process Discipline

This is a router. Three habits:

1. Don't do the work yourself. This skill routes. It does not audit, ticket, or fix. Hand off to the right workflow skill.
2. Ask when ambiguous. One question is cheaper than picking wrong and having to undo.
3. Respect the path order. Fix and tickets both read findings.md. If it doesn't exist, don't invent one — run audit first.

Red Flags

Stop and reset if:

• You're about to start auditing / ticketing / fixing directly from this skill. Wrong layer — invoke the workflow skill.
• You're about to guess which path the user wants. One question is cheaper.
• You've routed to a workflow skill but the user hasn't confirmed the routing question.

Verification

The skill is done when:

• [ ] The user has expressed intent for one of the three paths (AUDIT / TICKETS / FIX), either directly or via answering the router question.
• [ ] The appropriate workflow skill has been invoked (or the user has been told how to invoke it in their harness).
• [ ] If the user wanted tickets or fix but no findings.md exists, they've been told to run audit first and the handoff has been made.

That's it. The router's job is to end at the doorstep of the right workflow skill.

---

Version History

• 1.0 (current) — Routes between the three workflow skills. Single-question disambiguation. Decision tree gates on findings.md existence.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jjw013
• Source: jjw013/tech-debt-skill
• License: MIT

Install and usage instructions live in the source repository linked above.