name: tech-debt description: Identify, categorize, and prioritize technical debt across six dimensions. Generates remediation plans with effort estimates. Offered by /draft:new-track for refactor tracks.

Tech Debt

You are conducting a technical debt analysis to catalog, prioritize, and plan remediation of debt across the codebase.

Red Flags — STOP if you're:

• Flagging intentional design choices as debt (check tech-stack.md accepted patterns first)
• Cataloging debt without understanding the business context
• Setting priorities without considering team capacity
• Recommending "rewrite from scratch" without exhausting incremental options
• Ignoring the existing guardrails.md conventions

Not all shortcuts are debt. Check accepted patterns before flagging.

Pre-Check

0. Capture Git Context

Before starting, capture the current git state:

git branch --show-current    # Current branch name
git rev-parse --short HEAD   # Current commit hash

Store this for the report header. All findings are relative to this specific branch/commit.

1. Verify Draft Context

ls draft/ 2>/dev/null

If draft/ doesn't exist, this skill can still run standalone with reduced context.

2. Load Draft Context (if available)

Read and follow the base procedure in core/shared/draft-context-loading.md.

Step 1: Parse Arguments

• /draft:tech-debt — Project-wide scan (default)
• /draft:tech-debt module <name> — Module-scoped scan
• /draft:tech-debt category <type> — Filter by category (code, architecture, test, dependency, documentation, infrastructure)
• /draft:tech-debt <path> — Scan specific directory/file pattern

Step 2: Load Context

1. Read draft/tech-stack.md — Critical: "Accepted Patterns" section. Do NOT flag these as debt.
2. Read draft/guardrails.md — Learned conventions (skip) and anti-patterns (always flag)
3. Read draft/.ai-context.md — Module boundaries, invariants, known constraints
4. Read draft/product.md — Business priorities for impact assessment
5. Read draft/workflow.md — Team conventions and toolchain for feasibility assessment

Step 3: Scan for Debt

Scan the codebase systematically across all six categories. For each finding, record: location (file:line), description, evidence, and category.

Category 1: Code Debt

• Complex functions (cyclomatic complexity >10, deep nesting >4 levels)
• Duplicated code blocks (>20 lines similar across multiple locations)
• TODO/FIXME/HACK/XXX comments (especially old ones — check git blame age)
• Dead code (unreachable branches, unused exports, commented-out blocks)
• Inconsistent naming patterns within the same module
• Long functions (>100 lines without clear separation of concerns)
• God classes (>500 lines, >10 public methods, mixed responsibilities)
• Magic numbers and hardcoded strings that should be constants
• Deeply nested callbacks or promise chains (callback hell)

Category 2: Architecture Debt

• Dependency cycles between modules (A depends on B depends on A)
• Tight coupling (modules with >5 direct cross-references)
• Layer violations (UI calling DB directly, business logic in controllers)
• Missing abstractions (repeated patterns without shared interface)
• Monolith tendencies (single module >50% of codebase)
• Inconsistent data flow patterns (some modules use events, others direct calls)
• Missing or bypassed API boundaries (internal implementation details exposed)
• Configuration scattered across multiple locations

Category 3: Test Debt

• Modules with zero test coverage
• Missing integration tests for service boundaries
• Brittle tests (frequently failing, time-dependent, order-dependent)
• Test-code coupling (tests that break on internal refactor, not behavior change)
• Missing E2E tests for critical user flows (from product.md)
• Tests with no assertions (tests that only check "doesn't throw")
• Disabled/skipped tests without justification
• Missing test fixtures or shared test utilities (repeated setup code)

Category 4: Dependency Debt

• Outdated dependencies (>2 major versions behind)
• Known security vulnerabilities (check advisories: npm audit, pip audit, etc.)
• Deprecated APIs in use (check dependency changelogs)
• Version conflicts or pinning issues
• Abandoned dependencies (no updates >2 years, archived repos)
• Overly broad dependency versions (no pinning in production)
• Unnecessary dependencies (functionality available in stdlib or already-included packages)

Category 5: Documentation Debt

• Undocumented public APIs (exported functions/classes without docstrings)
• Stale README (doesn't match current setup steps or architecture)
• Missing architecture decision records for non-obvious choices
• Outdated onboarding documentation
• Missing runbooks for production services
• API docs out of sync with implementation
• Missing inline comments for complex algorithms or business rules

Category 6: Infrastructure Debt

• Manual deployment steps (should be automated)
• Missing or insufficient monitoring (services without health checks or alerts)
• Hardcoded configuration (should be environment variables)
• Missing CI checks (linting, security scanning, type checking)
• No automated backup/restore verification
• Missing or outdated Dockerfiles / container configs
• Inconsistent environment parity (dev/staging/prod divergence)
• Missing rate limiting or resource guards on public endpoints

Step 4: Prioritize

For each finding, score on three dimensions:

• Impact (1-5): How much does this hurt development velocity or production reliability?

  • 1: Minor annoyance, cosmetic
  • 2: Slows development occasionally
  • 3: Regular friction, workarounds needed
  • 4: Significant velocity drag or reliability risk
  • 5: Blocking progress or causing incidents

• Risk (1-5): How likely is this to cause a production incident?

  • 1: Extremely unlikely
  • 2: Unlikely but possible
  • 3: Moderate likelihood
  • 4: Likely under certain conditions
  • 5: Near-certain or already causing issues

• Effort (1-5): How much work to remediate?

  • 1: Hours (quick fix)
  • 2: A day or two
  • 3: A sprint (1-2 weeks)
  • 4: Multiple sprints
  • 5: Large project (months)

Priority = (Impact + Risk) / (6 - Effort)

Higher score = higher priority. This formula naturally favors high-impact, low-effort items ("quick wins") and deprioritizes low-impact, high-effort items.

Step 5: Generate Remediation Plan

Organize findings into three actionable tiers:

Tier 1: Quick Wins (Priority > 3, Effort <= 2)

Items that can be fixed in a single sprint or less. Do these first — they deliver the best return on investment.

For each item:

• Specific fix description
• Estimated time (hours)
• Suggested assignee pattern (e.g., "whoever touches this module next")

Tier 2: Strategic Improvements (Priority > 2, Effort > 2)

Items requiring dedicated effort. Create via /draft:new-track or feed into /draft:jira-preview.

For each item:

• Scope and approach
• Estimated effort (sprints)
• Dependencies and sequencing
• Risk of deferral (what happens if we wait?)

Tier 3: Nice-to-Haves (Priority <= 2)

Track but don't prioritize. Revisit quarterly. These items are real debt but the cost of remediation exceeds the current pain.

Step 6: Save Output

MANDATORY: Include YAML frontmatter with git metadata. Follow core/shared/git-report-metadata.md.

Include the report header table immediately after frontmatter:

| Field | Value |
|-------|-------|
| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
| **Generated** | {ISO_TIMESTAMP} |
| **Synced To** | `{FULL_SHA}` |

Save to: draft/tech-debt-report-<timestamp>.md Create symlink: draft/tech-debt-report-latest.md

TIMESTAMP=$(date +%Y-%m-%dT%H%M)
# Example: draft/tech-debt-report-2026-03-15T1430.md
ln -sf tech-debt-report-${TIMESTAMP}.md draft/tech-debt-report-latest.md

Report structure:

1. Executive Summary — Total findings by category and priority tier, headline stats
2. Priority Matrix — Table of all findings sorted by priority score
3. Category Details — Per-category findings with file locations and evidence
4. Remediation Plan — Three tiers with effort estimates
5. Recommendations — Strategic advice on debt management practices

Cross-Skill Dispatch

• Offered by: /draft:new-track (refactor tracks — scope the debt before planning)
• Suggested by: /draft:implement (when TODO/FIXME detected at completion)
• Suggested by: /draft:deep-review (architecture debt findings)
• Feeds into: /draft:jira-preview (create remediation tickets from Tier 2 items)
• Feeds into: /draft:testing-strategy (Test Debt findings inform test planning)
• Jira sync: If ticket linked, attach report and post summary via core/shared/jira-sync.md

Error Handling

If no draft context: Run with reduced analysis, note: "Run /draft:init for better debt detection with accepted-pattern filtering" If tech-stack.md has accepted patterns: Explicitly skip those patterns, note: "Skipped N accepted patterns from tech-stack.md" If >100 findings: Group by category, show top 20 by priority in the summary, full list in Category Details section If module scope requested but module not found: List available modules, ask user to confirm