tech-debt

Name: tech-debt
Rating: 70
Author: vm0-ai

by vm0-ai

the easiest way to run natural language-described workflows automatically

⭐ 191🍴 7📅 Jan 23, 2026

agentic-workflow ai-agent ai-runtime ai-sandbox claude-code cli cloudflare codex

View on GitHub Run in Manus

SKILL.md

name: tech-debt description: Technical debt management - scan codebase for bad smells and create tracking issues allowed-tools: Bash, Read, Grep, Glob, Edit, Write context: fork

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:

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

Parse the operation from the args parameter:

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

Phase 2: Detailed Analysis

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

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

Analysis Criteria (reference from specs/bad-smell.md and .claude/skills/testing/SKILL.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

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
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}

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

### 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

### 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}*

Phase 4: User Report

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.

Implementation Notes

Efficiency Tips:

Use grep -l (files only) for fast scanning
Use wc -l for line counts
Combine multiple greps with parallel execution
Only read files that match patterns
Cache scan results for issue operation

Accuracy Tips:

Exclude node_modules and .git directories
Exclude generated files (*.d.ts)
Exclude migration files for some checks
Use word boundaries in regex (\b) for precision
Verify matches by reading actual file content

Operation 2: Issue

Create a GitHub issue based on research findings. If research hasn't been run, automatically run it first.

Usage

issue

Workflow

Step 1: Check for Existing Research

# 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

Step 2: Prepare Issue Content

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)

### 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)

### Phase 3: Medium Priority (Target: 1-2 months)
- [ ] Remove fallback patterns ({count} files)
- [ ] Fix testing mock assertions ({count} files)
- [ ] Replace fake timers ({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: `/specs/bad-smell.md`
- Testing Guidelines: `/.claude/skills/testing/SKILL.md`

Step 3: Create GitHub Issue

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 "$(cat /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 "$(cat /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 "$(cat /tmp/tech-debt-{date}/github-comment-critical.md)"

# 3. Post high priority issues as comment
gh issue comment $ISSUE_NUMBER \
  --body "$(cat /tmp/tech-debt-{date}/github-comment-high.md)"

# 4. Post medium priority issues as comment
gh issue comment $ISSUE_NUMBER \
  --body "$(cat /tmp/tech-debt-{date}/github-comment-medium.md)"

# 5. Post action plan as comment
gh issue comment $ISSUE_NUMBER \
  --body "$(cat /tmp/tech-debt-{date}/github-comment-action-plan.md)"

Comment Size Limits:

Each comment should be <65K characters
If a section exceeds limit, split into multiple comments
Use clear headers to indicate which part of the report each comment contains

Step 4: Report to User

# 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}/`

Implementation Notes

GitHub CLI Usage:

Use gh issue create to create issues
Use gh issue comment to add comments
Verify gh is authenticated: gh auth status
Use --body-file for large content if needed

Content Preparation:

Inline all report content (don't use file links)
Use markdown collapsible sections (<details>) for long content
Include syntax highlighting for code snippets
Add line breaks for readability

Error Handling:

Check if gh CLI is installed and authenticated
Verify issue creation succeeded before posting comments
If comment posting fails, save remaining content to file and report to user
Don't fail entire operation if one comment fails

General Guidelines

Scanning Principles

Comprehensive Coverage
- Scan all source files in turbo/ directory
- Include both production and test code
- Don't skip any file types (.ts, .tsx, .js, .jsx)
Efficient Execution
- Use fast pattern matching first (grep, find)
- Only read files that match patterns
- Run searches in parallel when possible
- Cache results between operations
Accurate Analysis
- Read full file content for matched files
- Verify patterns in context
- Avoid false positives
- Include line numbers for all findings
Actionable Reporting
- Provide specific file paths and line numbers
- Include code snippets for context
- Suggest concrete remediation steps
- Estimate effort for fixes

Quality Standards

Zero Tolerance Issues (P0):

TypeScript any usage
Lint suppressions (@ts-ignore, eslint-disable)
Dynamic imports
Mocking internal code (AP-4)

High Priority Issues (P1):

Files >1500 lines
Defensive programming patterns
Hardcoded URLs
Direct fetch mocking (AP-2)
Filesystem mocking (AP-3)

Medium Priority Issues (P2):

Files >1000 lines
Fallback patterns
Testing mock calls (AP-1)
Fake timers (AP-5)

Low Priority Issues (P3):

Over-testing patterns
Console mocking without assertions

Communication Style

To User:

Medium level of detail (not too brief, not overwhelming)
Focus on most important findings
Provide clear next steps
Use markdown formatting

In Reports:

High level of detail
Include all findings with evidence
Provide remediation guidance
Use consistent formatting

In GitHub Issues:

Balance detail with readability
Use collapsible sections for long content
Include actionable checklists
Add appropriate labels

Error Handling

When encountering errors:

If grep/find fails, report and continue with other checks
If file is unreadable, note it and continue
If directory doesn't exist, report and skip
If gh CLI fails, report and save content to file
Always complete scan even if some steps fail
Provide partial results if full scan can't complete

Example Usage

# Run research scan
args: "research"

# Create GitHub issue from research
args: "issue"

References

Bad smell documentation: /specs/bad-smell.md
Testing anti-patterns: /.claude/skills/testing/SKILL.md
Code quality skill: /.claude/skills/code-quality/SKILL.md
Project principles: /CLAUDE.md

Score

Total Score

70/100

Based on repository quality metrics

✓SKILL.md

SKILL.mdファイルが含まれている

+20

✓LICENSE

ライセンスが設定されている

+10

○説明文

100文字以上の説明がある

0/10

✓人気

GitHub Stars 100以上

✓最近の活動

1ヶ月以内に更新

+10

○フォーク

10回以上フォークされている

0/5

✓Issue管理

オープンIssueが50未満

✓言語

プログラミング言語が設定されている

✓タグ

1つ以上のタグが設定されている

Reviews

💬

Reviews coming soon

tech-debt

SKILL.md

name: tech-debt description: Technical debt management - scan codebase for bad smells and create tracking issues allowed-tools: Bash, Read, Grep, Glob, Edit, Write context: fork

Technical Debt Management Skill

Operations

Operation 1: Research

Usage

Workflow

Phase 1: Fast Scan

Phase 2: Detailed Analysis

Phase 3: Generate Report

{next-file}

Remediation Strategy

References

Phase 4: User Report

Implementation Notes

Operation 2: Issue

Usage

Workflow

Step 1: Check for Existing Research

Step 2: Prepare Issue Content

Step 3: Create GitHub Issue

Step 4: Report to User

Implementation Notes

General Guidelines

Scanning Principles

Quality Standards

Communication Style

Error Handling

Example Usage

References

Score

Reviews

create-pr

writing-dev-server-tests

writing-bundler-tests

implementing-jsc-classes-cpp

implementing-jsc-classes-zig

prompt-lookup

tech-debt

SKILL.md

name: tech-debt description: Technical debt management - scan codebase for bad smells and create tracking issues allowed-tools: Bash, Read, Grep, Glob, Edit, Write context: fork

Technical Debt Management Skill

Operations

Operation 1: Research

Usage

Workflow

Phase 1: Fast Scan

Phase 2: Detailed Analysis

Phase 3: Generate Report

{next-file}

Remediation Strategy

References

Phase 4: User Report

Implementation Notes

Operation 2: Issue

Usage

Workflow

Step 1: Check for Existing Research

Step 2: Prepare Issue Content

Step 3: Create GitHub Issue

Step 4: Report to User

Implementation Notes

General Guidelines

Scanning Principles

Quality Standards

Communication Style

Error Handling

Example Usage

References

Score

Reviews

Related

Related Skills

create-pr

writing-dev-server-tests

writing-bundler-tests

implementing-jsc-classes-cpp

implementing-jsc-classes-zig

prompt-lookup