feat(skills): Add techdebt skill with parallel subagent architecture

Comprehensive technical debt detection using always-parallel subagents.
Implements Boris Cherny's recommendation: "Build a /techdebt slash command
and run it at the end of every session to find and kill duplicated code."

Features:
- 🚀 Always-parallel subagent execution (2-15s scans)
- 🎯 4 detection categories: Duplication, Security, Complexity, Dead Code
- 📊 AST-based structural detection, not naive text matching
- 🔒 Security pattern matching (hardcoded secrets, SQL injection, XSS)
- 📈 Severity ranking (P0-P3) with actionable recommendations
- 🔄 Git-aware: scan diff (default) or deep scan (full codebase)
- 🌐 Multi-language: Python, JS/TS, Go, Rust, SQL

Structure (1,520 lines total):
- SKILL.md (424 lines) - Main workflow, subagent orchestration
- references/patterns.md (480 lines) - Language-specific debt patterns
- references/severity-guide.md (383 lines) - Classification framework
- assets/report-template.md (233 lines) - Actionable report format

Benefits:
- Session-end workflow catches issues while context is fresh
- Parallel subagents keep main context clean (Boris's tip)
- Scalable to large codebases via compute parallelization
- Same architecture for quick (diff) and deep (full) scans

Bump version: 1.5.2 → 1.6.0 (new skill, 42 total)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-mods",
-  "version": "1.5.2",
-  "description": "Custom commands, skills, and agents for Claude Code - session continuity, terminal canvas, 22 expert agents, 41 skills, 3 commands, 4 rules, modern CLI tools",
+  "version": "1.6.0",
+  "description": "Custom commands, skills, and agents for Claude Code - session continuity, terminal canvas, 22 expert agents, 42 skills, 3 commands, 4 rules, modern CLI tools",
   "author": "0xDarkMatter",
   "repository": "https://github.com/0xDarkMatter/claude-mods",
   "license": "MIT",
@@ -85,6 +85,7 @@
       "skills/structural-search",
       "skills/tailwind-patterns",
       "skills/task-runner",
+      "skills/techdebt",
       "skills/testing-patterns",
       "skills/testgen",
       "skills/tool-discovery"

skills/techdebt/SKILL.md

@@ -0,0 +1,424 @@
+---
+name: techdebt
+description: "Technical debt detection and remediation. Run at session end to find duplicated code, dead imports, security issues, and complexity hotspots. Triggers: 'find tech debt', 'scan for issues', 'check code quality', 'wrap up session', 'ready to commit', 'before merge', 'code review prep'. Always uses parallel subagents for fast analysis."
+---
+
+# Tech Debt Scanner
+
+Automated technical debt detection using parallel subagents. Designed to run at session end to catch issues while context is fresh.
+
+## Quick Start
+
+```bash
+# Session end - scan changes since last commit (default)
+/techdebt
+
+# Deep scan - analyze entire codebase
+/techdebt --deep
+
+# Specific categories
+/techdebt --duplicates    # Only duplication
+/techdebt --security      # Only security issues
+/techdebt --complexity    # Only complexity hotspots
+/techdebt --deadcode      # Only dead code
+
+# Auto-fix mode (interactive)
+/techdebt --fix
+```
+
+## Architecture
+
+**Always uses parallel subagents** for fast analysis:
+
+```
+Main Agent (orchestrator)
+    │
+    ├─> Subagent 1: Duplication Scanner
+    ├─> Subagent 2: Security Scanner
+    ├─> Subagent 3: Complexity Scanner
+    └─> Subagent 4: Dead Code Scanner
+
+    ↓ All run in parallel (2-15s depending on scope)
+
+Main Agent: Consolidate findings → Rank by severity → Generate report
+```
+
+**Benefits:**
+- 🚀 Parallel execution - all scans run simultaneously
+- 🧹 Clean main context - no pollution from analysis work
+- 💪 Scalable - handles large codebases efficiently
+- 🎯 Fast - even small diffs benefit from parallelization
+
+## Workflow
+
+### Step 1: Determine Scope
+
+**Default (no flags):**
+- Scan files changed since last commit: `git diff --name-only HEAD`
+- Fast session-end workflow (~2-3 seconds)
+- Perfect for "wrap up" scenarios
+
+**Deep scan (`--deep` flag):**
+- Scan entire codebase
+- Comprehensive analysis (~10-15 seconds for medium projects)
+- Use when refactoring or preparing major releases
+
+**Specific category (e.g., `--duplicates`):**
+- Run only specified scanner
+- Fastest option for targeted analysis
+
+### Step 2: Spawn Parallel Subagents
+
+Launch 4 subagents simultaneously (or subset if category specified):
+
+**Subagent 1: Duplication Scanner**
+- Task: Find duplicated code blocks using AST similarity
+- Tools: `ast-grep`, structural search, token analysis
+- Output: List of duplicate code blocks with similarity scores
+
+**Subagent 2: Security Scanner**
+- Task: Detect security vulnerabilities and anti-patterns
+- Checks: Hardcoded secrets, SQL injection, XSS, insecure crypto
+- Output: Security findings with severity and remediation guidance
+
+**Subagent 3: Complexity Scanner**
+- Task: Identify overly complex functions and methods
+- Metrics: Cyclomatic complexity, nested depth, function length
+- Output: Complexity hotspots with refactoring suggestions
+
+**Subagent 4: Dead Code Scanner**
+- Task: Find unused imports, variables, and unreachable code
+- Checks: Unused imports, dead branches, orphaned functions
+- Output: Dead code list with safe removal instructions
+
+**Subagent instructions template:**
+```
+Scan {scope} for {category} issues.
+
+Scope: {file_list or "entire codebase"}
+Language: {detected from file extensions}
+Focus: {category-specific patterns}
+
+Output format:
+- File path + line number
+- Issue description
+- Severity (P0-P3)
+- Suggested fix (if available)
+
+Use appropriate tools:
+- Duplication: ast-grep for structural similarity
+- Security: pattern matching + known vulnerability patterns
+- Complexity: cyclomatic complexity calculation
+- Dead Code: static analysis for unused symbols
+```
+
+### Step 3: Consolidate Findings
+
+Main agent collects results from all subagents and:
+
+1. **Deduplicate** - Remove duplicate findings across categories
+2. **Rank by severity:**
+   - **P0 (Critical):** Security vulnerabilities, blocking issues
+   - **P1 (High):** Major duplication, high complexity
+   - **P2 (Medium):** Minor duplication, moderate complexity
+   - **P3 (Low):** Dead code, style issues
+3. **Group by file** - Organize findings by affected file
+4. **Calculate debt score** - Overall technical debt metric
+
+### Step 4: Generate Report
+
+Create actionable report with:
+
+```markdown
+# Tech Debt Report
+
+**Scope:** {X files changed | Entire codebase}
+**Scan Time:** {duration}
+**Debt Score:** {0-100, lower is better}
+
+## Summary
+
+| Category | Findings | P0 | P1 | P2 | P3 |
+|----------|----------|----|----|----|----|
+| Duplication | X | - | X | X | - |
+| Security | X | X | - | - | - |
+| Complexity | X | - | X | X | - |
+| Dead Code | X | - | - | X | X |
+
+## Critical Issues (P0)
+
+### {file_path}:{line}
+**Category:** {Security}
+**Issue:** Hardcoded API key detected
+**Impact:** Credential exposure risk
+**Fix:** Move to environment variable
+
+## High Priority (P1)
+
+### {file_path}:{line}
+**Category:** {Duplication}
+**Issue:** 45-line block duplicated across 3 files
+**Impact:** Maintenance burden, inconsistency risk
+**Fix:** Extract to shared utility function
+
+[... continue for all findings ...]
+
+## Recommendations
+
+1. Address all P0 issues before merge
+2. Consider refactoring high-complexity functions
+3. Remove dead code to reduce maintenance burden
+
+## Auto-Fix Available
+
+Run `/techdebt --fix` to interactively apply safe automated fixes.
+```
+
+### Step 5: Auto-Fix Mode (Optional)
+
+If `--fix` flag provided:
+
+1. **Identify safe fixes:**
+   - Dead import removal (safe)
+   - Simple duplication extraction (review required)
+   - Formatting fixes (safe)
+
+2. **Interactive prompts:**
+   ```
+   Fix: Remove unused import 'requests' from utils.py:5
+   [Y]es / [N]o / [A]ll / [Q]uit
+   ```
+
+3. **Apply changes:**
+   - Edit files with confirmed fixes
+   - Show git diff of changes
+   - Prompt for commit
+
+**Safety rules:**
+- Never auto-fix security issues (require manual review)
+- Never auto-fix complexity (requires design decisions)
+- Only auto-fix with explicit user confirmation
+
+## Detection Patterns
+
+### Duplication
+
+**AST Similarity Detection:**
+- Use `ast-grep` for structural pattern matching
+- Detect code blocks with >80% structural similarity
+- Ignore trivial differences (variable names, whitespace)
+
+**Token-based Analysis:**
+- Compare token sequences for exact duplicates
+- Minimum threshold: 6 consecutive lines
+- Group similar duplicates across files
+
+**Thresholds:**
+- P1: 30+ lines duplicated in 3+ locations
+- P2: 15+ lines duplicated in 2+ locations
+- P3: 6+ lines duplicated in 2 locations
+
+### Security
+
+**Pattern Detection:**
+
+| Pattern | Severity | Example |
+|---------|----------|---------|
+| Hardcoded secrets | P0 | `API_KEY = "sk-..."` |
+| SQL injection risk | P0 | `f"SELECT * FROM users WHERE id={user_id}"` |
+| Insecure crypto | P0 | `hashlib.md5()`, `random.random()` for tokens |
+| Path traversal | P0 | `open(user_input)` without validation |
+| XSS vulnerability | P0 | Unescaped user input in HTML |
+| Eval/exec usage | P1 | `eval(user_input)` |
+| Weak passwords | P2 | Hardcoded default passwords |
+
+**Language-specific checks:**
+- Python: `pickle` usage, `yaml.load()` without SafeLoader
+- JavaScript: `eval()`, `innerHTML` with user data
+- SQL: String concatenation in queries
+
+### Complexity
+
+**Metrics:**
+
+| Metric | P1 Threshold | P2 Threshold |
+|--------|--------------|--------------|
+| Cyclomatic Complexity | >15 | >10 |
+| Function Length | >100 lines | >50 lines |
+| Nested Depth | >5 levels | >4 levels |
+| Number of Parameters | >7 | >5 |
+
+**Refactoring suggestions:**
+- Extract method for long functions
+- Introduce parameter object for many parameters
+- Simplify conditionals with guard clauses
+- Break up deeply nested logic
+
+### Dead Code
+
+**Detection methods:**
+- Unused imports (language-specific linters)
+- Unreachable code (after return/break/continue)
+- Unused variables (written but never read)
+- Orphaned functions (never called in codebase)
+
+**Safe removal criteria:**
+- No external references found
+- Not part of public API
+- Not dynamically imported/called
+
+## Language Support
+
+**Tier 1 (Full support):**
+- Python: `ast-grep`, `radon`, `pylint`
+- JavaScript/TypeScript: `ast-grep`, `eslint`, `jscpd`
+- Go: `gocyclo`, `golangci-lint`
+- Rust: `clippy`, `cargo-audit`
+
+**Tier 2 (Basic support):**
+- Java, C#, Ruby, PHP: Pattern-based detection only
+
+**Language detection:**
+- Auto-detect from file extensions
+- Use appropriate tools per language
+- Fallback to universal patterns if specific tools unavailable
+
+## Integration Patterns
+
+### Session End Automation
+
+Add to your workflow:
+
+```markdown
+## Session Wrap-Up Checklist
+
+- [ ] Run `/techdebt` to scan changes
+- [ ] Address any P0 issues found
+- [ ] Create tasks for P1/P2 items
+- [ ] Commit clean code
+```
+
+### Pre-Commit Hook
+
+Create `.claude/hooks/pre-commit.sh`:
+
+```bash
+#!/bin/bash
+# Auto-run tech debt scan before commits
+
+echo "🔍 Scanning for tech debt..."
+claude skill techdebt --quiet
+
+if [ $? -eq 1 ]; then
+  echo "❌ P0 issues detected. Fix before committing."
+  exit 1
+fi
+
+echo "✅ No critical issues found"
+```
+
+### CI/CD Integration
+
+Run deep scan on pull requests:
+
+```yaml
+# .github/workflows/techdebt.yml
+name: Tech Debt Check
+on: [pull_request]
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Run tech debt scan
+        run: claude skill techdebt --deep --ci
+```
+
+## Advanced Usage
+
+### Baseline Tracking
+
+Track debt over time:
+
+```bash
+# Initial baseline
+/techdebt --deep --save-baseline
+
+# Compare against baseline
+/techdebt --compare-baseline
+# Output: "Debt increased by 15% since baseline"
+```
+
+Baseline stored in `.claude/techdebt-baseline.json`:
+
+```json
+{
+  "timestamp": "2026-02-03T10:00:00Z",
+  "commit": "a28f0fb",
+  "score": 42,
+  "findings": {
+    "duplication": 8,
+    "security": 0,
+    "complexity": 12,
+    "deadcode": 5
+  }
+}
+```
+
+### Custom Patterns
+
+Add project-specific patterns in `.claude/techdebt-rules.json`:
+
+```json
+{
+  "security": [
+    {
+      "pattern": "TODO.*security",
+      "severity": "P0",
+      "message": "Security TODO must be resolved"
+    }
+  ],
+  "complexity": {
+    "cyclomatic_threshold": 12,
+    "function_length_threshold": 80
+  }
+}
+```
+
+### Report Formats
+
+```bash
+/techdebt --format=json     # JSON output for tooling
+/techdebt --format=markdown # Markdown report (default)
+/techdebt --format=sarif    # SARIF for IDE integration
+```
+
+## Troubleshooting
+
+**Issue: Scan times out**
+- Solution: Use `--deep` only on smaller modules, or increase timeout
+- Consider: Break large codebases into smaller scan chunks
+
+**Issue: Too many false positives**
+- Solution: Adjust thresholds in `.claude/techdebt-rules.json`
+- Consider: Use `--ignore-patterns` flag to exclude test files
+
+**Issue: Missing dependencies (ast-grep, etc.)**
+- Solution: Install tools via `npm install -g @ast-grep/cli` or skip category
+- Fallback: Pattern-based detection still works without specialized tools
+
+## Best Practices
+
+1. **Run at every session end** - Catch debt while context is fresh
+2. **Address P0 immediately** - Don't commit critical issues
+3. **Create tasks for P1/P2** - Track technical debt in backlog
+4. **Use baselines for trends** - Monitor debt accumulation over time
+5. **Automate in CI/CD** - Prevent debt from merging
+6. **Educate team** - Share findings, discuss refactoring strategies
+
+## References
+
+See also:
+- [Anthropic's Agent Skills](https://github.com/anthropics/skills) - Subagent patterns
+- [references/patterns.md](references/patterns.md) - Language-specific debt patterns
+- [references/severity-guide.md](references/severity-guide.md) - How to rank findings

skills/techdebt/assets/report-template.md

@@ -0,0 +1,233 @@
+# Tech Debt Report
+
+**Generated:** {timestamp}
+**Scope:** {scope_description}
+**Scan Time:** {duration}
+**Debt Score:** {score}/100
+
+---
+
+## Executive Summary
+
+{summary_paragraph}
+
+**Key Findings:**
+- {finding_count} total issues found
+- {p0_count} critical issues requiring immediate action
+- {p1_count} high-priority issues to address soon
+- Debt score is {trend} compared to baseline
+
+---
+
+## Summary Statistics
+
+| Category | Findings | P0 | P1 | P2 | P3 |
+|----------|----------|----|----|----|----|
+| 🔄 Duplication | {dup_total} | {dup_p0} | {dup_p1} | {dup_p2} | {dup_p3} |
+| 🔒 Security | {sec_total} | {sec_p0} | {sec_p1} | {sec_p2} | {sec_p3} |
+| 📊 Complexity | {cplx_total} | {cplx_p0} | {cplx_p1} | {cplx_p2} | {cplx_p3} |
+| 💀 Dead Code | {dead_total} | {dead_p0} | {dead_p1} | {dead_p2} | {dead_p3} |
+| **Total** | **{total}** | **{p0_total}** | **{p1_total}** | **{p2_total}** | **{p3_total}** |
+
+---
+
+## Critical Issues (P0) 🚨
+
+{if p0_count > 0}
+{for each p0_finding}
+### {file_path}:{line_number}
+
+**Category:** {category}
+**Issue:** {issue_description}
+**Impact:** {impact_description}
+**Recommendation:** {fix_suggestion}
+
+```{language}
+{code_snippet}
+```
+
+**Fix:**
+```{language}
+{fixed_code_snippet}
+```
+
+---
+{end for}
+{else}
+✅ No critical issues found.
+{endif}
+
+---
+
+## High Priority (P1) ⚠️
+
+{if p1_count > 0}
+{for each p1_finding}
+### {file_path}:{line_number}
+
+**Category:** {category}
+**Issue:** {issue_description}
+**Impact:** {impact_description}
+**Recommendation:** {fix_suggestion}
+
+```{language}
+{code_snippet}
+```
+
+---
+{end for}
+{else}
+✅ No high-priority issues found.
+{endif}
+
+---
+
+## Medium Priority (P2) 📋
+
+{if p2_count > 0}
+<details>
+<summary>Show {p2_count} medium-priority findings</summary>
+
+{for each p2_finding}
+### {file_path}:{line_number}
+
+**Category:** {category}
+**Issue:** {issue_description}
+**Fix:** {fix_suggestion}
+
+---
+{end for}
+
+</details>
+{else}
+✅ No medium-priority issues found.
+{endif}
+
+---
+
+## Low Priority (P3) 🧹
+
+{if p3_count > 0}
+<details>
+<summary>Show {p3_count} low-priority findings</summary>
+
+{for each p3_finding}
+- **{file_path}:{line_number}** - {issue_description}
+{end for}
+
+</details>
+{else}
+✅ No low-priority issues found.
+{endif}
+
+---
+
+## Trends
+
+{if baseline_exists}
+### Comparison to Baseline
+
+**Baseline:** {baseline_date} (commit {baseline_commit})
+
+| Metric | Baseline | Current | Change |
+|--------|----------|---------|--------|
+| Debt Score | {baseline_score} | {current_score} | {score_delta} |
+| P0 Issues | {baseline_p0} | {current_p0} | {p0_delta} |
+| P1 Issues | {baseline_p1} | {current_p1} | {p1_delta} |
+| Total Findings | {baseline_total} | {current_total} | {total_delta} |
+
+**Trend:** {trend_description}
+
+{else}
+No baseline found. Run `/techdebt --save-baseline` to start tracking trends.
+{endif}
+
+---
+
+## Recommendations
+
+### Immediate Actions
+
+{if p0_count > 0}
+1. **Address all {p0_count} P0 issues before merging**
+   - These represent security or data integrity risks
+   - Estimated fix time: {p0_fix_time}
+{else}
+✅ No immediate actions required
+{endif}
+
+### Short-Term (This Sprint)
+
+{if p1_count > 0}
+1. **Refactor {high_complexity_count} high-complexity functions**
+   - Start with most frequently modified files
+   - Estimated time: {p1_fix_time}
+
+2. **Eliminate major code duplication**
+   - {dup_p1_count} instances of significant duplication
+   - Extract to shared utilities
+{else}
+✅ No urgent refactoring needed
+{endif}
+
+### Medium-Term (This Quarter)
+
+{if p2_count > 0}
+1. **Code cleanup sprint**
+   - Address {p2_count} medium-priority issues
+   - Focus on {top_p2_category}
+
+2. **Establish debt baseline**
+   - Track trends over time
+   - Set improvement goals
+{endif}
+
+### Long-Term
+
+1. **Prevent new debt**
+   - Add pre-commit hooks for tech debt scanning
+   - Include in CI/CD pipeline
+   - Set quality gates for PRs
+
+2. **Regular debt reviews**
+   - Weekly P1 triage
+   - Monthly full scans
+   - Quarterly architectural reviews
+
+---
+
+## Files Analyzed
+
+{file_list_with_counts}
+
+**Total:** {total_files} files, {total_lines} lines analyzed
+
+---
+
+## Auto-Fix Available
+
+{if auto_fix_count > 0}
+The following {auto_fix_count} issues can be automatically fixed:
+
+{for each auto_fix}
+- [ ] {file_path}:{line_number} - {fix_description}
+{end for}
+
+Run `/techdebt --fix` to apply these changes interactively.
+{else}
+No safe auto-fixes available. All issues require manual review.
+{endif}
+
+---
+
+## Next Steps
+
+1. **Review this report** with your team
+2. **Address P0 issues** immediately
+3. **Create tickets** for P1 findings
+4. **Schedule refactoring** for high-impact areas
+5. **Track progress** with baseline comparisons
+
+---
+
+*Generated by claude-mods techdebt skill v1.0*

skills/techdebt/references/patterns.md

@@ -0,0 +1,480 @@
+# Language-Specific Tech Debt Patterns
+
+Detection patterns for common technical debt across programming languages.
+
+## Python
+
+### Duplication Patterns
+
+**Import duplication:**
+```python
+# Bad: Repeated logic across modules
+# file1.py
+def process_user(user):
+    if not user.email:
+        raise ValueError("Email required")
+    return user.save()
+
+# file2.py
+def update_user(user):
+    if not user.email:
+        raise ValueError("Email required")
+    return user.save()
+
+# Fix: Extract to shared validator
+```
+
+**Algorithm duplication:**
+```python
+# Pattern: Same calculation logic in multiple places
+# Detection: AST similarity >85% for blocks >10 lines
+```
+
+### Security Patterns
+
+**Hardcoded secrets:**
+```python
+API_KEY = "sk-1234567890abcdef"  # P0
+PASSWORD = "admin123"             # P0
+SECRET_TOKEN = "abc" * 10         # P0
+
+# Patterns to detect:
+- Uppercase variables with "KEY", "SECRET", "PASSWORD", "TOKEN"
+- String values matching common secret formats (sk-, ghp_, aws_)
+```
+
+**SQL injection:**
+```python
+# Bad
+query = f"SELECT * FROM users WHERE id={user_id}"  # P0
+cursor.execute("SELECT * FROM users WHERE name='" + name + "'")  # P0
+
+# Good
+cursor.execute("SELECT * FROM users WHERE id=?", (user_id,))
+```
+
+**Insecure crypto:**
+```python
+import hashlib
+hashlib.md5(password)          # P0 - Use bcrypt/scrypt
+hashlib.sha1(password)         # P0 - Use bcrypt/scrypt
+
+import random
+token = random.random()        # P0 - Use secrets module
+
+import pickle
+pickle.loads(user_data)        # P1 - Unsafe deserialization
+
+import yaml
+yaml.load(config)              # P1 - Use yaml.safe_load()
+```
+
+**Path traversal:**
+```python
+# Bad
+file_path = request.GET['file']
+open(file_path)                # P0 - No validation
+
+# Good
+file_path = os.path.basename(request.GET['file'])
+open(os.path.join(SAFE_DIR, file_path))
+```
+
+### Complexity Patterns
+
+**Deeply nested conditionals:**
+```python
+# P1: >5 levels deep
+def process(data):
+    if data:
+        if data.user:
+            if data.user.role:
+                if data.user.role == 'admin':
+                    if data.user.permissions:
+                        if 'delete' in data.user.permissions:
+                            # Action here - 6 levels deep
+                            pass
+
+# Fix: Use guard clauses and early returns
+```
+
+**Long functions:**
+```python
+# P1: >100 lines
+# P2: >50 lines
+# Suggest: Extract method refactoring
+```
+
+**Many parameters:**
+```python
+# P2: >5 parameters
+def create_user(name, email, age, address, phone, role, department):
+    pass
+
+# Fix: Use dataclass or parameter object
+```
+
+### Dead Code Patterns
+
+**Unused imports:**
+```python
+import os          # Used
+import sys         # Unused - P3
+from typing import List  # Used
+from typing import Dict  # Unused - P3
+```
+
+**Unreachable code:**
+```python
+def process():
+    return True
+    print("Never executed")  # P3 - Unreachable
+```
+
+**Unused variables:**
+```python
+def calculate(x, y):
+    result = x + y    # Written but never read - P3
+    return x * y
+```
+
+## JavaScript/TypeScript
+
+### Duplication Patterns
+
+**React component duplication:**
+```typescript
+// Bad: Similar components with slight variations
+const UserCard = ({ user }) => (
+  <div className="card">
+    <h2>{user.name}</h2>
+    <p>{user.email}</p>
+  </div>
+);
+
+const ProductCard = ({ product }) => (
+  <div className="card">
+    <h2>{product.name}</h2>
+    <p>{product.price}</p>
+  </div>
+);
+
+// Fix: Generic Card component with props
+```
+
+### Security Patterns
+
+**XSS vulnerabilities:**
+```typescript
+// Bad
+element.innerHTML = userInput;  // P0
+document.write(userData);       // P0
+$(selector).html(userContent);  // P0
+
+// Good
+element.textContent = userInput;
+```
+
+**Eval usage:**
+```typescript
+eval(userCode);                 // P0
+new Function(userCode)();       // P0
+setTimeout(userCode, 1000);     // P1 if userCode is string
+```
+
+**Insecure random:**
+```typescript
+// Bad
+const token = Math.random().toString(36);  // P0
+
+// Good
+const token = crypto.randomBytes(32).toString('hex');
+```
+
+### Complexity Patterns
+
+**Callback hell:**
+```typescript
+// P2: >3 levels of nesting
+getData((data) => {
+  processData(data, (processed) => {
+    saveData(processed, (result) => {
+      notifyUser(result, (notification) => {
+        // 4 levels deep
+      });
+    });
+  });
+});
+
+// Fix: Use Promises or async/await
+```
+
+**Long switch statements:**
+```typescript
+// P2: >10 cases
+switch (action.type) {
+  case 'ACTION_1': /* ... */ break;
+  case 'ACTION_2': /* ... */ break;
+  // ... 15 more cases
+}
+
+// Fix: Use strategy pattern or object lookup
+```
+
+### Dead Code Patterns
+
+**Unused imports:**
+```typescript
+import React from 'react';        // Used
+import { useState } from 'react'; // Unused - P3
+```
+
+**Dead branches:**
+```typescript
+if (false) {
+  // Never executed - P3
+}
+
+const DEBUG = false;
+if (DEBUG) {
+  // Dead code - P3
+}
+```
+
+## Go
+
+### Duplication Patterns
+
+**Error handling duplication:**
+```go
+// Bad: Repeated error handling
+result1, err := operation1()
+if err != nil {
+    log.Printf("Error in operation1: %v", err)
+    return nil, err
+}
+
+result2, err := operation2()
+if err != nil {
+    log.Printf("Error in operation2: %v", err)
+    return nil, err
+}
+
+// Fix: Extract error handler
+```
+
+### Security Patterns
+
+**SQL injection:**
+```go
+// Bad
+query := "SELECT * FROM users WHERE id=" + userId  // P0
+db.Query(query)
+
+// Good
+db.Query("SELECT * FROM users WHERE id=?", userId)
+```
+
+**Insecure TLS:**
+```go
+// Bad
+&tls.Config{
+    InsecureSkipVerify: true,  // P0
+}
+
+// Good
+&tls.Config{
+    MinVersion: tls.VersionTLS12,
+}
+```
+
+### Complexity Patterns
+
+**Deep interface nesting:**
+```go
+// P2: Multiple type assertions in one function
+func process(data interface{}) {
+    if v, ok := data.(map[string]interface{}); ok {
+        if inner, ok := v["key"].([]interface{}); ok {
+            if item, ok := inner[0].(string); ok {
+                // 3 levels deep
+            }
+        }
+    }
+}
+```
+
+### Dead Code Patterns
+
+**Unused imports:**
+```go
+import (
+    "fmt"  // Used
+    "os"   // Unused - P3
+)
+```
+
+**Unreachable returns:**
+```go
+func process() error {
+    return nil
+    return errors.New("never reached")  // P3
+}
+```
+
+## Rust
+
+### Duplication Patterns
+
+**Error conversion duplication:**
+```rust
+// Bad: Repeated error conversion logic
+let file1 = File::open("file1.txt")
+    .map_err(|e| format!("Failed to open file1: {}", e))?;
+
+let file2 = File::open("file2.txt")
+    .map_err(|e| format!("Failed to open file2: {}", e))?;
+
+// Fix: Extract error conversion helper
+```
+
+### Security Patterns
+
+**Unsafe blocks:**
+```rust
+// P1: Any unsafe block requires review
+unsafe {
+    // Requires careful audit
+}
+```
+
+**Unwrap in production:**
+```rust
+// P2: Unwrap can panic
+let value = result.unwrap();  // P2 - Use ? or match instead
+```
+
+### Complexity Patterns
+
+**Deep match nesting:**
+```rust
+// P2: >4 levels
+match outer {
+    Some(x) => match x {
+        Ok(y) => match y {
+            Some(z) => match z {
+                Valid(v) => {
+                    // 4 levels deep
+                }
+                _ => {}
+            }
+            _ => {}
+        }
+        _ => {}
+    }
+    _ => {}
+}
+
+// Fix: Use if-let chains or early returns
+```
+
+## SQL
+
+### Duplication Patterns
+
+**Repeated CTEs:**
+```sql
+-- Bad: Same CTE in multiple queries
+WITH active_users AS (
+  SELECT * FROM users WHERE status = 'active'
+)
+SELECT * FROM active_users WHERE role = 'admin';
+
+-- Same CTE repeated in another query
+-- Fix: Create materialized view
+```
+
+### Security Patterns
+
+**SQL injection in dynamic SQL:**
+```sql
+-- Bad: String concatenation
+EXECUTE 'SELECT * FROM ' || table_name;  -- P0
+
+-- Good: Use prepared statements
+```
+
+### Complexity Patterns
+
+**Overly complex queries:**
+```sql
+-- P1: >5 JOINs in single query
+-- P2: >3 subqueries nested
+-- Fix: Break into CTEs or temporary tables
+```
+
+## Cross-Language Patterns
+
+### Magic Numbers
+
+**Pattern:** Unexplained numeric constants
+```
+# Any language
+timeout = 3600  # P3 - Should be named constant
+rate_limit = 100  # P3 - Should be config
+```
+
+### TODOs and FIXMEs
+
+**Pattern:** Age-based tracking
+```
+# P1: >90 days old
+# P2: >30 days old
+# P3: <30 days old
+
+# Use git blame to determine age:
+git blame -L <line>,<line> <file> | awk '{print $1}' | xargs git show -s --format=%ci
+```
+
+### Long Functions
+
+**Universal threshold:**
+- P1: >150 lines (any language)
+- P2: >75 lines (any language)
+
+### Commented-Out Code
+
+**Pattern:** Code blocks commented instead of deleted
+```
+// P3: Remove dead code, rely on git history
+/*
+def old_implementation():
+    # 50 lines of commented code
+*/
+```
+
+## Detection Tools by Language
+
+| Language | Duplication | Security | Complexity | Dead Code |
+|----------|-------------|----------|------------|-----------|
+| Python | `ast-grep`, `jscpd` | `bandit`, `semgrep` | `radon`, `mccabe` | `vulture`, `pylint` |
+| JavaScript | `jscpd`, `ast-grep` | `eslint-plugin-security` | `eslint` | `eslint` |
+| TypeScript | `jscpd`, `ast-grep` | `eslint-plugin-security` | `eslint` | `eslint` |
+| Go | `gocyclo`, `ast-grep` | `gosec`, `staticcheck` | `gocyclo` | `golangci-lint` |
+| Rust | `ast-grep` | `cargo-audit`, `clippy` | `cargo-clippy` | `cargo-clippy` |
+| Java | `pmd`, `jscpd` | `spotbugs`, `pmd` | `pmd` | `pmd` |
+
+## Custom Pattern Matching
+
+For languages without specialized tools, use regex patterns:
+
+```python
+# Hardcoded secrets (universal)
+r'(password|passwd|pwd|secret|token|api[_-]?key)\s*=\s*["\'][^"\']{8,}["\']'
+
+# SQL injection markers (universal)
+r'(execute|query|sql)\s*\(\s*["\'].*?\+.*?["\']'
+
+# Magic numbers (universal, excluding 0, 1, -1, 100, 1000)
+r'\b(?!0\b|1\b|-1\b|100\b|1000\b)\d{2,}\b'
+```

skills/techdebt/references/severity-guide.md

@@ -0,0 +1,383 @@
+# Severity Classification Guide
+
+How to rank technical debt findings by severity and impact.
+
+## Severity Levels
+
+| Level | Label | Action Required | Examples |
+|-------|-------|-----------------|----------|
+| **P0** | Critical | Block merge | Security vulnerabilities, data loss risks |
+| **P1** | High | Address soon | Major duplication, high complexity |
+| **P2** | Medium | Plan to fix | Minor duplication, moderate complexity |
+| **P3** | Low | Nice to have | Dead code, style issues, minor TODOs |
+
+## Classification Framework
+
+### Security Issues → P0 (Critical)
+
+**Criteria:**
+- Exposes sensitive data
+- Enables unauthorized access
+- Allows code injection
+- Compromises system integrity
+
+**Examples:**
+- Hardcoded API keys, passwords, tokens
+- SQL injection vulnerabilities
+- XSS vulnerabilities
+- Path traversal risks
+- Insecure cryptography (MD5, SHA1 for passwords)
+- Unsafe deserialization
+- Missing authentication checks
+
+**Action:** Fix immediately, block merge until resolved
+
+### Data Integrity → P0 (Critical)
+
+**Criteria:**
+- Risk of data corruption
+- Inconsistent state possible
+- Transaction safety compromised
+
+**Examples:**
+- Race conditions in critical paths
+- Missing database constraints
+- Improper error handling in transactions
+- Lack of input validation on critical fields
+
+**Action:** Fix before deploying to production
+
+### Major Duplication → P1 (High)
+
+**Criteria:**
+- 30+ lines duplicated
+- Duplicated across 3+ files
+- Core business logic duplicated
+- High maintenance burden
+
+**Impact:**
+- Bug fixes must be applied multiple times
+- Inconsistencies between copies
+- Increased testing burden
+
+**Action:** Refactor within current sprint/milestone
+
+**Refactoring strategies:**
+- Extract shared function/method
+- Create utility module
+- Implement template method pattern
+- Use composition over duplication
+
+### High Complexity → P1 (High)
+
+**Criteria:**
+- Cyclomatic complexity >15
+- Function length >100 lines
+- Nested depth >5 levels
+- Difficult to test/maintain
+
+**Impact:**
+- Bug-prone code
+- Hard to understand and modify
+- Testing becomes expensive
+- Knowledge silos form
+
+**Action:** Simplify when next touching this code
+
+**Refactoring strategies:**
+- Extract method
+- Replace conditionals with polymorphism
+- Introduce guard clauses
+- Break into smaller functions
+
+### Minor Duplication → P2 (Medium)
+
+**Criteria:**
+- 15-30 lines duplicated
+- Duplicated in 2 files
+- Utility/helper logic duplicated
+- Moderate maintenance burden
+
+**Action:** Track in backlog, address during related work
+
+### Moderate Complexity → P2 (Medium)
+
+**Criteria:**
+- Cyclomatic complexity 10-15
+- Function length 50-100 lines
+- Nested depth 4-5 levels
+- Testable but challenging
+
+**Action:** Consider refactoring when adding features
+
+### Dead Code → P3 (Low)
+
+**Criteria:**
+- Unused imports
+- Unreachable code blocks
+- Orphaned functions/classes
+- Commented-out code
+
+**Impact:**
+- Clutter and confusion
+- False positives in searches
+- Maintenance overhead
+- Misleading context
+
+**Action:** Remove during code cleanup sessions
+
+**Safe removal checklist:**
+- Verify no dynamic references (reflection, eval, etc.)
+- Check not part of public API
+- Confirm not referenced in documentation
+- Use git for history, not comments
+
+### Trivial Issues → P3 (Low)
+
+**Criteria:**
+- Minor style inconsistencies
+- Recent TODOs (<30 days old)
+- Small magic numbers
+- Minor naming issues
+
+**Action:** Fix opportunistically or ignore
+
+## Special Cases
+
+### Age-Based Adjustments
+
+**Old TODOs:**
+- >90 days → P1 (likely forgotten, needs resolution)
+- 30-90 days → P2 (track and prioritize)
+- <30 days → P3 (fresh, being actively worked on)
+
+**Rationale:** Old TODOs indicate unresolved design decisions or deferred work that should be addressed.
+
+### Context-Based Adjustments
+
+**Critical paths (auth, payment, data processing):**
+- Elevate all findings by one level
+- P2 complexity → P1 in payment processing
+- P3 dead code → P2 in authentication
+
+**Test code:**
+- Reduce all findings by one level
+- P1 duplication → P2 in test fixtures
+- Allow higher complexity in integration tests
+
+**Example code/documentation:**
+- Ignore most issues
+- Focus only on security P0s
+
+### Team Velocity Adjustments
+
+**Fast-moving startups:**
+- Focus on P0 only
+- Track P1 but don't block
+- P2/P3 for cleanup sprints
+
+**Mature products:**
+- Strict P0/P1 enforcement
+- Regular P2 addressing
+- Zero-debt goal for critical modules
+
+## Decision Matrix
+
+Use this matrix when severity is ambiguous:
+
+| Question | Yes → Higher | No → Lower |
+|----------|-------------|------------|
+| Is this in a critical path? | +1 level | 0 |
+| Does it affect end users directly? | +1 level | 0 |
+| Has this caused bugs before? | +1 level | 0 |
+| Is this code frequently modified? | +1 level | 0 |
+| Would fixing this take >2 hours? | -1 level | 0 |
+| Is there a documented plan to fix? | -1 level | 0 |
+
+**Example:**
+- Base: P2 (moderate complexity in utility function)
+- Critical path? No (0)
+- Affects users? No (0)
+- Caused bugs? Yes (+1 → P1)
+- Frequently modified? Yes (+1 → P0)
+- **Final:** P0 (block merge)
+
+## Auto-Fix Eligibility
+
+Only certain findings can be auto-fixed safely:
+
+**Eligible (with confirmation):**
+- Unused imports (P3)
+- Formatting issues (P3)
+- Simple dead code removal (P3)
+- Magic number extraction to const (P3)
+
+**Not eligible (manual review required):**
+- All security issues (P0)
+- Complexity refactoring (P1/P2)
+- Duplication extraction (P1/P2)
+- Architecture changes (any)
+
+## Reporting Guidelines
+
+### Summary Statistics
+
+Always include in reports:
+
+```
+Total findings: 42
+├─ P0: 2 (BLOCK MERGE)
+├─ P1: 8 (Address soon)
+├─ P2: 15 (Plan to fix)
+└─ P3: 17 (Nice to have)
+
+Debt Score: 38/100 (lower is better)
+```
+
+**Debt Score Formula:**
+```
+Score = (P0 * 50) + (P1 * 10) + (P2 * 5) + (P3 * 1)
+Normalized to 0-100 scale based on codebase size
+```
+
+### Trend Tracking
+
+Show changes over time:
+
+```
+Debt Score: 38 (↓12% from baseline)
+
+Category changes since baseline:
+├─ Duplication: 12 findings (↓3)
+├─ Security: 0 findings (✓ no change)
+├─ Complexity: 18 findings (↑2)
+└─ Dead Code: 12 findings (↓8)
+
+✓ Good: Security issues resolved
+⚠ Watch: Complexity trending up
+```
+
+### Actionable Recommendations
+
+Prioritize by impact:
+
+```
+## Immediate Actions (P0)
+
+1. Remove hardcoded API key in config.py:42
+   └─ Impact: Security breach risk
+   └─ Fix: Move to environment variable
+   └─ Time: 5 minutes
+
+2. Fix SQL injection in users.py:156
+   └─ Impact: Database compromise
+   └─ Fix: Use parameterized query
+   └─ Time: 10 minutes
+
+## High Priority (P1)
+
+3. Refactor process_payment() - 125 lines, complexity 18
+   └─ Impact: Bug-prone, hard to test
+   └─ Fix: Extract validation, calculation, and persistence
+   └─ Time: 2 hours
+
+[... continue with ranked list ...]
+```
+
+## Exceptions and Suppressions
+
+Sometimes technical debt is acceptable:
+
+### Suppress findings
+
+Add comments to justify:
+
+```python
+# techdebt: suppress complexity - intentionally complex
+# reason: Performance-critical path, optimized algorithm
+# reviewed: 2026-02-01 by @username
+def highly_optimized_function():
+    # 150 lines of complex but necessary code
+    pass
+```
+
+**Valid suppression reasons:**
+- Performance optimization (with benchmarks)
+- External API compatibility (can't change)
+- Temporary workaround (with ticket reference)
+- Generated code (with generator version)
+
+**Invalid reasons:**
+- "Will fix later" (create ticket instead)
+- "No time" (prioritize properly)
+- "Works fine" (doesn't address debt)
+
+### Document technical debt decisions
+
+For intentional debt:
+
+```markdown
+## Known Technical Debt
+
+| Component | Issue | Reason | Plan |
+|-----------|-------|--------|------|
+| payment.py | Duplication with refund.py | Rapid prototyping | Refactor in Q2 (PROJ-123) |
+| auth.py | High complexity | Legacy system | Migrate to new auth in v3.0 |
+```
+
+## Review Process
+
+### Pre-Merge Checklist
+
+- [ ] All P0 issues resolved
+- [ ] P1 issues tracked in backlog (with tickets)
+- [ ] Debt score not increased significantly
+- [ ] New code doesn't introduce P0/P1 debt
+
+### Regular Debt Reviews
+
+**Weekly:** Review new P1 findings, prioritize fixes
+
+**Monthly:** Full scan, track trends, set improvement goals
+
+**Quarterly:** Architectural review, major refactorings
+
+## Calibration Examples
+
+Learn from these real-world examples:
+
+**Example 1: Hardcoded secret**
+```python
+API_KEY = "sk-abc123def456"  # Severity: P0
+```
+- Impact: Credential exposure
+- Fix time: 5 minutes
+- Can't wait: Yes
+- **Verdict: P0 (block merge)**
+
+**Example 2: Duplicated validation (30 lines, 3 files)**
+```python
+# Same 30-line validation in user.py, admin.py, api.py
+```
+- Impact: Inconsistent validation
+- Fix time: 1 hour
+- Can wait: Until next feature in module
+- **Verdict: P1 (address soon)**
+
+**Example 3: Complex function (95 lines, complexity 12)**
+```python
+def process_order():  # 95 lines, complexity 12
+```
+- Impact: Hard to modify
+- Fix time: 2 hours
+- Can wait: Yes, if tests are good
+- **Verdict: P2 (plan to fix)**
+
+**Example 4: Unused import**
+```python
+import os  # Never used
+```
+- Impact: Clutter
+- Fix time: 1 second
+- Can wait: Yes
+- **Verdict: P3 (clean up when convenient)**