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"

18. Partial Internal Mocks (AP-6 Violations)

# vi.importActual is a sign of partial mocking — usually wrong
grep -r 'vi\.importActual' turbo --include="*.test.ts" --include="*.test.tsx" -l

19. Direct Component Rendering (AP-10 Violations)

# Platform test files using render() instead of setupPage — misses production bootstrap
grep -r 'render(' turbo/apps/platform --include="*.test.tsx" -l

20. Direct Database Operations in Tests

# Tests should use API helpers, not direct DB insert/update/delete
grep -r 'globalThis\.services\.db\.\(insert\|update\|delete\)' turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

21. Tests Importing Internal Services

# Test files importing from internal lib/ — means testing implementation, not behavior
grep -rE "from.*['\"].*lib/infra|from.*['\"].*lib/zero" turbo \
  --include="*.test.ts" --include="*.test.tsx" -l

22. initServices() in Tests

# Route tests should never call initServices() directly — API helpers handle it
grep -r 'initServices()' turbo --include="*.test.ts" --include="*.test.tsx" -l

23. ccstate-react/experimental in Views (eslint-disable)

# Views files suppressing ccstate/no-use-ccstate-in-views — pending migration
grep -rl "eslint-disable ccstate/no-use-ccstate-in-views" turbo/apps/platform/src/views/

24. void Instead of detach() for Floating Promises

# Using void to suppress floating promise lint — should use detach() with Reason
grep -rEn 'void [a-zA-Z_$][a-zA-Z0-9_$]*\(' turbo/apps/platform --include="*.ts" --include="*.tsx" -l

25. Manual Loading Boolean in Signals

# Manual loading/saving boolean state — should use useLoadableSet or loadable pattern
# Match signal names following the loading$/saving$/submitting$/creating$/deleting$ convention
grep -rEn '\b(loading|saving|submitting|creating|deleting)\$\s*=\s*state\(' turbo/apps/platform/src/signals --include="*.ts" -l

26. Orphaned resetSignal (No Parent Signal)

# resetSignal called without parent signal — causes polling loops that never stop
# Match set(resetXxx$) calls with no arguments after the signal name (no comma = no parent)
grep -rEn 'set\(reset[A-Za-z0-9_]*\$\)' turbo/apps/platform/src/signals --include="*.ts"

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 (use setupPage, not render())
• AP-11: Direct Database Operations in Tests (use API helpers)
• AP-12: Importing Internal Services in Tests (tests internal implementation)
• AP-13: initServices() in Tests (API helpers handle it)

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)

ccstate Anti-Patterns:

• CS-1: ccstate-react/experimental in views (pending migration to signals)
• CS-2: void instead of detach() (floating promises not tracked for cleanup)
• CS-3: Manual loading boolean in signals (use useLoadableSet or loadable pattern)
• CS-4: Orphaned resetSignal without parent (causes polling leaks)
• CS-5: Manual state synchronization (command sets multiple related states — use computed)

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
  • AP-6: Partial internal mocks (vi.importActual)
  • AP-11: Direct database operations in tests
  • AP-12: Importing internal services in tests
  • AP-13: initServices() in tests
  • CS-1: ccstate-react/experimental in views (pending migration)
  • CS-2: void instead of detach() (untracked floating promises)
  • CS-3: Manual loading boolean in signals
  • CS-4: Orphaned resetSignal without parent signal
• Medium (P2): Issues that should be addressed
  • Files >1000 lines
  • Fallback patterns
  • AP-1: Testing mock calls
  • AP-5: Fake timers
  • AP-10: Direct component rendering (use setupPage)
  • CS-5: Manual state synchronization (use computed)
• Low (P3):

---

Content truncated.