Plan Refactor | Skills Pool

# 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)

Modules using generic names instead of domain terms
Missing bounded context annotations (//! **DDD Context:**)
Domain concepts in code that aren't in the DDD model doc
Cross-context dependencies (e.g., codegen importing runtime internals)

b. Code Organization

God files (>500 lines) that should be split
Related functions scattered across unrelated modules
Inconsistent module structure between similar components
Dead code or unused imports

c. Error Handling

Bare unwrap() on user input (should be proper error handling)
Missing error context (.map_err() without context)
Inconsistent error types across module boundaries
Runtime: bare tuple errors instead of #beamtalk_error{}

d. Test Quality

Modules with no tests or low coverage
Tests that test implementation details instead of behavior
Missing E2E tests for user-facing features
Duplicated test setup that could be extracted

e. API Surface

Public functions that should be private
Missing documentation on public APIs
Inconsistent function signatures for similar operations
Missing type annotations or specs

f. Performance Concerns

Unnecessary allocations in hot paths
O(n²) or worse algorithms
Unnecessary cloning where borrows would work (Rust)
Unbounded data structures

g. Dependency Health

Unused dependencies in Cargo.toml
Outdated dependencies with known issues
Missing # why: comments for non-obvious dependencies

h. Coupling & Cohesion

Shotgun surgery: one logical change requires touching many unrelated files
Feature envy: functions that use another module's data more than their own
Internal details leaking across module boundaries (public API too wide)
Low cohesion: module has unrelated responsibilities that should be split
High churn files: if a file changes in every PR, it may be a coupling bottleneck

i. Change Velocity & Developer Friction

Churn hotspots (files modified in most PRs) — central or poorly factored?
Merge conflict magnets (large files touched by multiple features simultaneously)
Onboarding friction: code that requires AGENTS.md to explain should be clearer
Boilerplate that could be reduced with macros, traits, or code generation

j. Compilation Pipeline Contracts (Beamtalk-specific)

Pipeline stage boundaries (lexer → parser → semantic → codegen → runtime) — are they independently testable with clear interfaces?
Runtime/codegen contract: do they agree on calling conventions, state shape, error format? Drift here causes subtle bugs.
Generated Core Erlang patterns: are they consistent across similar AST nodes? Inconsistency means runtime bugs.
BEAM interop surface: are Erlang module/function names predictable and documented?

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.

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]

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)

Plan Refactor

Plan Refactor Workflow

Steps

Plan Refactor

Plan Refactor Workflow

Steps

Analysis Guidelines

What Makes Good Refactoring

Safety Principles

Size Estimation

Beamtalk-Specific Concerns

Notion

Feishu Wiki

Gemini

Obsidian Vault Maintainer

Openclaw Pr Maintainer

Wiki Maintainer