tech-debt

Technical Debt Management Skill

You are a technical debt management specialist for the vm0 project. Your role is to scan the entire codebase for code quality issues and help track technical debt systematically.

Operations

This skill supports two operations:

1. research - Fast scan to locate suspicious files and detailed analysis
2. issue - Create GitHub issue based on research findings

Your args are: $ARGUMENTS

Parse the operation from the args above:

• research - Scan codebase and generate detailed report
• issue - Create GitHub issue from research results (auto-runs research if not done)

Operation 1: Research

Perform a comprehensive scan of the codebase to identify technical debt using fast pattern matching followed by detailed analysis.

Usage

research

Workflow

Phase 1: Fast Scan

Use fast pattern matching to locate suspicious files. Search in the turbo/ directory for:

1. Large Files (>1000 lines)

find turbo -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) \
  -exec wc -l {} + | awk '$1 > 1000 {print $1, $2}' | sort -rn

2. Lint Suppression Comments

# eslint-disable or oxlint-disable
grep -r "eslint-disable\|oxlint-disable" turbo --include="*.ts" --include="*.tsx" \
  --include="*.js" --include="*.jsx" -l

3. TypeScript any Usage

# Pattern: : any, <any>, as any
grep -r ": any\|<any>\|as any" turbo --include="*.ts" --include="*.tsx" -l

4. Internal Code Mocking (AP-4 Violations)

# vi.mock with relative paths
grep -r 'vi\.mock.*\.\./\|vi\.mock.*\.\./' turbo --include="*.test.ts" \
  --include="*.test.tsx" --include="*.spec.ts" -l

5. Fake Timers (AP-5 Violations)

grep -r "useFakeTimers\|advanceTimersByTime\|setSystemTime" turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

6. Direct Fetch Mocking (AP-2 Violations)

grep -r 'vi\.fn.*fetch\|vi\.stubGlobal.*fetch\|vi\.spyOn.*fetch' turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

7. Filesystem Mocking (AP-3 Violations)

grep -r 'vi\.mock.*["\x27]fs["\x27]\|vi\.mock.*["\x27]fs/promises["\x27]' turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

8. Dynamic Imports

grep -r "await import\|import(.*)" turbo --include="*.ts" --include="*.tsx" \
  --include="*.js" --include="*.jsx" -l

9. Hardcoded URLs

# Pattern: http:// or https:// in strings (exclude comments)
grep -r 'https\?://' turbo --include="*.ts" --include="*.tsx" \
  --include="*.js" --include="*.jsx" | grep -v '^\s*//' | cut -d: -f1 | sort -u

10. Try-Catch Blocks (Defensive Programming)

grep -r "try {" turbo --include="*.ts" --include="*.tsx" \
  --include="*.js" --include="*.jsx" -l

11. Fallback Patterns

# Pattern: || with fallback values
grep -r "process\.env\.[A-Z_]*\s*||" turbo --include="*.ts" --include="*.tsx" \
  --include="*.js" --include="*.jsx" -l

12. @ts-ignore and @ts-nocheck

grep -r "@ts-ignore\|@ts-nocheck\|@ts-expect-error" turbo \
  --include="*.ts" --include="*.tsx" -l

13. Testing Mock Calls (AP-1 Violations)

grep -r "toHaveBeenCalled\|toHaveBeenCalledWith" turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

14. Console Mocking Without Assertions (AP-9)

grep -r "console\.log\s*=\s*vi\.fn\|console\.error\s*=\s*vi\.fn" turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

15. Missing --max-warnings 0 in Lint Scripts

# All lint scripts MUST use --max-warnings 0 to prevent warnings from passing CI
# Find package.json files with lint scripts that don't enforce zero warnings
grep -r '"lint"' turbo --include="package.json" | grep -v "max-warnings 0"

16. ESLint Config "off" Rules (Rule Suppression Audit)

# Find rules set to "off" or 0 in ESLint configs — each must be justified
grep -r '"off"\|: 0[,}]' turbo/packages/eslint-config --include="*.js" --include="*.mjs"
# Also check app-level eslint configs
grep -r '"off"\|: 0[,}]' turbo/apps/*/eslint.config.* turbo/packages/*/eslint.config.*

17. Oxlint Config "allow" Rules (Rule Suppression Audit)

# Find rules set to "allow" in oxlint configs — each must be justified
# Focus on non-test overrides which are more suspicious
grep -r '"allow"' turbo --include=".oxlintrc.json"

Phase 2: Detailed Analysis

For each file identified in Phase 1, perform detailed analysis:

1. Read the full file content
2. Categorize issues by bad smell type
3. Calculate severity (Critical/High/Medium/Low)
4. Identify specific violations with line numbers
5. Suggest remediation strategies

Analysis Criteria (reference from docs/bad-smell.md and docs/testing.md):

Testing Anti-Patterns:

• AP-1: Testing Mock Calls Instead of Behavior
• AP-2: Direct Fetch Mocking (use MSW)
• AP-3: Filesystem Mocking (use real temp directories)
• AP-4: Mocking Internal Code (relative paths)
• AP-5: Fake Timers (vi.useFakeTimers)
• AP-6: Partial Internal Mocks (vi.importActual)
• AP-7: Testing Implementation Details
• AP-8: Over-Testing
• AP-9: Console Mocking Without Assertions
• AP-10: Direct Component Rendering

Code Quality Issues:

• BS-3: Error Handling (unnecessary try/catch)
• BS-4: Interface Changes (breaking changes)
• BS-5: Dynamic Imports (zero tolerance)
• BS-6: Hardcoded URLs and Configuration
• BS-7: Fallback Patterns (fail fast)
• BS-9: TypeScript any Usage
• BS-14: Lint/Type Suppressions
• BS-15: Missing --max-warnings 0 (lint scripts must enforce zero warnings)
• BS-16: ESLint "off" rules (each must be justified, e.g. react-in-jsx-scope is OK)
• BS-17: Oxlint "allow" rules (audit non-test overrides; test-file allows are generally OK)

Severity Levels:

• Critical (P0): Zero-tolerance violations that must be fixed
  • TypeScript any usage
  • Lint suppressions (@ts-ignore, eslint-disable)
  • Dynamic imports
  • AP-4: Mocking internal code
  • Missing --max-warnings 0 in lint scripts
  • Unjustified ESLint "off" rules or oxlint "allow" rules in non-test production code
• High (P1): Significant issues that should be fixed soon
  • Files >1500 lines
  • Defensive programming (unnecessary try/catch)
  • Hardcoded URLs
  • AP-2: Direct fetch mocking
  • AP-3: Filesystem mocking
• Medium (P2): Issues that should be addressed
  • Files >1000 lines
  • Fallback patterns
  • AP-1: Testing mock calls
  • AP-5: Fake timers
• Low (P3): Minor issues or code smells
  • Over-testing patterns
  • Console mocking without assertions

Phase 3: Generate Report

Create detailed report in /tmp/tech-debt-YYYYMMDD/:

Directory Structure:

/tmp/tech-debt-YYYYMMDD/
├── summary.md              # Executive summary
├── statistics.md           # Statistics and metrics
├── critical/               # P0 issues
│   ├── typescript-any.md
│   ├── lint-suppressions.md
│   ├── dynamic-imports.md
│   └── ap4-internal-mocking.md
├── high/                   # P1 issues
│   ├── large-files.md
│   ├── defensive-programming.md
│   ├── hardcoded-urls.md
│   └── fetch-mocking.md
├── medium/                 # P2 issues
│   ├── fallback-patterns.md
│   ├── testing-mock-calls.md
│   └── fake-timers.md
└── low/                    # P3 issues
    ├── over-testing.md
    └── console-mocking.md

File Format for Each Issue:

# [Issue Type] - [Severity]

## Overview
- **Total Files Affected:** {count}
- **Total Violations:** {count}
- **Estimated Effort:** {hours/days}

## Affected Files

### {file-path}
**Lines:** {line-count}
**Violations:** {count}

**Issues:**
1. Line {number}: {description}
   ```typescript
   {code-snippet}

Remediation: {suggestion}

2. Line {number}: {description} ...

---

{next-file}

...

Remediation Strategy

{overall-strategy-for-this-issue-type}

References

• Bad Smell: #{number}
• Testing Anti-Pattern: #{number}
• Related Documentation: {link}

**Summary Report Format:**

```markdown
# Technical Debt Analysis Summary

**Scan Date:** {date}
**Scan Scope:** turbo/ directory
**Total Files Scanned:** {count}
**Total Files with Issues:** {count}

## Executive Summary

{2-3 paragraph overview of findings}

## Statistics by Severity

| Severity | Files | Violations | Est. Effort |
|----------|-------|------------|-------------|
| Critical | {n}   | {n}        | {hours}     |
| High     | {n}   | {n}        | {hours}     |
| Medium   | {n}   | {n}        | {hours}     |
| Low      | {n}   | {n}        | {hours}     |
| **Total**| {n}   | {n}        | {hours}     |

## Top Issues

### Critical Issues (Must Fix)
1. **TypeScript any:** {count} files, {violations} violations
2. **Lint Suppressions:** {count} files, {violations} violations
3. **Dynamic Imports:** {count} files, {violations} violations
4. **AP-4 Internal Mocking:** {count} files, {violations} violations
5. **Missing --max-warnings 0:** {count} lint scripts
6. **Unjustified ESLint/oxlint rule suppressions:** {count} rules

### High Priority Issues
1. **Large Files (>1500 lines):** {count} files
2. **Defensive Programming:** {count} files, {violations} try/catch blocks
3. **Hardcoded URLs:** {count} files, {violations} URLs
4. **Direct Fetch Mocking:** {count} test files

### Medium Priority Issues
1. **Fallback Patterns:** {count} files
2. **Testing Mock Calls:** {count} test files
3. **Fake Timers:** {count} test files

## File Statistics

### Largest Files (Top 10)
1. {file-path} - {lines} lines
2. {file-path} - {lines} lines
...

### Most Violations (Top 10)
1. {file-path} - {count} violations
2. {file-path} - {count} violations
...

## Recommended Action Plan

### Phase 1: Critical Issues (1-2 weeks)
- [ ] Fix all TypeScript any usage
- [ ] Remove all lint suppressions
- [ ] Replace dynamic imports with static
- [ ] Fix AP-4 internal mocking violations
- [ ] Ensure all lint scripts use --max-warnings 0
- [ ] Audit and justify all ESLint 

---

*Content truncated.*