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

Understand Code First — Search codebase for 3+ similar implementations BEFORE writing any code. Read existing files, validate assumptions with grep evidence, map dependencies via graph trace. Never invent new patterns when existing ones work. MUST READ .claude/skills/shared/understand-code-first-protocol.md for full protocol and checklists. Design Patterns Quality — Priority checks: (1) DRY via OOP — same-suffix classes MUST share base class, 3+ similar patterns → extract. (2) Right Responsibility — logic in LOWEST layer (Entity > Service > Component). (3) SOLID principles. MUST READ .claude/skills/shared/design-patterns-quality-checklist.md for full protocol and checklists.

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

Frontend/UI Context (if applicable)

When this task involves frontend or UI changes,

UI System Context — For frontend/UI/styling tasks, MUST READ these BEFORE implementing: frontend-patterns-reference.md (component base classes, stores, forms), scss-styling-guide.md (BEM methodology, SCSS vars, responsive), design-system/README.md (design tokens, component inventory, icons). MUST READ .claude/skills/shared/ui-system-context.md for full protocol and checklists.

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

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

See .claude/skills/shared/graph-intelligence-queries.md for full query reference.

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

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

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 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. MANDATORY IMPORTANT MUST READ the following files before starting:

MUST READ .claude/skills/shared/understand-code-first-protocol.md before starting
MUST READ .claude/skills/shared/design-patterns-quality-checklist.md before starting
MUST READ .claude/skills/shared/ui-system-context.md before starting

code-simplifier