Menu
Technical debt management - scan codebase for bad smells and create tracking issues
The review-first prompt is selected by default. You can switch to a direct command or download a local copy.
Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/vm0-ai/vm0 --skill tech-debtThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Showing SKILL.md
Based on SOC occupation classification
| name | tech-debt |
| description | Technical debt management - scan codebase for bad smells and create tracking issues |
| context | fork |
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.
This skill supports two operations:
Your args are: $ARGUMENTS
Parse the operation from the args above:
research - Scan codebase and generate detailed reportissue - Create GitHub issue from research results (auto-runs research if not done)Perform a comprehensive scan of the codebase to identify technical debt using fast pattern matching followed by detailed analysis.
research
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" \) \
- -l {} + | awk | -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"
For each file identified in Phase 1, perform detailed analysis:
Analysis Criteria (reference from docs/bad-smell.md and docs/testing.md):
Testing Anti-Patterns:
Code Quality Issues:
ccstate Anti-Patterns:
Severity Levels:
any usage--max-warnings 0 in lint scriptsCreate 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}
...
{overall-strategy-for-this-issue-type}
**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
5. **Partial Internal Mocks (AP-6):** {count} test files
6. **Direct DB Operations in Tests:** {count} test files
7. **Internal Service Imports in Tests:** {count} test files
8. **initServices() in Tests:** {count} test files
9. **ccstate-react/experimental in Views:** {count} view files
10. **void Instead of detach():** {count} files
11. **Manual Loading Boolean:** {count} signal files
12. **Orphaned resetSignal:** {count} occurrences
### Medium Priority Issues
1. **Fallback Patterns:** {count} files
2. **Testing Mock Calls:** {count} test files
3. **Fake Timers:** {count} test files
4. **Direct Component Rendering (AP-10):** {count} test files
5. **Manual State Synchronization:** {count} signal 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 "off" / oxlint "allow" rules
### Phase 2: High Priority (2-4 weeks)
- [ ] Refactor files >1500 lines
- [ ] Remove defensive try/catch blocks
- [ ] Replace hardcoded URLs with config
- [ ] Convert fetch mocks to MSW
### Phase 3: Medium Priority (1-2 months)
- [ ] Remove fallback patterns
- [ ] Fix testing mock call assertions
- [ ] Replace fake timers
### Phase 4: Low Priority (ongoing)
- [ ] Address over-testing patterns
- [ ] Clean up console mocking
## Detailed Reports
- [Critical Issues](./critical/)
- [High Priority Issues](./high/)
- [Medium Priority Issues](./medium/)
- [Low Priority Issues](./low/)
---
*Generated by tech-debt skill on {date}*
After generating detailed reports, provide a medium-detail summary to the user:
# Technical Debt Scan Complete
## Scan Results
**Total Files Scanned:** {count}
**Files with Issues:** {count}
**Total Violations:** {count}
## By Severity
- **Critical (P0):** {count} files, {violations} violations
- **High (P1):** {count} files, {violations} violations
- **Medium (P2):** {count} files, {violations} violations
- **Low (P3):** {count} files, {violations} violations
## Top 5 Critical Issues
1. **TypeScript any** - {count} files
- {file-path}:{line} - {brief-description}
- {file-path}:{line} - {brief-description}
2. **Lint Suppressions** - {count} files
- {file-path}:{line} - {brief-description}
- {file-path}:{line} - {brief-description}
3. **Dynamic Imports** - {count} files
- {file-path}:{line} - {brief-description}
4. **AP-4 Internal Mocking** - {count} files
- {file-path}:{line} - {brief-description}
5. **Large Files** - {count} files
- {file-path} - {lines} lines
- {file-path} - {lines} lines
## Detailed Reports
All detailed analysis has been saved to `/tmp/tech-debt-{date}/`
- Summary: `/tmp/tech-debt-{date}/summary.md`
- Statistics: `/tmp/tech-debt-{date}/statistics.md`
- Critical issues: `/tmp/tech-debt-{date}/critical/`
- High priority: `/tmp/tech-debt-{date}/high/`
## Next Steps
Run `tech-debt issue` to create a GitHub issue tracking these findings.
Efficiency Tips:
grep -l (files only) for fast scanningwc -l for line countsAccuracy Tips:
node_modules and .git directories\b) for precisionCreate a GitHub issue based on research findings. If research hasn't been run, automatically run it first.
issue
# Check if research was already done today
LATEST_REPORT=$(ls -td /tmp/tech-debt-* 2>/dev/null | head -1)
if [ -z "$LATEST_REPORT" ]; then
echo "No research found. Running research first..."
# Run research operation
else
echo "Using existing research from: $LATEST_REPORT"
fi
Read research reports and prepare GitHub issue content:
Issue Title:
[Tech Debt] Codebase Quality Scan - {date}
Issue Body Structure:
# Technical Debt Analysis - {date}
This issue tracks technical debt identified through automated codebase scanning.
## Executive Summary
{paste-from-summary.md}
## Statistics
{paste-from-statistics.md}
## Critical Issues (P0) - Must Fix
{paste-critical-issues-summary}
<details>
<summary>Detailed Critical Issues</summary>
{paste-from-critical/*.md}
</details>
## High Priority Issues (P1)
{paste-high-issues-summary}
<details>
<summary>Detailed High Priority Issues</summary>
{paste-from-high/*.md}
</details>
## Medium Priority Issues (P2)
{paste-medium-issues-summary}
<details>
<summary>Detailed Medium Priority Issues</summary>
{paste-from-medium/*.md}
</details>
## Action Plan
### Phase 1: Critical Issues (Target: 1-2 weeks)
- [ ] Fix TypeScript any usage ({count} files)
- [ ] Remove lint suppressions ({count} files)
- [ ] Replace dynamic imports ({count} files)
- [ ] Fix internal mocking violations ({count} files)
- [ ] Ensure all lint scripts use --max-warnings 0 ({count} scripts)
- [ ] Audit ESLint "off" / oxlint "allow" rules ({count} rules)
### Phase 2: High Priority (Target: 2-4 weeks)
- [ ] Refactor large files ({count} files)
- [ ] Remove defensive programming ({count} blocks)
- [ ] Replace hardcoded URLs ({count} files)
- [ ] Convert fetch mocks to MSW ({count} files)
- [ ] Remove vi.importActual usage ({count} files)
- [ ] Replace direct DB operations in tests with API helpers ({count} files)
- [ ] Remove internal service imports from tests ({count} files)
- [ ] Remove initServices() from tests ({count} files)
- [ ] Migrate ccstate-react/experimental out of views ({count} files)
- [ ] Replace void with detach() ({count} files)
- [ ] Replace manual loading booleans with useLoadableSet ({count} files)
- [ ] Fix orphaned resetSignal calls ({count} occurrences)
### Phase 3: Medium Priority (Target: 1-2 months)
- [ ] Remove fallback patterns ({count} files)
- [ ] Fix testing mock assertions ({count} files)
- [ ] Replace fake timers ({count} files)
- [ ] Replace direct component rendering with setupPage ({count} files)
- [ ] Refactor manual state synchronization to computed ({count} files)
## Labels
`tech-debt` `quality` `refactoring`
---
**Scan Details:**
- Date: {date}
- Scope: turbo/ directory
- Total files scanned: {count}
- Total violations: {count}
**References:**
- Bad Smell Documentation: `/docs/bad-smell.md`
- Testing Guidelines: `/docs/testing.md`
Single Issue Strategy:
If total content is under GitHub issue size limit (~65K characters):
gh issue create \
--title "[Tech Debt] Codebase Quality Scan - $(date +%Y-%m-%d)" \
--body-file /tmp/tech-debt-{date}/github-issue-body.md \
--label "tech-debt,quality,refactoring"
Multiple Comments Strategy:
If content exceeds size limit, create issue with summary and post detailed sections as comments:
# 1. Create issue with executive summary
ISSUE_URL=$(gh issue create \
--title "[Tech Debt] Codebase Quality Scan - $(date +%Y-%m-%d)" \
--body-file /tmp/tech-debt-{date}/github-issue-summary.md \
--label "tech-debt,quality,refactoring")
ISSUE_NUMBER=$(echo $ISSUE_URL | grep -oP '\d+$')
# 2. Post critical issues as comment
gh issue comment $ISSUE_NUMBER \
--body-file /tmp/tech-debt-{date}/github-comment-critical.md
# 3. Post high priority issues as comment
gh issue comment $ISSUE_NUMBER \
--body-file /tmp/tech-debt-{date}/github-comment-high.md
# 4. Post medium priority issues as comment
gh issue comment $ISSUE_NUMBER \
--body-file /tmp/tech-debt-{date}/github-comment-medium.md
# 5. Post action plan as comment
gh issue comment $ISSUE_NUMBER \
--body-file /tmp/tech-debt-{date}/github-comment-action-plan.md
Comment Size Limits:
# GitHub Issue Created
**Issue URL:** {url}
**Issue Number:** #{number}
## Content Posted
โ
Issue created with executive summary
โ
Posted {n} comments with detailed findings
## Issue Structure
- Main issue: Executive summary and statistics
- Comment 1: Critical Issues (P0)
- Comment 2: High Priority Issues (P1)
- Comment 3: Medium Priority Issues (P2)
- Comment 4: Action Plan
## Next Steps
1. Review the GitHub issue
2. Prioritize which issues to tackle first
3. Create separate issues for specific refactoring tasks if needed
4. Track progress using the checklist in the action plan
## Local Reports
Detailed reports are also available in:
`/tmp/tech-debt-{date}/`
GitHub CLI Usage:
gh issue create to create issuesgh issue comment to add commentsgh auth status--body-file for large content if neededContent Preparation:
<details>) for long contentError Handling:
Comprehensive Coverage
Efficient Execution
Accurate Analysis
Actionable Reporting
Zero Tolerance Issues (P0):
any usage--max-warnings 0 in lint scriptsHigh Priority Issues (P1):
Medium Priority Issues (P2):
Low Priority Issues (P3):
To User:
In Reports:
In GitHub Issues:
When encountering errors:
# Run research scan
args: "research"
# Create GitHub issue from research
args: "issue"
/docs/bad-smell.md/docs/testing.md/docs/testing/anti-patterns.md/docs/testing/api-testing.md/docs/testing/app-testing.md/.claude/skills/ccstate/SKILL.md/.claude/skills/code-quality/SKILL.md/CLAUDE.mdFeature switch system guide for gating new user-facing features behind feature flags
Patterns and best practices for using ccstate state management in the vm0 platform
Database migrations and Drizzle ORM guidelines for the vm0 project