Analyze the codebase and plan refactoring for code quality and maintainability. Use when user types /plan-refactor or asks to plan refactoring work.
Perform a whole-repo analysis to identify refactoring opportunities that improve code quality, maintainability, and alignment with architectural principles. Produce actionable Linear issues ranked by impact.
Key Philosophy: This is analysis and planning, not implementation. The output is a prioritized set of well-specified issues that agents can pick up via /pick-issue. Focus on high-impact structural improvements, not cosmetic changes.
Establish scope: Ask the user if they want to focus on a specific area or analyze the whole repo:
beamtalk-core, beamtalk-cli)Gather current state: Run quick diagnostics to understand the codebase health:
# Code metrics
find crates/ -name '*.rs' | xargs wc -l | tail -1 # Rust LOC
find runtime/apps/ -name '*.erl' | xargs wc -l | tail -1 # Erlang LOC
# Module sizes (files > 500 lines are candidates for splitting)
find crates/ -name '*.rs' -exec wc -l {} + | sort -rn | head -20
find runtime/apps/ -name '*.erl' -exec wc -l {} + | sort -rn | head -20
# Test coverage gaps (modules without corresponding test files)
# Rust: check for #[cfg(test)] modules
grep -rL '#\[cfg(test)\]' crates/*/src/**/*.rs 2>/dev/null | head -20
# Clippy warnings (non-blocking)
cargo clippy --all-targets 2>&1 | grep "warning:" | sort | uniq -c | sort -rn | head -20
# TODO/FIXME/HACK markers
grep -rn 'TODO\|FIXME\|HACK\|XXX' crates/ runtime/apps/ --include='*.rs' --include='*.erl' | head -30
# Churn hotspots (files that change most often — poorly factored or central)
git log --since="3 months ago" --format=format: --name-only | sort | uniq -c | sort -rn | head -20
# Merge conflict magnets (large files with high churn)
# Cross-reference churn hotspots with file sizes above
Analyze architecture against principles: Check each concern area:
a. DDD Alignment (reference: docs/beamtalk-ddd-model.md)
//! **DDD Context:**)b. Code Organization
c. Error Handling
unwrap() on user input (should be proper error handling).map_err() without context)#beamtalk_error{}d. Test Quality
e. API Surface
f. Performance Concerns
g. Dependency Health
# why: comments for non-obvious dependenciesh. Coupling & Cohesion
i. Change Velocity & Developer Friction
j. Compilation Pipeline Contracts (Beamtalk-specific)
Cross-reference with existing issues: Check Linear for already-planned refactoring:
Search Linear for: label:Refactor state:Backlog,Todo
Avoid duplicating work that's already tracked. Note any existing issues that overlap.
Rank findings by impact: Score each finding on two axes:
| Factor | Weight | Description |
|---|---|---|
| Blast radius | High | How many files/features does this affect? |
| Bug risk | High | Could this cause bugs or security issues? |
| Developer friction | Medium | Does this slow down development? |
| DDD drift | Medium | Does this cause naming/structure confusion? |
| Performance | Low | Is this in a hot path? |
| Cosmetic | Skip | Pure style with no functional impact |
Skip cosmetic-only findings. Only report things that have actionable impact.
Present findings to user: Show a ranked summary before creating issues:
## Refactoring Analysis: [Scope]
### 🔴 High Impact (address soon)
1. **[Finding]** - [file(s)] - [why it matters]
2. ...
### 🟡 Medium Impact (plan for next cycle)
3. **[Finding]** - [file(s)] - [why it matters]
4. ...
### 🟢 Low Impact (nice to have)
5. **[Finding]** - [file(s)] - [why it matters]
6. ...
### Already Tracked
- BT-XXX covers [finding] (skip)
### Skipped
- [N] cosmetic-only findings omitted
Ask the user which findings to create issues for before proceeding.
Create Linear issues: For each approved finding, create a well-specified issue using the create-issue skill patterns:
Refactor type + appropriate area label + size estimateagent-ready (refactoring should be self-contained)Group related findings into a single issue when they affect the same files or concern.
Create Epic if needed: If there are 5+ related issues, create an Epic to group them:
Epic: [Refactoring Theme] (e.g., "Epic: DDD Alignment for Codegen Layer")Summary: Present final output:
## Refactoring Plan Complete
**Scope:** [what was analyzed]
**Issues created:** [count] ([list with IDs])
**Epic:** BT-XXX (if created)
**Estimated total size:** [S/M/L/XL]
**Recommended order:** [which issues to tackle first and why]
✅ Good refactoring targets:
❌ Skip these:
Every refactoring issue MUST include these constraints:
| Size | Scope | Example |
|---|---|---|
| S | 1-2 files, <50 lines changed | Extract a helper function, add missing error context |
| M | 3-5 files, 50-200 lines | Split a module, consolidate duplicated logic |
| L | 5-10 files, 200-500 lines | Reorganize a subsystem, introduce new abstraction |
| XL | 10+ files, 500+ lines | Cross-cutting architectural change (Epic candidate) |
Rust compiler crates:
(Result, Vec<Diagnostic>) patternErlang runtime:
#beamtalk_error{} recordslogger module-spec) required on all public functionsCross-cutting:
docs/development/architecture-principles.md