Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

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-refactor

About 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:

TypePatternTargetRefactor 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 lines50–200 lines>200 lines
Blast Radius0–2 files3–8 files>8 files
Platform Splits0–3 blocks4–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
Read the complete source ↗