[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 ask user whether to skip.

Prerequisites: MUST READ before executing:

• .claude/skills/shared/understand-code-first-protocol.md

• .claude/skills/shared/evidence-based-reasoning-protocol.md

• docs/project-reference/domain-entities-reference.md — Domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)

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

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

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

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

Related

• code-review

• refactoring

IMPORTANT Task Planning Notes (MUST FOLLOW)

• Always plan and break work into many small todo tasks

• Always add a final review todo task to verify work quality and identify fixes/enhancements

Workflow Recommendation

IMPORTANT MUST: If you are NOT already in a workflow, use AskUserQuestion to ask the user:

• Activate quality-audit workflow (Recommended) — code-simplifier → review-changes → code-review

• Execute /code-simplifier directly — run this skill standalone

Next Steps

MANDATORY IMPORTANT MUST after completing this skill, use AskUserQuestion to recommend:

• "/review-changes (Recommended)" — Review all changes before commit

• "/code-review" — Full code review

• "Skip, continue manually" — user decides

Closing Reminders

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