Code Simplifier Skill Skill

[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.

Prerequisites: MUST ATTENTION READ before executing:

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

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)

External Memory: For complex or lengthy work (research, analysis, scan, review), write intermediate findings and final results to a report file in plans/reports/ — prevents context loss and serves as deliverable.

Evidence Gate: MANDATORY IMPORTANT MUST ATTENTION — every claim, finding, and recommendation requires file:line proof or traced evidence with confidence percentage (>80% to act, <80% must verify first).

OOP & DRY Enforcement: MANDATORY IMPORTANT MUST ATTENTION — flag duplicated patterns that should be extracted to a base class, generic, or helper. Classes in the same group or suffix (ex *Entity, *Dto, *Service, etc...) MUST ATTENTION inherit a common base (even if empty now — enables future shared logic and child overrides). Verify project has code linting/analyzer configured for the stack.

Quick Summary

Goal: Simplify and refine code for clarity, consistency, and maintainability while preserving all functionality.

MANDATORY IMPORTANT MUST ATTENTION Plan ToDo Task to READ the following project-specific reference docs:

docs/project-reference/code-review-rules.md — anti-patterns, review checklists, quality standards (READ FIRST)

project-structure-reference.md — project patterns and structure

If files not found, search for: project documentation, coding standards, architecture docs.

Workflow:

Identify Targets — Recent git changes or specified files (skip generated/vendor)
Analyze — Find complexity hotspots (nesting >3, methods >20 lines), duplicates, naming issues
Apply Simplifications — One refactoring type at a time following KISS/DRY/YAGNI
Verify — Run related tests, confirm no behavior changes
Fresh-Context Verification — Spawn code-reviewer sub-agent to validate simplifications

Key Rules:

Preserve all existing functionality; no behavior changes
Follow platform patterns (Entity expressions, fluent helpers, project store base (search for: store base class), BEM)
Keep tests passing after every change

Frontend/UI Context (if applicable)

When this task involves frontend or UI changes,

UI System Context — For ANY task touching .ts, .html, .scss, or .css files:

MUST ATTENTION READ before implementing:

docs/project-reference/frontend-patterns-reference.md — component base classes, stores, forms

docs/project-reference/scss-styling-guide.md — BEM methodology, SCSS variables, mixins, responsive

docs/project-reference/design-system/README.md — design tokens, component inventory, icons

Reference docs/project-config.json for project-specific paths.

Component patterns: docs/project-reference/frontend-patterns-reference.md
Styling/BEM guide: docs/project-reference/scss-styling-guide.md
Design system tokens: docs/project-reference/design-system/README.md

Code Simplifier Skill

Simplify and refine code for clarity, consistency, and maintainability.

Usage

/code-simplifier                    # Simplify recently modified files
/code-simplifier path/to/file.ts    # Simplify specific file
/code-simplifier --scope=function   # Focus on function-level simplification

Simplification Mindset

Be skeptical. Verify before simplifying. Every change needs proof it preserves behavior.

Do NOT assume code is redundant — verify by tracing call paths and reading implementations
Before removing/replacing code, grep for all usages to confirm nothing depends on the current form
Before flagging a convention violation, grep for 3+ existing examples — codebase convention wins
Every simplification must include file:line evidence of what was verified
If unsure whether simplification preserves behavior, do NOT apply it

What It Does

Analyzes code for unnecessary complexity
Identifies opportunities to simplify without changing behavior
Applies KISS, DRY, and YAGNI principles
Preserves all existing functionality
Follows convention — grep for 3+ existing patterns before applying simplifications

Readability Checklist (MUST ATTENTION evaluate)

Before finishing, verify the code is easy to read, easy to maintain, easy to understand:

Schema visibility — If a function computes a data structure (object, map, config), add a comment showing the output shape so readers don't have to trace the code
Non-obvious data flows — If data transforms through multiple steps (A → B → C), add a brief comment explaining the pipeline
Self-documenting signatures — Function params should explain their role; remove unused params
Magic values — Replace unexplained numbers/strings with named constants or add inline rationale
Naming clarity — Variables/functions should reveal intent without reading the implementation

Simplification Targets

Redundant code paths
Over-engineered abstractions
Unnecessary comments (self-documenting code preferred)
Complex conditionals that can be flattened
Verbose patterns that have simpler alternatives

Execution

Use the code-simplifier:code-simplifier subagent:

Task(subagent_type="code-simplifier:code-simplifier", prompt="Review and simplify [target files]")

Examples

Before:

function getData() {
    const result = fetchData();
    if (result !== null && result !== undefined) {
        return result;
    } else {
        return null;
    }
}

After:

function getData() {
    return fetchData() ?? null;
}

Workflow

Identify targets
- If no arguments: git diff --name-only HEAD~1 for recent changes
- If arguments provided: use specified files/patterns
- Skip: generated code, migrations, vendor files
Analyze each file
- Identify complexity hotspots (nesting > 3, methods > 20 lines)
- Find duplicated code patterns
- Check naming clarity
Design Pattern Assessment (per design-patterns-quality-checklist.md)
- DRY/Abstraction: Flag duplicate patterns extractable to base class, generic, or helper
- Right Responsibility: Verify logic is in lowest appropriate layer (Entity > Service > Component)
- Pattern Opportunities: Check for creational/structural/behavioral pattern opportunities (switch→Strategy, scattered new→Factory, etc.)
- Anti-Patterns: Flag God Objects, Copy-Paste, Circular Dependencies, Singleton overuse
- Guard against over-engineering: Only recommend patterns with evidence of 3+ occurrences of the problem
Apply simplifications
- One refactoring type at a time
- Preserve all functionality
- Follow platform patterns
Verify
- Run related tests if available
- Confirm no behavior changes

Project Patterns

Backend

Extract to entity static expressions (search for: entity expression pattern)
Use fluent helpers (search for: fluent helper pattern in docs/project-reference/backend-patterns-reference.md)
Move mapping to DTO mapping methods (search for: DTO mapping pattern)
Use project validation fluent API (see docs/project-reference/backend-patterns-reference.md)
Check entity expressions have database indexes
Verify document database index methods exist for collections

[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.

Frontend

Use project store base (search for: store base class) for state management
Apply subscription cleanup pattern (search for: subscription cleanup pattern) to all subscriptions
Ensure BEM class naming on all template elements
Use platform base classes (project base component (search for: base component class), project store component base (search for: store component base class))

Constraints

Preserve functionality — No behavior changes
Keep tests passing — Verify after changes
Follow patterns — Use platform conventions
Document intent — Add comments only where non-obvious
Doc staleness — After simplifications, cross-reference changed files against related docs (feature docs, test specs, READMEs); flag any that need updating

Shared Protocol Duplication Policy — Inline protocol content in skills (wrapped in ) is INTENTIONAL duplication. Do NOT extract, deduplicate, or replace with file references. AI compliance drops significantly when protocols are behind file-read indirection. To update: edit .claude/skills/shared/sync-inline-versions.md first, then grep SYNC:protocol-name and update all occurrences.

Graph Intelligence (RECOMMENDED if graph.db exists)

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

Verify no callers break after simplification: python .claude/scripts/code_graph query callers_of <function> --json
Check dependents: python .claude/scripts/code_graph query importers_of <module> --json
Batch analysis: python .claude/scripts/code_graph batch-query file1 file2 --json

Graph-Trace Before Simplification

When graph DB is available, BEFORE simplifying code, trace to understand what depends on it:

python .claude/scripts/code_graph trace <file-to-simplify> --direction downstream --json — all downstream consumers that depend on current behavior
Verify simplified code preserves the same interface for all traced consumers
Cross-service MESSAGE_BUS consumers are especially fragile — they may depend on exact message shape

code-review
refactoring

Fresh-Context Verification (MANDATORY after simplifications)

After tests pass, spawn a fresh code-reviewer sub-agent to verify simplifications from an unbiased perspective:

Fresh-Context Review — Eliminate AI confirmation bias. Spawn code-reviewer sub-agent for re-review iterations — zero memory of prior fixes.

When: After fixing review findings. NOT for initial review (needs intent context).

How: Agent(subagent_type: "code-reviewer") with self-contained prompt: git diff scope + docs/project-reference/code-review-rules.md + checklist summary. Prompt MUST NOT reference prior findings. Report to plans/reports/review-iteration-{N}-{date}.md.

Result: PASS → proceed | FAIL (iteration < 3) → fix ALL issues, spawn NEW agent | FAIL (iteration 3) → escalate to user | Issue count increased → STOP, escalate

Max 3 iterations. Track [Re-Review {N}/3] tasks per iteration.

Simplification-specific sub-agent prompt:

Agent({
  description: "Fresh-context simplification verification",
  subagent_type: "code-reviewer",
  prompt: "## Task\nReview ALL uncommitted changes. These are code simplification refactors.\nYou are reviewing with completely fresh eyes — no knowledge of WHY simplifications were made.\n\n## Verify\n1. No behavior changes (logic equivalence preserved)\n2. Simplifications actually improved readability\n3. No accidental removal of necessary code\n4. Conventions still followed (grep 3+ patterns)\n5. No new issues introduced by refactoring\n\nRead docs/project-reference/code-review-rules.md for project standards.\n\n## Output\n- **Status**: PASS or FAIL\n- **Issues**: [list with file:line evidence]\n- **Reverts Needed**: [list of changes that should be reverted]\n\nEvery finding MUST have file:line evidence."
})

If sub-agent flags issues with simplifications → revert problematic changes and log reasoning.

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 quality-audit workflow (Recommended) — code-simplifier → review-changes → code-review

Execute /code-simplifier directly — run this skill standalone

Next Steps

MANDATORY IMPORTANT MUST ATTENTION — NO EXCEPTIONS after completing this skill, you MUST ATTENTION use AskUserQuestion to present these options. Do NOT skip because the task seems "simple" or "obvious" — the user decides:

"/workflow-review-changes (Recommended)" — Review all changes before commit
"/code-review" — Full code review
"Skip, continue manually" — user decides

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

MANDATORY IMPORTANT MUST ATTENTION break work into small todo tasks using TaskCreate BEFORE starting. MANDATORY IMPORTANT MUST ATTENTION validate decisions with user via AskUserQuestion — never auto-decide. MANDATORY IMPORTANT MUST ATTENTION add a final review todo task to verify work quality. MANDATORY IMPORTANT MUST ATTENTION READ the following files before starting:

MANDATORY IMPORTANT MUST ATTENTION search 3+ existing patterns and read code BEFORE any modification. Run graph trace when graph.db exists.
MANDATORY IMPORTANT MUST ATTENTION check DRY via OOP (same-suffix → base class), right responsibility (lowest layer), SOLID. Grep for dangling refs after changes.
MANDATORY IMPORTANT MUST ATTENTION read frontend-patterns-reference, scss-styling-guide, design-system/README before any UI change.

Agent Skills: Code Simplifier Skill

Install this agent skill to your local

Skill Files