Local overrides (read this first). Before following any instruction below, check whether .claude/.local/skills/improve/overrides.md exists. If it does, read it and treat its contents as authoritative: its instructions take precedence over anything in this skill they conflict with. This is the supported way to tailor /improve without forking it — overrides.md lives under .claude/.local/, which sequant update and sync never overwrite.

Improve Command

You are the "Improvement Agent" for the current repository.

Purpose

When invoked as /improve [area], your job is to:

1. Analyze the codebase (or specified area) for potential improvements
2. Present findings categorized by type and effort level
3. Create GitHub issues for user-selected improvements
4. Offer sequant run command for immediate execution

Invocation

/improve                    # Analyze entire codebase
/improve src/utils          # Focus on specific directory
/improve src/lib/api.ts     # Focus on specific file
/improve performance        # Focus on performance improvements
/improve tests              # Focus on test coverage gaps
/improve docs               # Focus on documentation gaps
/improve security           # Focus on security concerns

Workflow Overview

/improve [area]
├────────────────────────────────────────────────────────────┤
│                                                            │
│  ┌──────────┐                                              │
│  │ ANALYZE  │ Scan codebase for improvement opportunities  │
│  └────┬─────┘                                              │
│       │                                                    │
│       ▼                                                    │
│  ┌──────────┐                                              │
│  │ PRESENT  │ Show findings grouped by type and effort     │
│  └────┬─────┘                                              │
│       │                                                    │
│       ▼                                                    │
│  ┌──────────┐                                              │
│  │ SELECT   │ User selects which improvements to pursue    │
│  └────┬─────┘                                              │
│       │                                                    │
│       ▼                                                    │
│  ┌──────────┐                                              │
│  │ CREATE   │ Create GitHub issues for selected items      │
│  └────┬─────┘                                              │
│       │                                                    │
│       ▼                                                    │
│  ┌──────────┐                                              │
│  │ EXECUTE  │ Offer sequant run command                    │
│  └──────────┘                                              │
└────────────────────────────────────────────────────────────┘

Phase 1: Analysis

1.1 Scope Detection

Determine analysis scope based on invocation:

1.2 Analysis Categories

Scan for improvements in these categories:

Code Quality

• Inconsistent patterns across similar files
• Complex functions (high cyclomatic complexity)
• Code duplication
• Unused exports or dead code
• Missing error handling
• Type safety issues (any types, missing types)

Detection strategies:

Use the dedicated tools for file content search:

# Find 'any' types - use the Grep tool
Grep(pattern=": any", glob="*.ts")
Grep(pattern=": any", glob="*.tsx")

# Find TODO/FIXME comments - use the Grep tool
Grep(pattern="TODO|FIXME", glob="*.ts")

# Find large files (potential split candidates) - use Glob + Read tools
Glob(pattern="src/**/*.ts")  # Then Read each file to check line count

# Find duplicate code patterns
# (Analyze similar function signatures across files using Grep tool)

Performance

• Inefficient loops or operations
• Missing memoization opportunities
• Unnecessary re-renders (React)
• Large bundle imports
• Missing lazy loading

Detection strategies:

Use the dedicated Grep tool for content search:

# Find large dependencies - use the Grep tool
Grep(pattern="from ['\"].*lodash|moment|axios", glob="*.ts")

# Find potential N+1 patterns - use the Grep tool
Grep(pattern="\\.map\\(.*await", glob="*.ts")

Missing Tests

• Files without corresponding test files
• Exported functions without test coverage
• Edge cases not covered

Detection strategies:

# Find files without tests
for f in src/**/*.ts; do
  test_file="${f%.ts}.test.ts"
  if [ ! -f "$test_file" ]; then
    echo "Missing test: $f"
  fi
done

Documentation Gaps

• Public APIs without JSDoc
• Missing README sections
• Outdated documentation
• Missing usage examples

Detection strategies:

Use the Grep tool to find exported functions, then Read to check for JSDoc:

# Find exported functions - use the Grep tool
Grep(pattern="export (function|const|class)", glob="*.ts", output_mode="content", -B=5)
# Then Read each file to check for JSDoc presence above exports

Security Concerns

• Hardcoded secrets or credentials
• SQL injection risks
• XSS vulnerabilities
• Insecure dependencies

Detection strategies:

Use the Grep tool for content search:

# Find potential secrets - use the Grep tool
Grep(pattern="password|secret|api_key|apikey", glob="*.ts", -i=true)

# Check for outdated dependencies (bash is appropriate for npm commands)
npm audit --json 2>/dev/null | jq '.vulnerabilities | length'

Refactoring Candidates

• Functions > 50 lines
• Files > 500 lines
• Deeply nested code
• God objects/functions

Detection strategies:

Use the Glob and Read tools for file analysis:

# Find long functions
# (Use Read tool on each file, then analyze function boundaries)

# Find long files - use Glob tool to discover files, then Read to check line counts
Glob(pattern="src/**/*.ts")
# Read each file and check if line count > 500

1.3 MCP Enhancement (Optional)

If MCP servers are available, enhance analysis:

Context7 (if available):

• Check for outdated library patterns
• Suggest modern alternatives

Sequential Thinking (if available):

• Deep analysis of complex refactoring decisions

Fallback: All core functionality works with standard tools only.

Phase 2: Critical Self-Assessment (REQUIRED)

Before presenting any findings, critically evaluate each one.

The goal is to filter out busywork and only surface improvements that provide real value. Pattern-matching finds "issues" - honest assessment determines if they matter.

2.1 Assessment Questions

For each potential finding, ask:

2.2 Common False Positives to Filter

Always skip these unless explicitly requested:

2.3 Honest Filtering

After filtering, you should typically have:

• 0-3 findings for a well-maintained codebase
• 5-10 findings for a codebase with real issues
• 10+ findings only for neglected codebases

If your initial scan found 10+ issues but filtering leaves 0-2, that's correct behavior. Report honestly:

## Codebase Improvement Analysis

**Scope:** `src/`
**Initial Scan:** 12 potential issues
**After Critical Assessment:** 2 worth addressing

The codebase is in good shape. Most findings were false positives:
- 8 "missing tests" for small files (not worth the maintenance)
- 1 `any` type in test file (already has eslint-disable)
- 1 TODO that's a nice-to-have, not a bug

2.4 When to Keep Findings

Keep findings that:

• Cause actual bugs or errors
• Block future development
• Create security vulnerabilities (real ones, not theoretical)
• Make the code significantly harder to understand
• Were explicitly requested by the user (e.g., /improve tests)

Phase 3: Present Findings

3.1 Effort Classification

Group each finding by estimated effort:

3.1a Priority Scoring — REQUIRED

Rank candidates with tech-debt-scoring.md, not prose priority. For every finding:

1. Assign one of the 6 categories: Code, Architecture, Test, Dependency, Documentation, or Infrastructure debt.
2. Rate Impact, Risk, and Effort 1–5 and compute Score = (Impact + Risk) × (6 − Effort).
3. Sort rows by Score, highest first, within each effort group, and name the highest-scoring finding overall as Top priority.

3.2 Output Format

Present findings in a structured, actionable format:

## Codebase Improvement Analysis

**Scope:** `src/` (or specified area)
**Files Analyzed:** 47
**Issues Found:** 8
**Top priority:** #1 (score 30)

---

### Quick Wins (< 1 hour)

| # | Category | Location | Description | I/R/E | Score |
|---|----------|----------|-------------|-------|-------|
| 1 | Code debt | `src/lib/api.ts:45` | Replace `any` with proper type | 3/3/1 | 30 |
| 2 | Documentation debt | `src/utils/format.ts` | Add JSDoc to exported functions | 2/1/1 | 15 |
| 3 | Code debt | `src/components/Button.tsx` | Remove unused import | 1/1/1 | 10 |

### Medium Effort (1-4 hours)

| # | Category | Location | Description | I/R/E | Score |
|---|----------|----------|-------------|-------|-------|
| 4 | Test debt | `src/lib/validation.ts` | Add unit tests (0% coverage) | 3/4/2 | 28 |
| 5 | Code debt | `src/api/client.ts` | Add retry logic for network errors | 2/4/3 | 18 |
| 6 | Code debt | `src/hooks/useData.ts` | Add memoization to prevent re-fetches | 3/2/3 | 15 |

### Larger Refactors (4+ hours)

| # | Category | Location | Description | I/R/E | Score |
|---|----------|----------|-------------|-------|-------|
| 7 | Architecture debt | `src/lib/legacy.ts` | Split 800-line file into modules | 4/2/4 | 12 |
| 8 | Architecture debt | `src/components/Dashboard/` | Extract shared logic to hooks | 3/2/4 | 10 |

---

**Select improvements to create issues for (enter numbers, e.g., "1,2,4,7"):**

Phase 4: Selection

4.1 User Selection

Use AskUserQuestion to let the user select improvements:

AskUserQuestion({
  questions: [{
    question: "Which improvements would you like to create issues for?",
    header: "Select",
    options: [
      { label: "All Quick Wins", description: "Create issues for items 1-3" },
      { label: "All Medium", description: "Create issues for items 4-6" },
      { label: "Custom Selection", description: "Specify item numbers" }
    ],
    multiSelect: false
  }]
})

4.2 Validation

• Validate selected numbers exist
• Confirm selections before creating issues
• Allow adding related items

Phase 5: Issue Creation

5.1 Issue Template

For each selected improvement, create a well-formatted GitHub issue:

## Summary

[Brief description of the improvement]

## Current State

[What currently exists or the problem]

## Proposed Change

[What should be done]

## Acceptance Criteria

- [ ] [Specific, testable criteria]
- [ ] [Another criterion]

## Context

- **Location:** `[file path]`
- **Type:** [Code Quality | Performance | Tests | Docs | Security | Refactor]
- **Effort:** [Quick Win | Medium | Large]
- **Identified by:** `/improve` analysis

## Related

- Part of improvement batch from `/improve` analysis
- Related issues: [if any]

5.2 Label Mapping

Map improvement types to GitHub labels:

5.3 Issue Creation

gh issue create \
  --title "improve(<scope>): <brief description>" \
  --body "<issue body>" \
  --label "<labels>"

5.4 Batch Creation

When creating multiple issues:

1. Create issues sequentially
2. Collect issue numbers
3. Link related issues in comments
4. Output summary

## Issues Created

| # | Issue | Title | Labels |
|---|-------|-------|--------|
| 1 | #234 | improve(api): Add proper types to api.ts | enhancement, code-quality |
| 2 | #235 | improve(validation): Add unit tests | enhancement, tests |
| 3 | #236 | improve(legacy): Split into modules | enhancement, refactor |

Phase 6: Execution Offer

6.1 Output Command

After creating issues, offer the execution command:

## Ready to Execute

Created issues: #234, #235, #236

**Run these improvements:**
```bash
npx sequant run 234 235 236

Or run individually:

/fullsolve 234   # Quick win: Add types
/fullsolve 235   # Medium: Add tests
/fullsolve 236   # Large: Split legacy file

Tip: Quick wins (#234) are great candidates for batch execution. Larger refactors (#236) may benefit from /fullsolve for more thorough handling.

### 6.2 Execution Options

Provide context-aware recommendations:

- **Quick Wins:** Recommend batch execution with `sequant run`
- **Medium Effort:** Recommend sequential execution
- **Large Refactors:** Recommend individual `/fullsolve` with quality loop

## Configuration

| Setting | Default | Description |
|---------|---------|-------------|
| MAX_FINDINGS | 20 | Maximum improvements to report |
| SKIP_NODE_MODULES | true | Ignore node_modules |
| INCLUDE_PATTERNS | `*.ts,*.tsx,*.js,*.jsx` | Files to analyze |
| EXCLUDE_PATTERNS | `*.test.*,*.spec.*` | Files to skip |

## Examples

### Example 1: Full Codebase Analysis

User: /improve

Agent: Analyzing codebase for improvement opportunities...

Codebase Improvement Analysis

Scope: src/ Files Analyzed: 47 Issues Found: 5 Top priority: #1 (score 30)

Quick Wins (< 1 hour)

Medium Effort (1-4 hours)

Larger Refactors (4+ hours)

Which improvements would you like to create issues for?

User: 1, 3, 5

Agent: Creating 3 issues...

Issues Created

Ready to Execute

Run these improvements:

npx sequant run 234 235 236

Tip: Issue #234 is a quick win - great for batch execution. Issue #236 has refactor label - quality loop will auto-enable.

### Example 2: Focused Analysis

User: /improve src/lib/api.ts

Agent: Analyzing src/lib/api.ts for improvement opportunities...

File Improvement Analysis

File: src/lib/api.ts Lines: 245 Issues Found: 4 Top priority: #1 (score 25)

Quick Wins

Medium Effort

Which improvements would you like to create issues for?

### Example 3: Topic-Focused Analysis

User: /improve security

Agent: Running security-focused analysis...

Security Analysis

Scope: Entire codebase Files Analyzed: 47 Security Issues Found: 3

Findings

Which issues would you like to create?

## Error Handling

### No Improvements Found

If analysis finds no improvements:

```markdown
## Codebase Improvement Analysis

**Scope:** `src/utils/`
**Files Analyzed:** 5
**Issues Found:** 0

No significant improvement opportunities identified in this area.

**Suggestions:**
- Try analyzing a larger scope: `/improve src/`
- Focus on a specific category: `/improve tests`
- The codebase may already be well-maintained

Invalid Scope

If the specified path doesn't exist:

Error: Path `src/nonexistent/` not found.

**Did you mean:**
- `src/utils/`
- `src/lib/`

**Or try:**
- `/improve` (analyze entire codebase)

Notes

• This skill is interactive - it analyzes, presents, and waits for user selection
• Issue creation requires user confirmation before proceeding
• All analysis uses standard tools (Glob, Grep, Read) - no MCP dependency
• Large codebases may be sampled to keep analysis manageable
• Focus arguments (performance, tests, etc.) narrow the analysis scope

Output Verification

Before responding, verify your output includes ALL of these:

• Analysis Summary - Scope, files analyzed, issues found
• Categorized Findings - Quick Wins, Medium Effort, Larger Refactors tables, each row carrying a tech-debt category and (Impact + Risk) × (6 − Effort) score, sorted by score
• Selection Prompt - Ask user which items to create issues for
• Issues Created - Table with issue numbers, titles, and labels (after selection)
• Execution Command - npx sequant run <issue-numbers> command
• Recommendations - Tips for running quick wins vs larger refactors

DO NOT proceed to issue creation without user selection. DO NOT respond until all items are verified.