Code Refactoring Skill | Agent Skills

[IMPORTANT] Use TaskCreate to break ALL work into small tasks BEFORE starting — including tasks for each file read. This prevents context loss from long files. For simple tasks, AI MUST ATTENTION ask user whether to skip.

Understand Code First — HARD-GATE: Do NOT write, plan, or fix until you READ existing code.

Search 3+ similar patterns (grep/glob) — cite file:line evidence

Read existing files in target area — understand structure, base classes, conventions

Run python .claude/scripts/code_graph trace <file> --direction both --json when .code-graph/graph.db exists

Map dependencies via connections or callers_of — know what depends on your target

Write investigation to .ai/workspace/analysis/ for non-trivial tasks (3+ files)

Re-read analysis file before implementing — never work from memory alone

NEVER invent new patterns when existing ones work — match exactly or document deviation

BLOCKED until: - [ ] Read target files - [ ] Grep 3+ patterns - [ ] Graph trace (if graph.db exists) - [ ] Assumptions verified with evidence

Evidence-Based Reasoning — Speculation is FORBIDDEN. Every claim needs proof.

Cite file:line, grep results, or framework docs for EVERY claim

Declare confidence: >80% act freely, 60-80% verify first, <60% DO NOT recommend

Cross-service validation required for architectural changes

"I don't have enough evidence" is valid and expected output

BLOCKED until: - [ ] Evidence file path (file:line) - [ ] Grep search performed - [ ] 3+ similar patterns found - [ ] Confidence level stated

Forbidden without proof: "obviously", "I think", "should be", "probably", "this is because" If incomplete → output: "Insufficient evidence. Verified: [...]. Not verified: [...]."

Design Patterns Quality — Priority checks for every code change:

DRY via OOP: Same-suffix classes (*Entity, *Dto, *Service) MUST ATTENTION share base class. 3+ similar patterns → extract to shared abstraction.

Right Responsibility: Logic in LOWEST layer (Entity > Domain Service > Application Service > Controller). Never business logic in controllers.

SOLID: Single responsibility (one reason to change). Open-closed (extend, don't modify). Liskov (subtypes substitutable). Interface segregation (small interfaces). Dependency inversion (depend on abstractions).

After extraction/move/rename: Grep ENTIRE scope for dangling references. Zero tolerance.

YAGNI gate: NEVER recommend patterns unless 3+ occurrences exist. Don't extract for hypothetical future use.

Anti-patterns to flag: God Object, Copy-Paste inheritance, Circular Dependency, Leaky Abstraction.

docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models) (content auto-injected by hook — check for [Injected: ...] header before reading)

Quick Summary

Goal: Restructure code without changing behavior using extract, move, and simplify patterns.

Workflow:

Analysis — Identify target, map dependencies with Grep, assess impact, verify test coverage
Plan — Document refactoring type, changes, and risks
Execute — Apply refactoring (extract method/class, move to entity/extension, simplify conditionals)
Verify — Run tests, confirm no behavior change, check compilation

Key Rules:

Never refactor without existing test coverage
Make small incremental changes; never mix refactoring with feature work
Place logic in the lowest appropriate layer (Entity > Service > Component)

Investigation Mindset (NON-NEGOTIABLE)

Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).

Do NOT assume code is unused — verify with grep across ALL services
Every refactoring recommendation must include file:line evidence
If you cannot prove a code path is safe to change, state "unverified, needs investigation"
Question assumptions: "Is this really dead code?" → trace all usages including dynamic/reflection
Challenge completeness: "Have I checked all 5 services?" → cross-service validation required
No "should be refactored" without proof — demonstrate the improvement with evidence

⚠️ MANDATORY: Confidence & Evidence Gate

MANDATORY IMPORTANT MUST ATTENTION declare Confidence: X% with evidence list + file:line proof for EVERY claim. 95%+ recommend freely | 80-94% with caveats | 60-79% list unknowns | <60% STOP — gather more evidence. Breaking changes (removing classes, changing interfaces) require 95%+ confidence with full cross-service trace.

Code Refactoring

Expert code restructuring agent. Focuses on structural changes that improve code quality without modifying behavior.

Refactoring Catalog

Extract Patterns

| Pattern | When to Use | Example | | ---------------------- | ----------------------------------- | ----------------------------------------- | | Extract Method | Long method, duplicated code | Move logic to private method | | Extract Class | Class has multiple responsibilities | Create Helper, Service, or Strategy class | | Extract Interface | Need abstraction for testing/DI | Create I{ClassName} interface | | Extract Expression | Complex inline expression | Move to Entity static expression | | Extract Validator | Repeated validation logic | Create validator extension method |

Move Patterns

| Pattern | When to Use | Example | | --------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------ | | Move Method | Method belongs to different class | Move from Handler to Helper/Entity | | Move to Extension | Reusable repository logic | Create {Entity}RepositoryExtensions | | Move to DTO | Mapping logic in handler | Use project DTO base .MapToEntity() (see docs/project-reference/backend-patterns-reference.md) | | Move to Entity | Business logic in handler | Add instance method or static expression |

Simplify Patterns

| Pattern | When to Use | Example | | --------------------------- | ---------------------------- | ---------------------------------- | | Inline Variable | Temporary variable used once | Remove intermediate variable | | Inline Method | Method body is obvious | Replace call with body | | Replace Conditional | Complex if/switch | Use Strategy pattern or expression | | Introduce Parameter Obj | Method has many parameters | Create Command/Query DTO |

Workflow

Phase 1: Analysis

Identify Target: Locate code to refactor
Map Dependencies: Find all usages with Grep
Assess Impact: List affected files and tests
Verify Tests: Ensure test coverage exists
External Memory: Write analysis to .ai/workspace/analysis/{refactoring-name}.analysis.md. Re-read before planning.

Phase 2: Plan

Document refactoring plan:

## Refactoring Plan

**Target**: [file:line_number]
**Type**: [Extract Method | Move to Extension | etc.]
**Reason**: [Why this refactoring improves code]

### Changes

1. [ ] Create/modify [file]
2. [ ] Update usages in [files]
3. [ ] Run tests

### Risks

- [Potential issues]

Phase 3: Execute

// BEFORE: Logic in handler
protected override async Task<Result> HandleAsync(Command req, CancellationToken ct)
{
    var isValid = entity.Status == Status.Active &&
                  entity.User?.IsActive == true &&
                  !entity.IsDeleted;
    if (!isValid) throw new Exception();
}

// AFTER: Extracted to entity static expression
// In Entity.cs
public static Expression<Func<Entity, bool>> IsActiveExpr()
    => e => e.Status == Status.Active &&
            e.User != null && e.User.IsActive &&
            !e.IsDeleted;

// In Handler
var entity = await repository.FirstOrDefaultAsync(Entity.IsActiveExpr(), ct)
    .EnsureFound("Entity not active");

Phase 4: Verify

Run affected tests
Verify no behavior change
Check code compiles
Review for consistency

Project-Specific Refactorings

Handler to Helper

// BEFORE: Reused logic in multiple handlers
var employee = await repo.FirstOrDefaultAsync(Employee.UniqueExpr(userId, companyId), ct)
    ?? await CreateEmployeeAsync(userId, companyId, ct);

// AFTER: Extracted to Helper
// In EmployeeHelper.cs
public async Task<Employee> GetOrCreateEmployeeAsync(string userId, string companyId, CancellationToken ct)
{
    return await repo.FirstOrDefaultAsync(Employee.UniqueExpr(userId, companyId), ct)
        ?? await CreateEmployeeAsync(userId, companyId, ct);
}

Handler to Repository Extension

// BEFORE: Query logic in handler
var employees = await repo.GetAllAsync(
    e => e.CompanyId == companyId && e.Status == Status.Active && e.DepartmentIds.Contains(deptId), ct);

// AFTER: Extracted to extension
// In EmployeeRepositoryExtensions.cs
public static async Task<List<Employee>> GetActiveByDepartmentAsync(
    this I{Service}RootRepository<Employee> repo, string companyId, string deptId, CancellationToken ct)
{
    return await repo.GetAllAsync(
        Employee.OfCompanyExpr(companyId)
            .AndAlso(Employee.IsActiveExpr())
            .AndAlso(e => e.DepartmentIds.Contains(deptId)), ct);
}

Mapping to DTO

// BEFORE: Mapping in handler
var config = new AuthConfig
{
    ClientId = req.Dto.ClientId,
    Secret = encryptService.Encrypt(req.Dto.Secret)
};

// AFTER: DTO owns mapping
// In AuthConfigDto.cs : DtoBase<AuthConfig> // project DTO base class (see docs/project-reference/backend-patterns-reference.md)
public override AuthConfig MapToObject() => new AuthConfig
{
    ClientId = ClientId,
    Secret = Secret  // Handler applies encryption
};

// In Handler
var config = req.Dto.MapToObject()
    .With(c => c.Secret = encryptService.Encrypt(c.Secret));

Index Impact Check

[IMPORTANT] Database Performance Protocol (MANDATORY):

Paging Required — ALL list/collection queries MUST ATTENTION use pagination. NEVER load all records into memory. Verify: no unbounded GetAll(), ToList(), or Find() without Skip/Take or cursor-based paging.

Index Required — ALL query filter fields, foreign keys, and sort columns MUST ATTENTION have database indexes configured. Verify: entity expressions match index field order, database collections have index management methods, migrations include indexes for WHERE/JOIN/ORDER BY columns.

When extracting expressions or moving queries, verify index coverage:

[ ] New expression fields have indexes in DbContext?
[ ] Moved queries still use indexed fields?
[ ] Refactored filters maintain index selectivity order?
[ ] List queries use pagination (no unbounded GetAll/ToList)?

Safety Checklist

Before any refactoring:

[ ] Searched all usages across ALL services (static + dynamic + reflection)?
[ ] Test coverage exists?
[ ] Documented in todo list?
[ ] Changes are incremental?
[ ] No behavior change verified?
[ ] Confidence declared — Confidence: X% with evidence list?

If ANY checklist item incomplete → STOP. State "Insufficient evidence to proceed."

Code Responsibility Refactoring (Priority Check)

⚠️ MUST ATTENTION READ: CLAUDE.md "Code Responsibility Hierarchy" for the Entity/Model > Service > Component layering rule. When refactoring, verify logic is in the LOWEST appropriate layer.

Component HTML & SCSS Standards

⚠️ MUST ATTENTION READ: CLAUDE.md "Component HTML Template Standard (BEM Classes)" and docs/project-reference/scss-styling-guide.md for BEM class requirements and host/wrapper styling patterns. When refactoring components, ensure all HTML elements have proper BEM classes.

Anti-Patterns

Big Bang Refactoring: Make small, incremental changes
Refactoring Without Tests: Ensure coverage first
Mixing Refactoring with Features: Do one or the other
Breaking Public APIs: Maintain backward compatibility
Logic in Wrong Layer: Leads to duplicated code - move to lowest appropriate layer

Graph-Assisted Investigation — MANDATORY when .code-graph/graph.db exists.

HARD-GATE: MUST ATTENTION run at least ONE graph command on key files before concluding any investigation.

Pattern: Grep finds files → trace --direction both reveals full system flow → Grep verifies details

| Task | Minimum Graph Action | | ------------------- | -------------------------------------------- | | Investigation/Scout | trace --direction both on 2-3 entry files | | Fix/Debug | callers_of on buggy function + tests_for | | Feature/Enhancement | connections on files to be modified | | Code Review | tests_for on changed functions | | Blast Radius | trace --direction downstream |

CLI: python .claude/scripts/code_graph {command} --json. Use --node-mode file first (10-30x less noise), then --node-mode function for detail.

Run python .claude/scripts/code_graph connections <file> --json on refactored files to find all consumers needing updates.

Graph Intelligence (RECOMMENDED if graph.db exists)

If .code-graph/graph.db exists, enhance analysis with structural queries:

Impact of restructuring -- trace callers: python .claude/scripts/code_graph query callers_of <function> --json
Impact of restructuring -- check importers: python .claude/scripts/code_graph query importers_of <module> --json
Batch analysis: python .claude/scripts/code_graph batch-query file1 file2 --json

See  block above for graph query patterns.

Graph-Trace for Refactoring Impact

When graph DB is available, BEFORE refactoring, trace to verify all consumers:

python .claude/scripts/code_graph trace <file-to-refactor> --direction downstream --json — all downstream consumers that depend on this code
python .claude/scripts/code_graph trace <file-to-refactor> --direction both --json — full picture: callers + consumers
Flag any consumer NOT covered in your refactoring plan — it may break silently

code-simplifier
code-review

Workflow Recommendation

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS: If you are NOT already in a workflow, you MUST ATTENTION use AskUserQuestion to ask the user. Do NOT judge task complexity or decide this is "simple enough to skip" — the user decides whether to use a workflow, not you:

Activate refactor workflow (Recommended) — scout → investigate → plan → code → review → sre-review → test → docs

Execute /refactoring directly — run this skill standalone

AI Agent Integrity Gate (NON-NEGOTIABLE)

Completion ≠ Correctness. Before reporting ANY work done, prove it:

Grep every removed name. Extraction/rename/delete touched N files? Grep confirms 0 dangling refs across ALL file types.

Ask WHY before changing. Existing values are intentional until proven otherwise. No "fix" without traced rationale.

Verify ALL outputs. One build passing ≠ all builds passing. Check every affected stack.

Evaluate pattern fit. Copying nearby code? Verify preconditions match — same scope, lifetime, base class, constraints.

New artifact = wired artifact. Created something? Prove it's registered, imported, and reachable by all consumers.

Closing Reminders

IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting
IMPORTANT MUST ATTENTION search codebase for 3+ similar patterns before creating new code
IMPORTANT MUST ATTENTION cite file:line evidence for every claim (confidence >80% to act)
IMPORTANT MUST ATTENTION add a final review todo task to verify work quality MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:
IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.
IMPORTANT MUST ATTENTION cite file:line evidence for every claim. Confidence >80% to act, <60% = do NOT recommend.
IMPORTANT MUST ATTENTION check DRY via OOP, right responsibility layer, SOLID. Grep for dangling refs after moves.
IMPORTANT MUST ATTENTION run at least ONE graph command on key files when graph.db exists. Pattern: grep → trace → verify.

Agent Skills: Code Refactoring

Install this agent skill to your local

Skill Files