Skill v1.0.4
currentAutomated scan100/1003 files
version: "1.0.4" name: tech-debt description: Identify, categorize, and prioritize technical debt across seven 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.
MANDATORY GRAPH LOOKUP (read before debt scan)
First resolve the bundled helpers:
# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}# is not exported into skill Bash). See core/shared/tool-resolver.md.DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
When draft/graph/schema.yaml exists, this skill must follow the graph-first lookup contract in core/shared/graph-query.md §Mandatory Lookup Contract. Tech-debt prioritization is fundamentally driven by graph data:
- Run
"$DRAFT_TOOLS/hotspot-rank.sh" --repo .— rank candidates by `fanIn × complexity` to surface high-leverage debt first. - Query
"$DRAFT_TOOLS/graph-arch.sh" --repo .and run"$DRAFT_TOOLS/cycle-detect.sh" --repo .— flag debt in modules involved in cycles as higher priority. - Run
"$DRAFT_TOOLS/cycle-detect.sh" --repo .to enumerate dependency cycles — every cycle is a candidate architecture-debt entry. - For each catalogued finding, run
"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>so the remediation plan includes blast-radius.
Filesystem grep (e.g. scan-markers.sh) is still primary for TODO/FIXME marker discovery — markers are source-text, not graph-derived. The graph governs prioritization, the marker scan governs discovery.
Red Flags — STOP if you're:
See shared red flags — applies to all code-touching skills.
Skill-specific:
- 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 namegit 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
- Read
draft/tech-stack.md— Critical: "Accepted Patterns" section. Do NOT flag these as debt. - Read
draft/guardrails.md— Learned conventions (skip) and anti-patterns (always flag) - Read
draft/.ai-context.md— Module boundaries, invariants, known constraints - Read
draft/product.md— Business priorities for impact assessment - Read
draft/workflow.md— Team conventions and toolchain for feasibility assessment
Step 3: Scan for Debt
Scan the codebase systematically across all seven categories. For each finding, record: location (file:line OR track id for Process Debt), description, evidence, and category.
Category 1: Code Debt
For TODO/FIXME/HACK/XXX/DEPRECATED markers, prefer the deterministic scan-markers.sh wrapper — it emits JSON [{path,line,marker,text,sha,author,introduced,age_days}] with blame ages already computed. Resolve via the canonical tool resolver (see core/shared/tool-resolver.md):
# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}# is not exported into skill Bash). See core/shared/tool-resolver.md.DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"[ -x "$DRAFT_TOOLS/scan-markers.sh" ] && bash "$DRAFT_TOOLS/scan-markers.sh" --root .# Fallback when script unavailable: grep -rn 'TODO\|FIXME\|HACK\|XXX\|DEPRECATED' .
Use the JSON output to prioritise: markers with age_days > 180 are stale and should be promoted to tracked tech debt.
Marker context gate (Ground-Truth Discipline G1): scan-markers.sh produces candidates, not findings. Before promoting a TODO/FIXME/HACK/XXX/DEPRECATED marker to your debt catalog, Read the surrounding 10–20 lines at that file:line. Many markers are justified (intentional deferrals with ownership) or already addressed (the marker rotted, the work shipped). A debt entry whose Evidence is "marker exists" without a Read is a Ground-Truth Red Flag — produce false positives and reviewer churn.
- 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 via
scan-markers.shabove) - 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
Category 7: Process Debt ( HLD/LLD compliance)
Scan draft/tracks/*/ for design-process gaps. For each track:
- Read
spec.mdfrontmatterclassification.criticality. Default tostandardif absent. - Check for
hld.md: - Missing for
criticality ∈ {standard, high, mission-critical}→ flag as Process Debt - Severity:
criticalfor mission-critical,highfor high,mediumfor standard - Remediation: "Run
/draft:decompose <track>to generate hld.md" - Check
hld.mdApprovals table: - Required rows unsigned (per
/draft:uploadStep 3.1 logic) and the track has merged commits → flag - Severity:
highif criticality ∈ {high, mission-critical},mediumotherwise - Remediation: "Re-circulate hld.md to listed approvers; update Date column on sign-off"
- Check for
lld.md: - Any module in HLD §Detailed Design has
Complexity: HighANDlld.mdis missing → flag - Severity:
medium - Remediation: "Run
/draft:decompose <track> --lld" - Check HLD §Checklist completeness:
- For criticality ≥ standard: any §Checklist sub-section still showing the placeholder text "<Describe..." or empty bullets → flag as Process Debt
- Severity:
highfor high/mission-critical,mediumfor standard - Remediation: "Author must populate hld.md §Checklist before /draft:deploy-checklist will pass"
- Check HLD/LLD freshness:
- If
synced_to_commitis older than the latest merged commit touching files in HLD §Detailed Design → flag as drift - Severity:
medium - Remediation: "Run
/draft:decompose <track>to refresh graph slots; review structural sections; re-circulate if signed"
Process Debt findings carry the same Impact/Effort/Risk scoring as other categories. They surface in the remediation plan alongside code/architecture debt.
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 route via /draft:jira (or /draft:plan "tech debt remediation").
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.mdln -sf tech-debt-report-${TIMESTAMP}.md draft/tech-debt-report-latest.md
Report structure:
- Executive Summary — Total findings by category and priority tier, headline stats
- Priority Matrix — Table of all findings sorted by priority score
- Category Details — Per-category findings with file locations and evidence
- Remediation Plan — Three tiers with effort estimates
- Recommendations — Strategic advice on debt management practices
Report Closing: Next Actions (REQUIRED)
Every tech-debt report must end with a ## Next Actions section listing the smallest set of follow-ups in execution order. Use this exact shape:
## Next Actions| # | Action | Owner | Blocker? | Skill / Command ||---|---|---|---|---|| 1 | <imperative one-liner> | <team\|TBD> | yes/no | `/draft:<skill> <args>` or `n/a` |
Rules:
- Tech-debt rarely "blocks" merge; mark
Blocker? = yesonly for items that will cause an outage on next deploy. - Suggest
/draft:new-trackfor items >1 day of work,/draft:adrfor design re-decisions,/draft:implementfor surgical cleanups. - Cap at 10 actions; full backlog stays in the report body.
Mandatory Self-Check (before debt report)
Before printing the final debt report, internally verify and report:
- Graph files queried — JSONL files loaded plus any live graph query-tool invocations (especially
cyclesandimpact). - Layer 1 files deliberately skipped — list any context sections skipped as irrelevant to the categories scanned.
- Filesystem grep fallback justification — for every
grep/findrun beyondscan-markers.sh, name the concept it searched for.
If draft/graph/schema.yaml does not exist, set Graph files queried: NONE and use justification graph data unavailable.
Graph Usage Report (append to debt report)
Emit the canonical footer from core/shared/graph-usage-report.md §Canonical footer. The lint hook scripts/tools/check-graph-usage-report.sh validates the section on save.
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(or/draft:planfor remediation tracks) (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