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:

Invocation	Scope
/improve	Entire src/ directory (or project root)
/improve src/utils	Specific directory
/improve file.ts	Single file
/improve performance	Performance-focused analysis
/improve tests	Test coverage analysis
/improve docs	Documentation analysis
/improve security	Security-focused analysis

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:

Question	If "No" → Filter Out
Does this cause real problems today?	Skip theoretical issues
Would fixing this measurably improve the codebase?	Skip cosmetic changes
Is the fix worth the maintenance burden it adds?	Skip if tests/code add more complexity than value
Would a senior engineer care about this?	Skip pedantic findings
Is this the right time to fix this?	Skip if other priorities exist

2.2 Common False Positives to Filter

Always skip these unless explicitly requested:

Pattern Match	Why It's Usually Noise
any in test files	Test mocks are hard to type; ESLint disables are fine
any with eslint-disable comment	Already acknowledged and accepted
Missing tests for <100 line files	Maintenance burden exceeds value
Missing tests for files tested implicitly	Integration tests often suffice
TODOs that are "nice to have"	If it worked without it for months, it's low priority
Large files that work fine	Size alone isn't a problem if code is cohesive
Low-severity dependency vulns	DoS in dev tools rarely matters
Missing JSDoc on internal functions	Self-documenting code > comment maintenance

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:

Group	Description	Typical Items
Quick Wins	< 1 hour	Add missing types, fix linting, add JSDoc
Medium Effort	1-4 hours	Add tests, refactor function, improve error handling
Larger Refactors	4+ hours	Split large file, redesign module, add feature

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:

Type	Labels
Code Quality	enhancement, code-quality
Performance	enhancement, performance
Missing Tests	enhancement, tests
Documentation	docs
Security	security, priority:high
Refactoring	enhancement, refactor

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)

#	Category	Location	Description	I/R/E	Score
1	Code debt	src/lib/api.ts:45	Replace any with ApiResponse type	3/3/1	30
2	Code debt	src/utils/index.ts	Remove unused formatDate export	1/1/1	10

Medium Effort (1-4 hours)

#	Category	Location	Description	I/R/E	Score
3	Test debt	src/lib/validation.ts	Add unit tests (currently 0% coverage)	3/4/2	28
4	Documentation debt	src/hooks/	Add JSDoc to custom hooks	2/1/2	12

Larger Refactors (4+ hours)

#	Category	Location	Description	I/R/E	Score
5	Architecture debt	src/lib/legacy.ts	Split 800-line file into modules	4/2/4	12

---

Which improvements would you like to create issues for?

User: 1, 3, 5

Agent: Creating 3 issues...

Issues Created

#	Issue	Title	Labels
1	#234	improve(api): Replace any type with ApiResponse	enhancement
2	#235	improve(validation): Add unit tests	enhancement, tests
3	#236	improve(legacy): Split into modules	enhancement, refactor

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

#	Category	Location	Description	I/R/E	Score
1	Code debt	Line 45	Replace data: any with proper type	3/2/1	25
2	Code debt	Line 78	Replace options?: any with RequestOptions	2/2/1	20

Medium Effort

#	Category	Location	Description	I/R/E	Score
3	Code debt	Lines 89-120	Add retry logic for transient errors	3/5/3	24
4	Test debt	-	Add integration tests for API client	3/3/3	18

---

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

#	Severity	Location	Description
1	Medium	src/config.ts:12	API key in source (should use env var)
2	Low	package.json	2 dependencies with known vulnerabilities
3	Info	src/api/client.ts	No request timeout configured

---

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.