# Using Tech Debt Skills

> Entry point and router for the tech-debt skill pack. Routes the user to the right workflow (audit, tickets, fix) based on intent. Use when a user mentions technical debt, debt audit, debt review, or debt cleanup — this skill decides which of the three workflow skills applies.

- **Type:** Skill
- **Install:** `agentstack add skill-jjw013-tech-debt-skill-using-tech-debt-skills`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jjw013](https://agentstack.voostack.com/s/jjw013)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jjw013](https://github.com/jjw013)
- **Source:** https://github.com/jjw013/tech-debt-skill/tree/main/skills/using-tech-debt-skills

## Install

```sh
agentstack add skill-jjw013-tech-debt-skill-using-tech-debt-skills
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/jjw013)
- **Source:** [jjw013/tech-debt-skill](https://github.com/jjw013/tech-debt-skill)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-jjw013-tech-debt-skill-using-tech-debt-skills
- Seller: https://agentstack.voostack.com/s/jjw013
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.