Skill: qa-tech-debt

Fork

Technical debt management and prioritization, including test-coverage analysis and Kaizen continuous improvement. Trigger when the user wants to identify, prioritize or plan the repayment of technical debt, analyse/improve test coverage, or run a PDCA continuous-improvement cycle.

Configuration

Property	Value
Context	fork
Allowed tools	Read, Grep, Glob, Bash
Keywords	tech, debt, technical debt, tech debt, refactoring priority, legacy code, code quality

Detailed description

Tech Debt Management

Triggers

• "technical debt"
• "tech debt"
• "refactoring priority"
• "legacy code"
• "code quality"

Identification

Code Smells to Detect

# TODOs and FIXMEs
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" src/

# Large files
find src -name "*.ts" -o -name "*.tsx" | xargs wc -l | sort -n | tail -20

# Complexity (nesting)
grep -r "if.*if.*if" --include="*.ts" src/

# any in TypeScript
grep -r ": any" --include="*.ts" --include="*.tsx" src/

Metrics

Metric	Threshold	Command
LOC/file	< 500	wc -l
Functions/file	< 15	grep
Nesting depth	< 4	analysis
Test coverage	> 70%	npm test -- --coverage

Categorization

Impact

Level	Description	Examples
Critical	Blocks development	Circular coupling
High	Significantly slows down	Massive duplication
Medium	Hinders maintenance	Confusing naming
Low	Cosmetic	Inconsistent style

Effort

Level	Time	Examples
Trivial	< 1h	Rename variable
Low	< 1 day	Extract function
Medium	1-5 days	Restructure module
High	> 1 week	Rewrite component

Prioritization

Impact/Effort Matrix

Impact
  ^
  |  Quick Wins  |  Strategic
  |     (P1)     |    (P2)
  +--------------+-------------
  |   Fill-in    |   Avoid
  |     (P3)     |    (P4)
  +-------------------------> Effort

Remediation Plan

Template

## Item: [Name]

**Priority**: P[1-4]
**Impact**: [Critical/High/Medium/Low]
**Effort**: [Trivial/Low/Medium/High]

### Description
[Description of the problem]

### Files concerned
- path/to/file.ts:L42

### Proposed solution
[Refactoring approach]

### Success criteria
- [ ] Tests pass
- [ ] No regression
- [ ] Improved metrics

Test coverage analysis

Test debt is a first-class category of technical debt. Measure and close the gaps.

# Current coverage (statements / branches / functions / lines)
npm test -- --coverage          # Jest / Vitest

Metric	Threshold	Notes
Statements	> 80%
Branches	> 75%	Hardest and highest-value gap
Functions	> 80%

• Categorise gaps by criticality (business code and edge cases first), not by raw %.
• Prioritise critical business code; 100% coverage != 100% quality — never sacrifice test quality to hit a number.
• Add missing tests for branches, boundary conditions and error paths; wire a coverage gate into CI (/ops:ops-ci). Generate the tests via /dev:dev-tdd or /dev:dev-tdd.

Continuous improvement (Kaizen)

For incremental, durable improvement of code and process, run the PDCA cycle instead of a big-bang rewrite.

• PLAN: identify the problem and root cause (5 Whys), set a SMART objective.
• DO: implement one change at a time, atomic commits.
• CHECK: measure before/after, compare to the objective.
• ACT: standardise on success, adjust on failure; plan the next iteration.
• Eliminate the 7 Muda (overproduction, waiting, transport, over-processing, inventory, motion, defects). Always measure before and after; one change at a time, no revolutions.

Workflow

1. Identify - Scan the codebase (smells, coverage gaps, Muda)
2. Categorize - Impact and effort
3. Prioritize - Decision matrix
4. Plan - Integrate into the backlog
5. Execute - Incremental refactoring (one change at a time, PDCA)
6. Validate - Tests, coverage and metrics (before/after)

Automatic triggering

This skill is automatically activated when:

• The matching keywords are detected in the conversation
• The task context matches the skill's domain

Triggering examples

• "I want to tech..."
• "I want to debt..."
• "I want to technical debt..."

Context fork

Fork means the skill runs in an isolated context:

• Does not pollute the main conversation
• Results are returned cleanly
• Ideal for autonomous tasks

---

Practical examples

1. Example: Tech Debt Inventory

Example: Tech Debt Inventory

Scenario

Audit a 2-year-old Node.js API to inventory and prioritize technical debt.

Debt Inventory

Critical (fix within 1 sprint)

ID	Category	Description	Impact	Effort
TD-001	Security	Express 4.17 has known CVEs, upgrade to 4.21+	High	S
TD-002	Reliability	No error handling middleware; unhandled rejections crash server	High	S
TD-003	Data	Raw SQL queries with string interpolation (SQL injection risk)	High	M

High (fix within 1 month)

ID	Category	Description	Impact	Effort
TD-004	Maintainability	3 god classes > 800 lines (OrderController, UserService, Utils)	Medium	L
TD-005	Testing	Test coverage at 23%, no integration tests	Medium	L
TD-006	Types	47 any types across codebase, no strict mode	Medium	M
TD-007	Dependencies	12 packages 2+ major versions behind	Medium	M

Medium (plan for next quarter)

ID	Category	Description	Impact	Effort
TD-008	Architecture	Circular dependencies between 5 modules	Low	L
TD-009	DX	No linting or formatting configured	Low	S
TD-010	Observability	Console.log only, no structured logging	Low	M
TD-011	API	Inconsistent error response formats across 15 endpoints	Low	M

Metrics Summary

Total debt items:        11
Critical:                3   (fix immediately)
High:                    4   (plan this month)
Medium:                  4   (next quarter)

Estimated total effort:  ~45 story points
Test coverage:           23% -> target 80%
TypeScript any count:    47 -> target 0
Outdated dependencies:   12 -> target 0

Recommended Paydown Plan

Sprint 1: Security & Stability

• TD-001: Upgrade Express (1 point)
• TD-002: Add error middleware (2 points)
• TD-003: Parameterized queries (5 points)
• TD-009: Setup ESLint + Prettier (2 points)

Sprint 2-3: Testing & Types

• TD-006: Enable strict TypeScript, fix any types (8 points)
• TD-005: Add tests for critical paths first (13 points)

Sprint 4+: Architecture

• TD-004: Extract services from god classes (8 points)
• TD-008: Resolve circular dependencies (5 points)

Key Decisions

• Security first: SQL injection and CVEs before any feature work
• 20% rule: Allocate 20% of each sprint to debt paydown
• Metrics tracking: Re-run audit monthly, track trend in coverage and any count
• Boy Scout rule: Improve any file you touch, even outside debt sprints

---

See also

• Back to skills
• Architecture