declutter-assessment

Codebase Assessment

Purpose

Systematically evaluate a codebase to understand its current state, identify quality issues, and prioritize refactoring opportunities.

The Assessment Rule

NO REFACTORING WITHOUT COMPLETE ASSESSMENT FIRST

Rushing into refactoring without understanding the codebase leads to:

• Fixing symptoms instead of root causes
• Missing critical dependencies
• Breaking hidden functionality
• Wasted effort on low-value changes

Assessment Phases

Phase 1: Structural Analysis

Objective: Understand the codebase architecture.

1. Map the directory structure
2. Identify entry points
3. Trace dependencies between modules
4. Document build and test configuration

Output:

• Architecture diagram
• Module dependency graph
• Build/test commands

Phase 2: Complexity Hotspots

Objective: Find the most problematic areas.

Metrics to collect:

Metric	Tool	Threshold
Cyclomatic Complexity	radon/escomplex	>10 = high
Lines per file	wc -l	>500 = review
Lines per function	AST analysis	>50 = extract
Nesting depth	AST analysis	>4 = flatten
Import count	grep/AST	>15 = god module

Output:

• Ranked list of complexity hotspots
• Visualization of problem areas

Phase 3: Code Smell Detection

Objective: Identify specific quality issues.

Invoke declutter:smell-detection skill and document findings:

- [ ] Bloaters identified
- [ ] OO Abusers identified
- [ ] Change Preventers identified
- [ ] Dispensables identified
- [ ] Couplers identified

Output:

• Smell report with severity levels

Phase 4: Test Coverage Analysis

Objective: Understand existing test safety net.

1. Run coverage tool (pytest-cov, istanbul, etc.)
2. Identify untested critical paths
3. Map coverage to complexity hotspots
4. Flag high-complexity + low-coverage areas

Output:

• Coverage report
• Risk matrix (complexity vs coverage)

Phase 5: Change History Analysis

Objective: Find areas that change frequently.

# Most frequently changed files
git log --pretty=format: --name-only | sort | uniq -c | sort -rg | head -20

# Files with most authors (potential knowledge gaps)
git log --pretty=format:'%an' --name-only | ...

# Recent churn (files changed in last month)
git log --since="1 month ago" --pretty=format: --name-only | sort | uniq -c | sort -rg

Output:

• Change frequency analysis
• Knowledge distribution map

Assessment Report Template

# Codebase Assessment Report

## Executive Summary
- Overall health: [Good/Fair/Poor/Critical]
- Primary concerns: [list top 3]
- Recommended focus areas: [list]
- Estimated effort: [Small/Medium/Large/Epic]

## Structural Overview
- Total files: N
- Total lines: N
- Primary languages: [list]
- Architecture style: [Monolith/Modular/Microservices/...]

## Complexity Analysis
| Rank | File | Complexity | Lines | Risk |
|------|------|------------|-------|------|
| 1 | path/to/file | 45 | 800 | HIGH |
| 2 | ... | ... | ... | ... |

## Code Smells Summary
| Category | Count | Critical | High | Medium | Low |
|----------|-------|----------|------|--------|-----|
| Bloaters | N | X | Y | Z | W |
| OO Abusers | N | ... | ... | ... | ... |
| ... | ... | ... | ... | ... | ... |

## Test Coverage
- Overall coverage: X%
- Critical path coverage: Y%
- Untested hotspots: [list]

## Change Analysis
- Most volatile files: [list top 5]
- Knowledge concentration: [High/Medium/Low]
- Recent focus areas: [list]

## Prioritized Recommendations

### Immediate Actions (Block development)
1. [Issue] - [Location] - [Suggested fix]

### High Priority (Next sprint)
1. [Issue] - [Location] - [Suggested fix]

### Medium Priority (Scheduled refactoring)
1. [Issue] - [Location] - [Suggested fix]

### Low Priority (Opportunistic)
1. [Issue] - [Location] - [Suggested fix]

## Next Steps
1. Review this assessment with the team
2. Approve refactoring priorities
3. Begin with `declutter:planning` for approved items

Assessment Checklist

- [ ] Directory structure mapped
- [ ] Entry points identified
- [ ] Dependencies traced
- [ ] Build commands documented
- [ ] Test commands documented
- [ ] Complexity metrics collected
- [ ] Hotspots ranked
- [ ] Code smells detected
- [ ] Smell severity assigned
- [ ] Test coverage analyzed
- [ ] Coverage gaps identified
- [ ] Change history analyzed
- [ ] Volatile files identified
- [ ] Report generated
- [ ] Priorities recommended

Signal

When assessment is complete, emit:

ASSESSMENT_COMPLETE