refactor-radar

Refactor Radar

Detects systemic codebase issues that repeatedly confuse AI assistants and offers to create refactoring proposals.

When to Trigger (Self-Assessment)

IMPORTANT: This skill is NOT user-invoked. Trigger when you detect patterns that will cause ONGOING confusion, not one-time mistakes.

Architectural Smells (High Confidence)

1. Inconsistent Naming Across Layers [category: naming]

   • DB uses snake_case, API uses camelCase, frontend uses kebab-case
   • Same concept has different names in different places (user, account, member)
   • Example: users.created_at → API returns createdAt → Frontend displays creation-date

2. Schema/Model Mismatch [category: schema]

   • ORM models don't match actual DB schema
   • TypeScript types don't match API responses
   • Documentation describes different structure than code
   • Example: Type says user.email: string but DB allows null

3. Inconsistent Patterns in Same Codebase [category: patterns]

   • Some services use Repository pattern, others direct DB access
   • Mixed async patterns (callbacks, promises, async/await)
   • Multiple state management approaches in same frontend
   • Example: /api/users uses REST, /api/orders uses GraphQL

4. Ambiguous or Misleading Names [category: naming]

   • UserService that also handles authentication
   • utils.ts with 2000 lines of unrelated functions
   • data folder containing both models and migrations
   • Example: processUser() that actually deletes users

5. Circular or Tangled Dependencies [category: dependencies]

   • Service A imports from Service B which imports from Service A
   • Shared types scattered across multiple packages
   • Example: auth module depends on user module depends on auth

Data Model Issues (Medium Confidence)

6. Implicit Relationships [category: database-migrations]

   • Foreign keys exist in code but not in DB constraints
   • Relationships documented nowhere
   • Example: order.userId exists but no FK constraint, unclear if cascade deletes

7. Overloaded Columns [category: schema]

   • Single column stores multiple types of data
   • Status fields with 15+ possible values
   • JSON blobs that should be normalized
   • Example: metadata JSON column used for 8 different purposes

8. Historical Cruft [category: legacy]

   • Deprecated columns still in schema
   • Dead code paths still present
   • Multiple versions of same logic
   • Example: Both v1_process() and process() exist, unclear which to use

Convention Drift (Lower Confidence)

9. Style Guide Violations [category: code-organization]

   • Older code doesn't follow current patterns
   • Different developers used different conventions
   • Example: Half the codebase uses async/await, half uses .then()

10. Missing Abstractions [category: code-organization]

    • Same boilerplate repeated across many files
    • Copy-paste patterns that should be utilities
    • Example: Same 20-line auth check in 15 different handlers

Invocation Protocol

Step 0: Check for Permanent Override

FIRST, check if user has permanently disabled this skill:

# If project has override skill, this skill is permanently disabled
if [ -f ".claude/skills/refactor-radar/SKILL.md" ]; then
  # User has "shut up forever" - do nothing
  exit 0
fi

Step 0.5: Check User Preferences for Category Exclusions

Check ~/.claude/CLAUDE.md for excluded categories:

grep -A 20 "## AI Suggestion Preferences" ~/.claude/CLAUDE.md 2>/dev/null

Look for sections like:

## AI Suggestion Preferences

### refactor-radar
skip: database-migrations, build-system, infrastructure
welcome: naming, code-organization

If the current trigger category is in the skip list, do not prompt.

Step 1: Check Configuration

cat .overdeck/refactor-radar.json 2>/dev/null || echo "{}"

Default configuration:

{
  "enabled": true,
  "mode": "normal",
  "promptCooldownMinutes": 60,
  "lastPromptTimestamp": null,
  "proposalsCreated": 0,
  "dismissedCount": 0,
  "sessionDismissals": 0
}

Modes:

• "aggressive" - Prompt on every detected issue
• "normal" - High/medium confidence issues, respect cooldown
• "minimal" - Only obvious architectural problems
• "silent" - Log internally, never prompt
• "disabled" - Completely off

Step 2: Respect Cooldowns

Skip prompting if:

• Mode is "disabled" or "silent"
• sessionDismissals >= 2 (user said "not now" twice this session)
• Less than promptCooldownMinutes since last prompt
• Already proposed this exact issue before

Step 3: Present to User

Refactor Radar: Architectural Issue Detected [category: {CATEGORY}]

I've noticed a systemic issue that's causing confusion:

Issue: [SPECIFIC PROBLEM]

Evidence:

• [CONCRETE EXAMPLE 1]
• [CONCRETE EXAMPLE 2]

Impact: This will likely cause repeated mistakes for me and other AI assistants working on this codebase.

Would you like me to create a refactoring proposal?

Step 4: Handle Responses

"Yes, create issue": Create issue with template:

## Refactoring Proposal: [TITLE]

### Problem
[Description of the architectural issue]

### Evidence
- [Specific examples found in codebase]
- [File paths and line numbers]

### Impact
- AI assistants repeatedly make mistakes due to this
- New developers likely face same confusion
- Increases maintenance burden

### Proposed Solution
[Concrete refactoring steps]

### Migration Path
[How to incrementally fix without breaking things]

### Acceptance Criteria
- [ ] [Specific measurable outcomes]

---
*Generated by Refactor Radar - AI-detected architectural improvement opportunity*

"Skip this category":

1. Update ~/.claude/CLAUDE.md to add category to skip list
2. Acknowledge: "Got it - I won't suggest {CATEGORY} refactors anymore. You can edit ~/.claude/CLAUDE.md to change this."

"Shut up forever": Create override skill to permanently disable:

mkdir -p .claude/skills/refactor-radar
cat > .claude/skills/refactor-radar/SKILL.md << 'EOF'
---
name: refactor-radar
description: disabled-override-xK9mQ2
---
Disabled by user preference.
EOF

Acknowledge: "Refactor Radar permanently disabled for this project. Delete .claude/skills/refactor-radar/ to re-enable."

Step 5: Update Configuration

mkdir -p .overdeck
cat > .overdeck/refactor-radar.json << 'EOF'
{
  "enabled": true,
  "mode": "normal",
  "promptCooldownMinutes": 60,
  "lastPromptTimestamp": "2024-01-15T10:30:00Z",
  "proposalsCreated": 2,
  "dismissedCount": 1,
  "sessionDismissals": 0,
  "knownIssues": ["inconsistent-naming-user-account"]
}
EOF

User Preferences in ~/.claude/CLAUDE.md

Users can exclude specific categories globally by adding to their personal ~/.claude/CLAUDE.md:

## AI Suggestion Preferences

### knowledge-capture
skip: database, authentication

### refactor-radar
skip: database-migrations, build-system, infrastructure
welcome: naming, code-organization, testing

Available Categories

Why Skip Categories?

Database migrations: "Schema changes require DBA approval and a formal change management process. AI suggestions here just create noise."

Build system: "Our build is ancient but stable. Touching it requires a dedicated sprint with full QA. Not happening anytime soon."

Infrastructure: "Platform team owns this. I'm a feature developer - infra proposals go nowhere."

Legacy: "We know there's legacy code. We have a 3-year modernization roadmap. Random cleanup PRs aren't helpful."

Authentication: "Security-critical code has strict review requirements. We don't want AI-generated proposals here."

Why Welcome Categories?

Naming: "Naming consistency is low-risk and high-value. Always happy to fix these."

Code organization: "Refactoring utils and extracting abstractions is exactly what we need help with."

Testing: "Test improvements are always welcome - low risk, high value."

Updating Preferences

To add a category exclusion:

# AI will add this section if it doesn't exist, or append to existing
cat >> ~/.claude/CLAUDE.md << 'EOF'

## AI Suggestion Preferences

### refactor-radar
skip: database-migrations, infrastructure
welcome: naming, code-organization
EOF

To modify:

# Edit directly
nano ~/.claude/CLAUDE.md

To remove all exclusions:

# Remove the AI Suggestion Preferences section
sed -i '/## AI Suggestion Preferences/,/^## /d' ~/.claude/CLAUDE.md

User Commands (Escalating Silence)

Users can control this skill via natural language, from gentle to nuclear:

To re-enable after "shut up forever":

rm -rf .claude/skills/refactor-radar/

Example Proposals

Example 1: Naming Inconsistency

Detected: Same entity called user, account, member across codebase

Proposal:

## Refactoring Proposal: Standardize User Entity Naming

### Problem
The "user" concept has inconsistent naming across layers:
- Database: `accounts` table
- Backend models: `User` class
- API responses: `member` object
- Frontend state: `currentAccount`

### Evidence
- `src/models/User.ts` maps to `accounts` table
- `GET /api/members/:id` returns user data
- Frontend calls it `useAccount()` hook

### Proposed Solution
1. Standardize on `User` everywhere
2. Create type aliases during migration: `type Account = User`
3. Update API endpoints with deprecation period
4. Rename frontend hooks/state

### Migration Path
1. Add aliases (non-breaking)
2. Update new code to use `User`
3. Migrate existing code incrementally
4. Remove aliases after full migration

Example 2: Mixed Async Patterns

Detected: Codebase mixes callbacks, promises, and async/await

Proposal:

## Refactoring Proposal: Standardize on async/await

### Problem
Three different async patterns in use:
- Older services use callbacks
- Middle-era code uses `.then()` chains
- Newer code uses async/await

### Evidence
- `src/services/legacy/email.js`: callback-based
- `src/services/payment.ts`: Promise chains
- `src/services/user.ts`: async/await

### Impact
- AI assistants inconsistently apply patterns
- Error handling differs between approaches
- Code review burden increased

### Proposed Solution
Standardize on async/await with these utilities:
- `promisify()` wrapper for callback APIs
- ESLint rule to enforce async/await
- Gradual migration of existing code

### Migration Path
1. Add ESLint rule (warn only)
2. Migrate one service at a time
3. Upgrade to error after 80% migrated

Example 3: Implicit Relationships

Detected: Foreign keys in code but not enforced in DB

Proposal:

## Refactoring Proposal: Add Missing Foreign Key Constraints

### Problem
Relationships exist in application code but lack DB constraints:
- `orders.userId` references `users.id` but no FK
- `comments.postId` references `posts.id` but no FK
- Orphaned records exist in production

### Evidence
- `prisma/schema.prisma` defines relations
- `migrations/` shows no FK constraints
- Query: `SELECT COUNT(*) FROM orders WHERE userId NOT IN (SELECT id FROM users)` returns 47

### Impact
- Data integrity issues
- AI assumes cascading behavior that doesn't exist
- Silent failures on deletions

### Proposed Solution
1. Add FK constraints with migration
2. Clean up orphaned data first
3. Add ON DELETE behavior (CASCADE or SET NULL)

### Migration Path
1. Identify all orphaned records
2. Create cleanup migration
3. Add FK constraints
4. Update application code to handle constraint errors

File Locations

Integration

Works with:

• knowledge-capture: If same issue triggers both, prefer refactor-radar (systemic fix > workaround). Both skills share the same category exclusion system in ~/.claude/CLAUDE.md
• pan-skill-creator: Can convert proposals into project-specific guidance
• Issue trackers: Creates issues in configured tracker (Linear, GitHub, GitLab)

Override Skill Format

The override skill is intentionally minimal to save context:

---
name: refactor-radar
description: disabled-override-xK9mQ2
---
Disabled by user preference.

The obscure description (disabled-override-xK9mQ2) ensures it never triggers on any user input. The body is minimal (4 words) to minimize context usage.