dev.tech-debt-review

Detect AI/agentic-specific tech debt that traditional linters miss.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Usage Modes

| Mode | Command | Scope | When to Use | |------|---------|-------|-------------| | Changed Files | /dev.tech-debt-review | Files changed vs main | Before PR (default) | | Full Audit | /dev.tech-debt-review --all | Full src/ directory | Release gate, quarterly review | | Category Focus | /dev.tech-debt-review --category=boundary | Specific category | Targeted cleanup |

Categories: boundary, prompt, context, testing, error, state, observability, subagent

Goal

Detect AI/agentic-specific anti-patterns that traditional linters miss:

| Category | What It Finds | Why It Matters | |----------|---------------|----------------| | Tool/Agent Boundary | Tools making decisions, encoding thresholds | Violates Constitution VII | | Prompt Debt | Hardcoded prompts, no versioning, injection risks | Maintenance nightmare | | Context Window | Unbounded data, no truncation, raw dumps | Performance/reliability | | Testing | Live LLM in unit tests, missing VCR, no evals | CI flakiness, cost | | Error Handling | No retry/backoff, missing timeouts | Reliability | | State Management | Unbounded conversation history | Memory leaks | | Observability | No tracing, missing metrics | Debugging blind spots | | Subagent | Depth > 1, unclear boundaries | Architecture violation |

Traditional linters catch syntax and style. This skill catches semantic anti-patterns specific to agentic systems.

Operating Constraints

STRICTLY READ-ONLY: Do not modify any files. Output analysis and recommendations.

SEMANTIC ANALYSIS: Read and understand code patterns, don't just grep.

EVIDENCE-BASED: Every finding must cite file:line and code snippet.

SCORING: Aggregate findings into 0-100 score for PR gate decisions.

Constitution Alignment

This skill validates adherence to project principles:

| Principle | What We Check | |-----------|---------------| | I. Local-First | No data transmission, security of prompts | | III. Causal-First | Recommendations trace to evidence | | VII. Intelligent Tooling | Tools provide data, agent provides judgment | | VIII. Compounding Value | Historical tracking of tech debt | | IX. Agent-Aware | Context optimized for agent cognition |

Reference: Constitution Mapping

Execution Steps

Phase 0: Scope Determination

You handle this phase directly.

Parse user input to determine scope:

If --all flag present: Full codebase audit

find src -name "*.ts" -type f | grep -v ".d.ts" | grep -v "node_modules"

If --category=X flag present: Filter to that category's patterns only
If specific file path provided: Analyze that file
```
ls -la <provided-path>
```

Default (no args): Changed files only

git diff --name-only main...HEAD | grep -E '\.tsx?$'

Report mode to user:

--all mode: "Running FULL CODEBASE audit on N files"
--category=X: "Running targeted audit for category: X"
Default: "Reviewing N files changed vs main"

Load context:

Read .specify/memory/constitution.md for principle references
Check for previous review at .claude/reviews/tech-debt-*.json for trend comparison

Phase 1: Parallel Category Analysis (Subagents)

Invoke 8 category-specific analyzers IN PARALLEL (single message, multiple Task calls).

Each subagent focuses on one category. Use Haiku for single-file analysis, Sonnet for cross-file patterns.

Task(boundary-analyzer, model=haiku, "Analyze files for Tool/Agent Boundary violations.

PATTERNS TO DETECT:
- JUDGMENT_IN_TOOL: Functions that return judgments ('good', 'bad', 'low', 'high')
- ORCHESTRATION_IN_TOOL: Tools that decide when/how to call other tools
- THRESHOLD_ENCODING: Hardcoded thresholds that encode decisions (if score < 0.3)
- DECISION_RETURN: Functions returning 'suggestedAction', 'shouldDo', etc.

FILES: [list]

For each finding, return:
- pattern: The pattern code (e.g., JUDGMENT_IN_TOOL)
- file: Absolute path
- line: Line number
- snippet: The offending code (max 5 lines)
- evidence: Why this matches the pattern

Return JSON array of findings. Return empty array if no issues.")

Task(prompt-analyzer, model=haiku, "Analyze files for Prompt Debt.

PATTERNS TO DETECT:
- HARDCODED_PROMPT: Prompt strings embedded directly in code (not in prompt files)
- NO_VERSIONING: Prompts without version tracking or timestamps
- INJECTION_RISK: User input concatenated into prompts without sanitization
- PROMPT_SPRAWL: Same prompt logic duplicated in multiple places

FILES: [list]

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Task(context-analyzer, model=haiku, "Analyze files for Context Window issues.

PATTERNS TO DETECT:
- UNBOUNDED_DATA: Arrays/objects passed to agent without size limits
- NO_SUMMARIZATION: Large data returned without truncation/summarization
- RAW_DUMP: Tool returning raw data structures instead of formatted summaries
- CONTEXT_BLOAT: Unnecessary verbose output in tool responses

FILES: [list]

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Task(testing-analyzer, model=haiku, "Analyze files for Testing Anti-patterns.

PATTERNS TO DETECT:
- LIVE_LLM_IN_UNIT: Unit tests that make real LLM API calls
- MISSING_VCR: Integration tests without VCR recordings
- MISSING_EVAL: Behavioral scenarios without TruLens evals
- FLAKY_ASSERTION: Tests asserting on non-deterministic LLM output
- NO_MOCK: Tests calling real external services

FILES: [list]
ADR-0011 Reference: Unit=mocked, Integration=VCR, E2E/Evals=live

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Task(error-analyzer, model=haiku, "Analyze files for Error Handling issues.

PATTERNS TO DETECT:
- NO_RETRY_LOGIC: LLM API calls without retry/backoff
- MISSING_TIMEOUT: API calls without timeout configuration
- SILENT_FAILURE: Errors caught but not logged/propagated
- UNHANDLED_REJECTION: Async operations without error handling
- GENERIC_CATCH: catch(e) without specific error handling

FILES: [list]

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Task(state-analyzer, model=haiku, "Analyze files for State Management issues.

PATTERNS TO DETECT:
- UNBOUNDED_HISTORY: Conversation history without max length
- MEMORY_LEAK: Growing state structures without cleanup
- NO_CHECKPOINT: Long-running operations without checkpointing
- STALE_STATE: Cached state without invalidation strategy

FILES: [list]

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Task(observability-analyzer, model=haiku, "Analyze files for Observability gaps.

PATTERNS TO DETECT:
- NO_TRACING: LLM calls without trace/span context
- MISSING_METRICS: No token counting, latency tracking
- NO_DEBUG_LOG: Complex operations without debug logging
- OPAQUE_ERROR: Errors without context for debugging

FILES: [list]

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Task(subagent-analyzer, model=sonnet, "Analyze files for Subagent Architecture violations.

PATTERNS TO DETECT:
- DEPTH_VIOLATION: Subagents spawning sub-subagents (depth > 1)
- UNCLEAR_BOUNDARY: Subagent with multiple unrelated responsibilities
- MISSING_ISOLATION: Subagent sharing mutable state with parent
- RECURSIVE_SPAWN: Agents that can spawn themselves

FILES: [list]
Constitution C8 Reference: Subagent depth limited to 1

Return JSON array of findings with pattern, file, line, snippet, evidence.")

Wait for all subagents to return.

Phase 2: Constitution Cross-Reference

You handle this phase directly.

For each finding from Phase 1, map to Constitution principles:

Reference: Constitution Mapping

| Pattern | Principle | Severity Modifier | |---------|-----------|-------------------| | JUDGMENT_IN_TOOL | VII | +2 (direct violation) | | ORCHESTRATION_IN_TOOL | VII | +3 (critical) | | INJECTION_RISK | I | +5 (security) | | DEPTH_VIOLATION | C8 | +4 (architecture) | | LIVE_LLM_IN_UNIT | ADR-0011 | +3 (testing strategy) |

Phase 3: Severity Scoring

You handle this phase directly.

Base deductions per finding type:

Reference: Severity Criteria

| Category | Pattern | Base Deduction | |----------|---------|----------------| | Boundary | JUDGMENT_IN_TOOL | -8 | | Boundary | ORCHESTRATION_IN_TOOL | -10 | | Boundary | THRESHOLD_ENCODING | -6 | | Prompt | HARDCODED_PROMPT | -3 | | Prompt | INJECTION_RISK | -15 | | Prompt | PROMPT_SPRAWL | -4 | | Context | UNBOUNDED_DATA | -7 | | Context | RAW_DUMP | -5 | | Testing | LIVE_LLM_IN_UNIT | -10 | | Testing | MISSING_VCR | -6 | | Testing | MISSING_EVAL | -8 | | Error | NO_RETRY_LOGIC | -6 | | Error | SILENT_FAILURE | -8 | | State | UNBOUNDED_HISTORY | -10 | | State | NO_CHECKPOINT | -5 | | Observability | NO_TRACING | -5 | | Observability | MISSING_METRICS | -4 | | Subagent | DEPTH_VIOLATION | -12 |

Scoring formula:

score = max(0, 100 - sum(deductions))

Score interpretation:

| Score | Grade | Action | |-------|-------|--------| | 90-100 | A | Ship it | | 80-89 | B | Minor cleanup before merge | | 70-79 | C | Plan remediation sprint | | 60-69 | D | Urgent fixes needed | | < 60 | F | Block release |

Phase 4: Generate Report

You handle this phase directly.

Output format:

## Tech Debt Review Report

**Score**: XX/100 (Grade: X)
**Trend**: [+/-N vs last review] or [First review - no trend data]
**Files Analyzed**: N
**Scope**: [changed files | full codebase | category: X]

---

### Executive Summary

| Category | Findings | Impact | Constitution |
|----------|----------|--------|--------------|
| Boundary | N | -XX | VII |
| Testing | N | -XX | ADR-0011 |
| ... | ... | ... | ... |
| **Total** | **N** | **-XX** | |

---

### P0 - Block Release

These issues MUST be fixed before merge:

#### [PATTERN_CODE] in file.ts:123

**Code:**
```typescript
// The offending code snippet

Problem: [Why this is an anti-pattern]

Constitution: Violates Principle [X]

Remediation: [Specific fix guidance]

P1 - This Sprint

[Summary findings - less detail than P0]

P2 - Backlog

| Pattern | File | Line | Category | |---------|------|------|----------| | ... | ... | ... | ... |

Historical Trend

| Date | Score | Grade | Change | |------|-------|-------|--------| | [today] | XX | X | - | | [prev] | XX | X | +/-N |

Anti-Pattern Reference

See: AI Anti-Patterns Guide


---

### Phase 5: Save Historical Data

**You handle this phase directly.**

Save review results to `.claude/reviews/tech-debt-YYYY-MM-DD.json`:

```json
{
  "version": "1.0.0",
  "timestamp": "2026-01-26T14:30:00Z",
  "scope": "changed_files|all|category:X",
  "filesAnalyzed": 145,
  "score": 78,
  "grade": "C",
  "categories": {
    "boundary": { "findings": 3, "impact": -23 },
    "testing": { "findings": 5, "impact": -30 },
    ...
  },
  "findings": [
    {
      "pattern": "JUDGMENT_IN_TOOL",
      "category": "boundary",
      "file": "src/tools/analyzer.ts",
      "line": 42,
      "snippet": "...",
      "severity": 8
    }
  ],
  "trend": {
    "previousScore": 72,
    "previousDate": "2026-01-19",
    "change": 6
  }
}

Integration with Other Skills

| Skill | Relationship | |-------|--------------| | /dev.test-review | Complementary - test-review checks test quality, tech-debt-review checks testing anti-patterns | | /dev.verify-wiring | Sequential - verify-wiring first, then tech-debt-review | | /arch-review | Parallel - different focus areas | | /dev.pr | Gate - score threshold can block PR |

Suggested workflow:

/dev.verify-wiring → /dev.tech-debt-review → /dev.test-review → /dev.pr

Red Flags (Auto-Fail)

These patterns automatically set grade to F:

| Pattern | Why | |---------|-----| | INJECTION_RISK | Security vulnerability | | DEPTH_VIOLATION | Architecture violation | | Multiple ORCHESTRATION_IN_TOOL | Fundamental design issue |

References

Handoff

After running this skill:

Grade A/B: Proceed to /dev.pr
Grade C: Review findings, plan fixes, proceed if time-boxed
Grade D/F: Fix critical issues, re-run before PR

dev-tech-debt-review

dev.tech-debt-review

User Input

Usage Modes

Goal

Operating Constraints

Constitution Alignment

Execution Steps

Phase 0: Scope Determination

Phase 1: Parallel Category Analysis (Subagents)

Phase 2: Constitution Cross-Reference

Phase 3: Severity Scoring

Phase 4: Generate Report

P1 - This Sprint

P2 - Backlog

Historical Trend

Anti-Pattern Reference

Integration with Other Skills

Red Flags (Auto-Fail)

References

Handoff