safe-refactor
Plan refactoring with blast radius analysis, dependency mapping, and rollback strategy. Triggers: "refactor", "safe refactor", "restructure", "rename type", "extract protocol".
Terry Nyberg · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add Terryc21/sitrep --skill safe-refactorAbout this skill
name: safe-refactor description: 'Plan refactoring with blast radius analysis, dependency mapping, and rollback strategy. Triggers: "refactor", "safe refactor", "restructure", "rename type", "extract protocol".' version: 2.5.0 author: Terry Nyberg license: Apache-2.0 allowed-tools: [Glob, Grep, Read, Bash, Edit, Write, LSP, AskUserQuestion] metadata: tier: analysis category: refactoring
Safe Refactor
Quick Ref: Blast radius analysis → dependency mapping → step-by-step plan → verify after each step. Every commit compiles and passes tests. Output:
.agents/research/YYYY-MM-DD-refactor-{target}.md
YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.
Permissions
AskUserQuestion with questions:
[
{
"question": "How should Claude handle bash commands, file edits, and writes during this skill run?",
"header": "Permissions",
"options": [
{"label": "Autonomous (Recommended)", "description": "Proceed without per-action approval prompts — destructive actions still require approval"},
{"label": "Supervised", "description": "Ask for approval before each bash command, file edit, or write"}
],
"multiSelect": false
}
]
If Autonomous: proceed through all steps without per-action approval prompts. Destructive actions (file deletion, git reset, dropping data) still require explicit user approval. If Supervised: request approval before each bash command, file edit, or write.
Pre-flight: Git Safety Check
git status --short
If uncommitted changes exist:
AskUserQuestion with questions:
[
{
"question": "You have uncommitted changes. Commit before proceeding?",
"header": "Git",
"options": [
{"label": "Commit first (Recommended)", "description": "Save current work so you can revert if this skill modifies files"},
{"label": "Continue without committing", "description": "Proceed — I accept the risk"}
],
"multiSelect": false
}
]
If "Commit first": Ask for a commit message, stage changed files, and commit. Then proceed.
Step 1: Identify Refactoring Candidates
Scan for files exceeding file size thresholds and display a risk assessment table.
1.1: Find Oversized Files
Check CLAUDE.md for project-specific file size guidelines. If none exist, use these defaults:
| Type | Pattern | Target | Refactor Trigger |
|---|---|---|---|
| Views | *View*.swift | <400 | >600 lines |
| ViewModels | *ViewModel*.swift | <300 | >500 lines |
| Managers/Services | *Manager*.swift, *Service*.swift | <400 | >600 lines |
| Models | *Model*.swift, *+*.swift, *Enums*.swift | <600 | >1000 lines |
# First: check CLAUDE.md for project-specific thresholds
Grep pattern="File Size|Split When|lines" path="CLAUDE.md" output_mode="content"
# If found, use those thresholds instead of the defaults above
# Find files exceeding thresholds (exclude Tests/ and generated code)
# Adjust the numeric thresholds below if CLAUDE.md defines different values
# Views over trigger
find Sources -name "*View*.swift" -not -path "*/Tests/*" -exec wc -l {} + | sort -rn | awk '$1 > 600 {print}'
# ViewModels over trigger
find Sources -name "*ViewModel*.swift" -exec wc -l {} + | sort -rn | awk '$1 > 500 {print}'
# Managers/Services over trigger
find Sources \( -name "*Manager*.swift" -o -name "*Service*.swift" \) -not -path "*/Tests/*" -exec wc -l {} + | sort -rn | awk '$1 > 600 {print}'
# Models over trigger
find Sources \( -name "*Model*.swift" -o -name "*Enums*.swift" \) -not -path "*/Tests/*" | xargs wc -l | sort -rn | awk '$1 > 1000 {print}'
1.2: Gather Risk Metrics
For each oversized file, collect:
# For each file: line count, function count, #if os blocks, struct/class/extension blocks
lines=$(wc -l < "$file")
funcs=$(grep -cE "^\s+(func |private func |static func )" "$file")
platform=$(grep -cE "#if os\(|#if canImport" "$file")
blocks=$(grep -cE "^(struct|class|extension|enum) " "$file")
# Check for test coverage
find Tests -name "*${basename}*" | wc -l
1.3: Count Blast Radius
For each oversized file, count downstream dependents:
# Count files that reference this type (exclude the file itself and Tests/)
typename=$(basename "$file" .swift)
Grep pattern="$typename" glob="Sources/**/*.swift" output_mode="files_with_matches"
# Subtract 1 for the file itself
1.4: Display Risk Assessment Table
Present one table per file type. Columns combine color indicators with actual numbers for at-a-glance scanning with precise data.
## Refactoring Risk Assessment — Oversized Files
### Views (trigger: >600 lines)
| # | File | Lines | Over | Blast Radius | Platform Splits | Functions | Tests | Urgency | ROI | Effort |
|---|------|-------|------|-------------|-----------------|-----------|-------|---------|-----|--------|
| 1 | `FileName` | 1289 | 🟡 +289 | 🟢 5 files | 🟡 10 | 1 | Partial | 🟡 High | 🟢 Good | Large |
### ViewModels (trigger: >500 lines)
...
### Managers/Services (trigger: >600 lines)
...
### Models (trigger: >1000 lines)
...
Color thresholds:
| Column | ⚪ Low | 🟢 Medium | 🟡 High |
|---|---|---|---|
| Over | <50 lines | 50–200 lines | >200 lines |
| Blast Radius | 0–2 files | 3–8 files | >8 files |
| Platform Splits | 0–3 blocks | 4–8 blocks | >8 blocks |
Urgency (when does this need to happen):
- 🔴 Critical — actively causing merge conflicts, blocking other work, or growing every sprint
- 🟡 High — significantly over threshold, frequently edited file, or upcoming feature work will make it worse
- 🟢 Medium — over threshold but stable, infrequently edited
- ⚪ Low — barely over threshold, not actively growing
ROI (synthesized judgment):
- 🟠 Excellent — blocking other work or causing merge conflicts
- 🟢 Good — significantly over threshold with low blast radius and clear split points
- 🟡 Marginal — moderate over wi