Codex compatibility note:
- Invoke
$skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author .claude/**; mirrors are generated.
- Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
- Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
- Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required
spawn_agent subagent(s) for that task.
- Preserve protocol order unless the user approves a deviation. Workflows use
$start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.
[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule.
[BLOCKING] Before each step or sub-skill call, update todo tracking: set in_progress when step starts, set completed when step ends.
[BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason.
[BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Quick Summary
Goal: Lower the cost of the next change — cut coupling, hidden state, duplicated knowledge, unclear intent — by simplifying and refining code for clarity, consistency, and maintainability without altering any observable behavior. — why: every simplification serves future change cost, not aesthetics.
Summary: (read-this-if-nothing-else digest — purpose + every main step)
- Purpose — skeptical-first MUTATOR, not a suggester: grep all usages + trace consumers (grep/read; an optional graph downstream trace may hint at more) and cite
file:line BEFORE touching anything; apply a simplification ONLY when certain it preserves behavior, never when unsure. — why: an unverified "safe" rewrite silently breaks a downstream consumer.
- Main steps, run in order: (1) Phase 0 Detect target + scope from project config/source; (2) Identify Targets — recent git changes or named files, HARD-SKIP generated/migration/vendor; (3) Analyze via the 5 Simplification Dimensions, marking inapplicable ones N/A with a reason; (4) Apply one refactoring type at a time (KISS/DRY/YAGNI, behavior-preserving); (5) Verify related tests after EACH change; (6) Self-Recursive Loop (analyze→simplify→verify) until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred) or a no-progress/unsafe/owner-decision stop hits — do NOT spawn a fresh-context reviewer for your own findings; (7) Self-Review Gate.
- The 5 Simplification Dimensions (step 3): readability · DRY/abstraction (compare real repetition; apply YAGNI) · responsibility based on the project's documented architecture and evidenced ownership · complexity reduction · persistence/query bounds on applicable changed paths only (otherwise N/A) — every technique answers ONE test: does this make the next change cheaper?
- Self-Review Gate (step 7) — this skill owns review of its own output: when it changed any file, self-invoke
$code-quality-review scoped to ONLY those changed files (recursion-safe leaf — NEVER $changes-review); skip + log the reason when nothing changed. Only an explicit --defer=review from a caller that runs a FULL review of the settled state afterwards skips it (see .claude/skills/workflow-review-changes/references/caller-mode.md); no flag means the gate runs. — why: the simplifier rewrites code after the main review batch, so its output ships unreviewed without this gate.
--report-only: read-only mode for a caller that owns every fix (e.g. a review skill's simplification dimension or a workflow review barrier) — steps 1–3 only, each finding with file:line + proposed change + behavior-preservation note, no edit of any file, no nested sub-agent, no user question, only the report written; see Report-Only Mode.
- Read FIRST:
code-review-rules.md (anti-patterns/checklists) then project-structure-reference.md, both under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides) — before any modification.
MANDATORY IMPORTANT MUST ATTENTION Plan task to READ:
code-review-rules.md under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides) — anti-patterns, review checklists (READ FIRST)
project-structure-reference.md — project patterns/structure
If not found, search for: project documentation, coding standards, architecture docs.
Workflow:
- Phase 0: Detect — Classify target types present in the project (source, UI/client, tests, configuration, or other) and scope
- Identify Targets — Recent git changes or specified files (skip generated/migration/vendor)
- Analyze — Apply simplification dimensions (see below)
- Apply — One refactoring type at a time following KISS/DRY/YAGNI
- Verify — Run related tests, confirm no behavior changes; when a caller runs the tests once, last (
SYNC:verify-last-order, e.g. a --tests=defer review fix loop), verify statically instead — re-read the diff against the covering tests and run none, the caller's single verify proves them
- Self-Recursive Check — Re-run this skill's simplification analysis until the current round's exit bar is clear: Round 1 requires zero validated findings at any severity, with no-edit LOW deferral allowed; every applied fix requires a fresh full review (
SYNC:review-policy). From Round 2 onward only validated CRITICAL/HIGH/MEDIUM findings reopen the loop, while LOW findings are recorded as deferred and do not justify another cycle. Failed binary gates always block.
- Self-Review Gate (MANDATORY when code changed) — If this skill modified any files, self-invoke
$code-quality-review scoped to ONLY those changed files; skip + log if nothing changed, or when the caller passed --defer=review (record Self-review deferred to caller post-fix FULL review)
Key Rules:
- AI surface? Only if the code holds a model call, prompt, agent, tool/MCP, retrieval or eval (see
node .claude/scripts/ai-signal-scan.cjs): read .claude/skills/shared/protocols/ai-engineering-gate.md; never simplify away a timeout, retry bound, step or cost cap, output validation, approval gate or retrieval evidence check; otherwise skip this line.
- Preserve all existing functionality — no behavior changes
- Apply conventions supported by
docs/project-config.json, its referenced project docs, and relevant existing code; treat an explicit N/A or absent stack as a signal to verify the target, not as a missing pattern to invent
- Easy to Change is the primary simplification goal for source files; DRY, SOLID, abstraction, and patterns are valid only when they lower future edit sites or cognitive load
- Tests pass after every change
- Apply simplification only when certain it preserves behavior — NEVER apply when unsure
Contents
Report-Only Mode (--report-only)
Use when a caller needs simplification opportunities as findings without edits — e.g. a review skill running its simplification dimension, a workflow parallel review barrier, or a review batch — and another step owns every fix. --report-only in $ARGUMENTS selects it; without the flag every step applies unchanged.
MANDATORY — when --report-only is passed, read .claude/skills/workflow-review-changes/references/caller-mode.md in full FIRST. It holds the shared caller rules: a --report-only pass returns one report with no source edits, the caller fixes once and requests fresh passes, and a child never mutates source in parallel or runs a nested loop. The rules below are this skill's own.
Review lens in workflow-review-changes. This mode can serve as the simplification lens inside the review barrier: report the findings, and the review's fix --target=review step applies the validated simplifications after findings validation.
- Run steps 1–3 only (Phase 0 Detect → Identify Targets → Analyze). Apply, Verify, the Self-Recursive loop, and the Self-Review Gate do not run: edit NO file — source, test, config, or doc. The caller runs its own findings-validation gate and owns every fix and re-review. — why: a simplifier that edits inside a review barrier races the diff every sibling reviewer is reading.
- Every finding carries:
file:line · the simplification dimension · the proposed change (concrete before → after, or the exact edit described) · a behavior-preservation note (the usages and consumers traced — grep/read evidence, plus any graph hint — and why observable behavior stays unchanged) · severity per SYNC:severity-rubric · confidence. A proposal whose behavior preservation cannot be proven is reported as behavior-change risk, never as a safe simplification. — why: the fixer applies it later without this skill's trace, so the evidence must travel with the finding.
- No nested fan-out. Skip the
spawn_agent(agent_type="code-simplifier", ...) execution path; analyze sequentially in this context.
- Report file. Write it to
tmp/reports/code-simplifier-{date}-{slug}.md, appended per file.
For this mode the declared step order ends at step 3; stopping there is the mode's contract, not a skipped step.
Phase 0: Artifact Detection
MUST ATTENTION classify before simplifying — detection drives focus and optional escalation only:
| Artifact Type |
Detection |
Key Focus |
| Source |
Target paths and file types identified from project config or user scope |
Preserve behavior; apply only responsibilities and conventions evidenced for the relevant code |
| UI/client (if any) |
Affected UI paths identified from project config or source |
Use configured UI, state, lifecycle, and styling conventions only when present; otherwise follow local evidence |
| Tests |
Test paths and runner identified by project config or source |
Preserve the assertions, async behavior, isolation, and runner conventions that apply to this project |
| Generated/migration/vendor |
Generated markers, configured paths, or vendor/migration directories |
SKIP generated, migration, and vendor code |
File extensions and stack-specific names in prompts or examples are search clues, not requirements. Classify the actual target using the project's config, references, and source.
Optional escalation by artifact:
| Artifact |
Escalate only when |
| Source code/diffs |
Broad review is requested after simplifier loop is clean |
| Security-sensitive |
Security-specific risk is present |
| Performance-critical |
Performance behavior is part of the change |
| Plans, docs, specs |
Artifact review is explicitly requested |
First Principle — Easy to Change · Easy to Scale · Easy to Maintain
The full gate is SYNC:core-engineering-principles (protocol guide below; a hook delivers its text); its closing digest ends this file.
Skill focus: favor project-owned boundaries around external libraries (for example component/service input-output contracts) when they localize future library changes; reject pass-through wrappers that add ceremony without lowering change cost.
Simplification Mindset
Skeptical-first: Verify before simplifying. Every change needs proof preserving behavior.
- NEVER assume code redundant — trace call paths and read implementations first
- Before removing/replacing: grep all usages confirming nothing depends on current form
- Before flagging convention violation: grep 3+ existing examples — codebase convention wins
- Every simplification requires
file:line evidence of what was verified
- Apply simplification only when certain it preserves behavior; if unsure → DO NOT apply
Simplification Dimensions
Dimension-based reasoning replaces fixed checklists. Each dimension has a Think: prompt forcing first-principles reasoning.
Dimension 1: Readability
Think: Would a new engineer understand this in 30 seconds? What forces multiple file traces?
- Schema visibility: functions computing data structures need output-shape comment
- Non-obvious pipelines: A→B→C transformations need brief pipeline explanation
- Self-documenting signatures: params explain role; remove unused params
- Magic values: replace unexplained numbers/strings with named constants
- Naming clarity: names reveal intent without reading implementation
Dimension 2: DRY & Abstraction
Think: Is the same responsibility repeated, and would a shared abstraction reduce future change cost without hiding intentional differences?
- Search by behavior and responsibility; names or type suffixes are clues for discovery, not proof that types share a base or contract
- Extract a shared function, module, or type only when repeated behavior and change reasons align and the abstraction reduces edit sites or cognitive load
- YAGNI gate: NEVER extract for hypothetical future use — 3+ similar occurrences prompt comparison, not automatic extraction
Dimension 3: Right Responsibility
Think: Which module or layer owns this invariant under the project's documented architecture and current call paths?
- Read the project structure and relevant pattern references, then trace callers to identify the owner supported by evidence
- When those docs are silent, follow a consistent existing code pattern; if no owner is evidenced, keep the change local and report the uncertainty
- Place transformations at the boundary documented or demonstrated by this project; do not create an assumed layer, entity, or DTO convention
Dimension 4: Complexity Reduction
Think: What is cognitive load? Can nesting/conditionals flatten?
- Inspect nesting and method size for obscured intent; use early returns or extraction when they lower cognitive load while preserving behavior. Line/depth counts are clues, never refactor mandates.
- Simplify complex conditions locally; choose a shared dispatch/pattern only when real variation and ownership justify its indirection.
Dimension 5: Data Access and Storage (when applicable)
Apply this dimension only when project config/reference docs identify a persistence system or relevant target code proves it is used, and the changed path reads or writes that system. If no database/storage is configured or evidenced in source, or the changed code does not use its query/index model, mark this dimension N/A — reason; do not require paging or indexes for unrelated code.
Think: Can this particular access path exceed its intended bound, and what evidence shows the configured or code-evidenced store needs a different access path?
- Result bounds: For a changed list/search/report path over persistent data, check expected result size and the caller contract. When results can grow and the project supports it, use its documented paging/window/cursor convention; otherwise cite the evidence that bounds the result. Names such as
GetAll, ToList, Find, or Skip/Take are search examples, not defects by themselves.
- Index fit: Only for a database configured or evidenced in source and a changed query path that uses it (or a schema/index change supporting that query), inspect filters, ordering, joins, schema/index definitions, and query plans when available. Recommend an index only when evidence supports it and account for write/storage cost; do not demand indexes on every filter, foreign key, or sort field.
- Other storage models: Follow the configured and code-evidenced access, query, and bound conventions for the storage in use. If persistent data is not in the changed path, record
N/A — reason.
Project Patterns
- Resolve affected paths through
docs/project-config.json and its configured docs index; load only relevant backend/API, UI/client, test or other references, honoring custom paths and documented N/A.
- Missing/silent references: inspect at least three fitting local examples. If none exists, keep the change minimal and report the gap; never invent a framework convention.
- Names, extensions and examples do not establish applicability. Require config/reference + changed-code evidence for any layer, class, helper, state tool, styling method or storage API.
- Dimension 5 is
N/A — reason unless config/source confirms a database and the changed path uses its query/index model. UI checks require an evidenced UI surface.
- Before paging/index recommendations, cite config/schema/source evidence and query/runtime behavior.
Graph Intelligence (optional advice)
Optional: when grep and reading files alone may not reveal a high-risk blast radius (shared contract, many callers, cross-module/cross-service flow, public API), the code graph (.code-graph/graph.db) can add callers, dependents and impacted tests. Treat it as a hint, NOT proof: the graph can be stale or incomplete (it lags uncommitted edits and unindexed paths) — verify anything that matters by reading the files/grep. Skip it for low-risk or local changes.
Before simplifying, trace what depends on the target (grep/read; optionally the graph):
python .claude/scripts/code_graph trace <file> --direction downstream --json
Verify simplified code preserves the interface for every traced consumer. When the changed contract crosses a module, process, or service boundary, trace all consumers configured or found in source; message-bus consumers are one example only when the project uses that boundary.
Additional queries:
- Optional hint for callers:
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
Execution
spawn_agent(agent_type="code-simplifier", prompt="Review and simplify [target files]")
Example:
// Before
function getData() {
const result = fetchData();
if (result !== null && result !== undefined) {
return result;
} else {
return null;
}
}
// After
function getData() {
return fetchData() ?? null;
}
Constraints
- Preserve functionality — no behavior changes
- Tests passing — verify after every change
- Follow patterns — use the project's conventions, never invent
- Doc staleness — cross-ref changed files against feature docs, test specs, READMEs; flag updates needed
- Preserve ALL invariants; never weaken a property/mutation test — a refactor MUST keep every
[HARD] §4 rule / §5 invariant intact and MUST NOT delete, relax, or trivialize any property test or mutation test that guards them. If a simplification changes observable behavior, that is NOT a silent change — it is a Dual-Feedback finding (feed the spec AND the tests, then re-review), report it and stop, never ship it. After simplifying, the package MUST still pass the SAME property/mutation bar it passed before — green tests on a weakened bar are not a pass.
Self-Recursive Verification (MANDATORY after simplifications)
After applying simplifications, follow the Self-Recursive Simplification Loop below. It owns round closure, deferred LOWs, no-progress/unsafe stops and the subsequent Self-Review Gate. For caller-owned verify-last execution, use the static-verification exception in Workflow Step 5.
Self-Review Gate (MANDATORY when this skill changed code)
This skill is a code MUTATOR. It owns the review of its own output. Once the self-recursive simplification loop above is clean, gate the result:
- Caller deferral.
--defer=review in $ARGUMENTS means the caller runs a FULL review of the settled whole target after this skill returns (see .claude/skills/workflow-review-changes/references/caller-mode.md). Skip steps 1–3, record Self-review deferred to caller post-fix FULL review, and return the exact list of files this skill changed so that review covers them. Without the flag — including a bare invocation by another skill — run the gate.
- Did this skill modify any files? Determine the exact set of files this skill changed (its own edits — not the whole working tree).
- No files changed → SKIP this gate and log the skip reason ("code-simplifier made no changes — no self-review needed"). Done.
- Files changed → continue.
- Self-invoke
$code-quality-review scoped to ONLY the changed files. Pass the explicit changed-file set as the review target — not the full diff, not unrelated files.
- Integrate the
$code-quality-review findings. If it surfaces blocking issues caused by the simplification, fix them (behavior-preserving only) and re-run the self-recursive loop + this gate. If issues are out of simplification scope, report them up — do not silently drop.
Recursion safety: $code-quality-review is a LEAF review skill — it does NOT invoke $code-simplifier back, so there is no cycle. Use $code-quality-review here, NEVER $workflow-review-changes (its sequence contains a code-simplifier step and would recurse) or $changes-review (a full-diff review heavier than this file-scoped gate needs).
Why this gate exists: $code-simplifier rewrites code after the main review batch has already run. Without this gate, the simplifier's output would ship unreviewed. This gate moves that review responsibility into the mutator itself — so the workflow-review-changes workflow no longer needs a separate $code-quality-review step after $code-simplifier.
Used standalone (outside a review workflow), this self-review gate is sufficient for the simplifier's own changes; you may still finish with $changes-review or the active workflow's review gate for broader, whole-changeset coverage.
Next Steps
EXEMPT when invoked by a parent skill or workflow step, when running as a sub-agent, or under --report-only: return the result to the caller; skip ask user question tool.
MANDATORY — NO EXCEPTIONS after completing, use ask user question tool:
- "$workflow-review-changes (Recommended)" — Review all changes before commit
- "$code-quality-review" — Full code review
- "Skip, continue manually" — user decides
AI Agent Integrity Gate (NON-NEGOTIABLE)
Completion ≠ Correctness. Before reporting work done, prove it:
- Grep every removed name. Extraction/rename/delete → grep confirms 0 dangling refs across ALL file types.
- Ask WHY before changing. Existing values 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? Prove registered, imported, reachable by all consumers.
[IMPORTANT] Use todo tracking to break ALL work into small tasks BEFORE starting. Keep task depth proportional to the work.
Prerequisites: MUST ATTENTION READ before executing:
domain-entities-reference.md under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides) — domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)
External Memory: Complex/lengthy work → write findings to tmp/reports/. Prevents context loss, serves as deliverable.
Evidence Gate: MANDATORY — every claim, finding, recommendation requires file:line proof or traced evidence (confidence >80% to act, <80% verify first).
DRY and abstraction fit: Compare repeated behavior and responsibility before proposing a shared abstraction. Recommend a function, module, or type only when evidence shows the instances share a reason to change and the abstraction reduces future edits; names or suffixes alone do not justify a base type. Verify any project-specific lint/analyzer rule in its config.
Self-Recursive Simplification Loop
Purpose: Avoid spending tokens on a fresh-context review of this skill's own findings. The simplifier owns its own convergence loop; broader review workflows can still run after the simplifier reports clean.
Loop:
- Analyze the current target/diff for simplification findings with
file:line evidence.
- Apply only behavior-preserving simplifications that satisfy the evidence gate.
- Run targeted verification after each change set.
- Re-read the updated diff and re-run this skill's simplification dimensions.
- Repeat until this skill's current round bar is clear: round 1 has zero validated simplification findings; round 2 have zero validated CRITICAL/HIGH/MEDIUM findings, with LOWs recorded as deferred.
Stop conditions:
- The same simplification finding repeats for 3 passes with no progress.
- A simplification needs product/owner input or has behavior-change risk.
- Verification cannot run or cannot prove behavior preservation.
Rules:
- Do not spawn a fresh-context reviewer just because simplifications were applied.
- Do not re-review known findings in a fresh context before fixing them.
- Do not hand off until the self-recursive pass clears the current round bar; never silently discard deferred LOWs.
- After the self-recursive loop is clean, run the Self-Review Gate — if any files were changed, self-invoke
$code-quality-review scoped to those files (recursion-safe leaf skill); skip + log if nothing changed or the caller passed --defer=review.
Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.
complexity-prevention — Change-cost lens on complexity (Ousterhout); designing or reviewing code → .claude/skills/shared/protocols/complexity-prevention.md
core-engineering-principles — Core quality gate: easy to change, easy to scale, easy to maintain, judged by future change cost; planning, implementing or reviewing any change → .claude/skills/shared/protocols/core-engineering-principles.md
design-patterns-quality — Design quality: one owner per rule, fitted patterns, no speculative abstraction; designing or reviewing code structure → .claude/skills/shared/protocols/design-patterns-quality.md
review-decision-autonomy — Choose supported review decisions and ask before extending the round budget; running any review or audit skill or mode → .claude/skills/shared/protocols/review-decision-autonomy.md
severity-rubric — One consequence-based Critical, High, Medium, Low scale for every finding and gate; classifying a finding or deciding whether a review round passes → .claude/skills/shared/protocols/severity-rubric.md
shared-protocol-duplication-policy — Protocol copies in carriers are intentional: edit the canonical source, then propagate; editing a shared protocol or its carriers → .claude/skills/shared/protocols/shared-protocol-duplication-policy.md
source-test-drift-check — When source behavior changes, reconcile the affected tests from evidence; code, fix, test or review work changes behavior → .claude/skills/shared/protocols/source-test-drift-check.md
subagent-return-contract — Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.md
ui-system-context — Resolve the project's UI conventions before a UI change; changing a user-interface surface → .claude/skills/shared/protocols/ui-system-context.md
understand-code-first — Read and trace the target and existing patterns before changing code; planning or editing code → .claude/skills/shared/protocols/understand-code-first.md
verify-last-order — Build all phases and write tests, review statically, then verify once with a mutation check; planning or running any code-changing task → .claude/skills/shared/protocols/verify-last-order.md
IMPORTANT MUST ATTENTION cite file:line evidence for every claim; never speculate. Confidence >80% to act, <60% = do NOT recommend; "not enough evidence" is valid output.
IMPORTANT MUST ATTENTION assess change amplification, cognitive load, coupling, leaked detail and invariant ownership from project evidence. Extract only when a real owner or consumer lowers change cost; no universal layer order or numeric threshold.
- MANDATORY Classify every finding Critical/High/Medium/Low by consequence using the affected asset, shipped impact, exposure, reversibility, evidence location, and confidence; Critical/High/MEDIUM remain actionable under the round bar, while LOW is recorded/deferred from round 2 onward.
- MANDATORY A finding names a reachable trigger path (caller, input, state or event that reaches the defect) and a consequence; an unreachable concern is an observation, and unsettled reachability is
NOT VERIFIABLE only when the concern would be MEDIUM or higher (an observation otherwise) — never a speculative LOW.
- MANDATORY Keep binary gates separate from severity: a failed test, security must-fix, required artifact, or parity check blocks at every round and is never relabeled LOW.
- MANDATORY Score-based skills (sre 0-2, perf two-axis) map onto the same four tiers — no parallel severity vocabulary.
Prompt-Enhance Closing Anchors
IMPORTANT MUST ATTENTION follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval; inside a workflow run, $start-workflow → Workflow-step mode bounds this
IMPORTANT MUST ATTENTION for every step/sub-skill call: set in_progress before execution, set completed after execution
IMPORTANT MUST ATTENTION every skipped step MUST include explicit reason; every completed step MUST include concise evidence
IMPORTANT MUST ATTENTION if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses
MUST ATTENTION Decide supported review choices and recommendations, record the rationale, and finish without routine user questions. Keep round-limit extension, indispensable facts and actual action authority; preserve source coverage, validation, tests, read-only boundaries and budgets. Review decisions do not accept open risks or make a failed gate pass.
Closing Reminders
IMPORTANT MUST ATTENTION Goal: Lower the cost of the next change — cut coupling, hidden state, duplicated knowledge, unclear intent — by simplifying and refining code for clarity, consistency, and maintainability without altering any observable behavior. — why: every simplification serves future change cost, not aesthetics.
IMPORTANT MUST ATTENTION Main steps (run in declared order, never skip/merge): (1) Phase 0 Detect target and scope from project config/source → (2) Identify Targets (skip generated/migration/vendor) → (3) Analyze the 5 Dimensions and mark inapplicable ones N/A with a reason → (4) Apply one refactoring type at a time → (5) Verify tests after EACH change → (6) Self-Recursive Loop until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred) → (7) Self-Review Gate ($code-quality-review on changed files; skipped only under --defer=review). — why: AI keeps forgetting the skill's own steps; surfacing them here is the recency anchor.
Protocols in force (concise digest of the SYNC/shared blocks this skill carries):
- Subagent Return Contract: sub-agents return only the summary shape; full detail to report file.
- UI System Context: read frontend-patterns, scss-styling-guide, design-system before touching UI files.
- Shared Protocol Duplication Policy: inline SYNC duplication is intentional — NEVER extract behind file reference.
- Source/Test Drift Check: when source behavior changes, decide from evidence whether tests follow or source is a bug.
- Understand Code First: read target + grep 3+ patterns (graph trace is optional advice) before writing or fixing.
- Design Patterns Quality: assess abstraction and responsibility using the project's evidenced architecture; do not impose a fixed object, layer, or framework convention.
- Complexity Prevention: look for evidence-backed change amplification and unclear ownership using the project's actual module boundaries.
- Severity Rubric: classify findings Critical/High/Medium/Low by consequence using
SYNC:severity-rubric; round 1 blocks on every open validated finding (LOW deferral), round 2 blocks only CRITICAL/HIGH/MEDIUM, and LOW is recorded/deferred. Failed binary gates always block.
- Parallel Sub-Agent Dispatch: Tag tasks PAR/SEQ, group PAR into disjoint-write-set waves, spawn each wave in ONE message, barrier before advancing.
IMPORTANT MUST ATTENTION apply a simplification ONLY when certain it preserves behavior — grep all usages + trace consumers (grep/read; an optional graph downstream trace may hint at more) and cite file:line BEFORE touching anything; if unsure → DO NOT apply. — why: an unverified "safe" rewrite silently breaks a downstream consumer.
IMPORTANT MUST ATTENTION NEVER simplify generated, migration, or vendor files — HARD-SKIP them in Phase 0. — why: regenerated output overwrites edits and migrations are one-time execution paths, not core logic.
IMPORTANT MUST ATTENTION run the Self-Recursive Loop (analyze → simplify → verify) until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred); do NOT spawn a fresh-context reviewer for this skill's own findings. — why: re-reviewing your own findings in fresh context burns tokens the convergence loop already owns.
- MANDATORY Evidence Gate — every finding/recommendation needs
file:line proof or a traced call chain; confidence >80% to act, 60-80% verify first, <60% DO NOT recommend. NEVER use "obviously"/"I think"/"should be" without proof.
- MANDATORY break work into small todo tasks via todo tracking BEFORE starting; keep exactly one
in_progress; mark completed immediately; add a final review task. On context loss, the current task list first — resume, never duplicate.
- MANDATORY READ
code-review-rules.md FIRST, then project-structure-reference.md — both under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides); search 3+ existing patterns and read the target code BEFORE modification. The code graph is optional advice for high-risk blast radius.
- MANDATORY evaluate pattern FIT before copying nearby code — verify same scope, lifetime, base class, constraints; closest example ≠ matching preconditions. — why: a copied pattern with mismatched preconditions compiles but is wrong.
- MANDATORY reason by the 5 Simplification Dimensions — readability, evidenced DRY/abstraction, responsibility according to documented architecture and actual ownership, complexity reduction, and configured persistence/query bounds when relevant (otherwise N/A with a reason); every technique answers ONE test: does this make the next change cheaper?
- MANDATORY IMPORTANT MUST ATTENTION compare repeated behavior before abstraction and assign responsibility from project docs and traced code; names/suffixes are clues only. After every extraction/move/rename, grep ENTIRE scope for dangling references — zero tolerance. — why: "primary file done" ≠ secondary files clean.
- MANDATORY IMPORTANT MUST ATTENTION preserve ALL invariants — NEVER weaken, delete, or trivialize a property/mutation test guarding a
[HARD] §4 rule or §5 invariant; a behavior change is a Dual-Feedback finding (feed spec AND tests, re-review) — report and stop, never ship silently. — why: green tests on a weakened bar are not a pass.
- MANDATORY IMPORTANT MUST ATTENTION verify ALL affected outputs and tests pass after EACH change (apply one refactoring type at a time) — one build green ≠ all green; when a caller runs the tests once, last (
SYNC:verify-last-order), compile/type-check each change and leave the test run to that caller's single verify. — why: multi-stack changes regress the stack you didn't check.
- MANDATORY IMPORTANT MUST ATTENTION Self-Review Gate — when this skill changed code, self-invoke
$code-quality-review scoped to ONLY the changed files (recursion-safe leaf skill; NEVER $workflow-review-changes, whose code-simplifier step would recurse, nor the heavier $changes-review); skip + log the
…(truncated)
1---2name: code-simplifier-43description: '[Code Quality] Use when a workflow step or the user asks for code simplification for clarity and maintainability without changing behavior.'4metadata:5 source: https://skillmd.com/skills/duc01226/code-simplifier-46---78> Codex compatibility note:9> - Invoke `$skill-name`: load the registered `.agents/skills/<name>/SKILL.md` and execute it with Codex tools; no separate `Skill` tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author `.claude/**`; mirrors are generated.10> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.11> - Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.12> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.13> - Preserve protocol order unless the user approves a deviation. Workflows use `$start-workflow`: gates stay fixed; other steps may flex with logged reasons and evidence.14<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->1516> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, `$start-workflow` → Workflow-step mode bounds this rule.17> **[BLOCKING]** Before each step or sub-skill call, update todo tracking: set `in_progress` when step starts, set `completed` when step ends.18> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.19> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.2021<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->2223## Quick Summary2425**Goal:** Lower the cost of the next change — cut coupling, hidden state, duplicated knowledge, unclear intent — by simplifying and refining code for clarity, consistency, and maintainability without altering any observable behavior. — why: every simplification serves future change cost, not aesthetics.2627**Summary:** (read-this-if-nothing-else digest — purpose + every main step)2829- **Purpose — skeptical-first MUTATOR, not a suggester:** grep all usages + trace consumers (grep/read; an optional graph downstream trace may hint at more) and cite `file:line` BEFORE touching anything; apply a simplification ONLY when certain it preserves behavior, never when unsure. — why: an unverified "safe" rewrite silently breaks a downstream consumer.30- **Main steps, run in order:** (1) **Phase 0 Detect** target + scope from project config/source; (2) **Identify Targets** — recent git changes or named files, HARD-SKIP generated/migration/vendor; (3) **Analyze** via the 5 Simplification Dimensions, marking inapplicable ones N/A with a reason; (4) **Apply** one refactoring type at a time (KISS/DRY/YAGNI, behavior-preserving); (5) **Verify** related tests after EACH change; (6) **Self-Recursive Loop** (analyze→simplify→verify) until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred) or a no-progress/unsafe/owner-decision stop hits — do NOT spawn a fresh-context reviewer for your own findings; (7) **Self-Review Gate**.31- **The 5 Simplification Dimensions (step 3):** readability · DRY/abstraction (compare real repetition; apply YAGNI) · responsibility based on the project's documented architecture and evidenced ownership · complexity reduction · persistence/query bounds on applicable changed paths only (otherwise N/A) — every technique answers ONE test: does this make the next change cheaper?32- **Self-Review Gate (step 7) — this skill owns review of its own output:** when it changed any file, self-invoke `$code-quality-review` scoped to ONLY those changed files (recursion-safe leaf — NEVER `$changes-review`); skip + log the reason when nothing changed. Only an explicit `--defer=review` from a caller that runs a FULL review of the settled state afterwards skips it (see `.claude/skills/workflow-review-changes/references/caller-mode.md`); no flag means the gate runs. — why: the simplifier rewrites code after the main review batch, so its output ships unreviewed without this gate.33- **`--report-only`:** read-only mode for a caller that owns every fix (e.g. a review skill's simplification dimension or a workflow review barrier) — steps 1–3 only, each finding with `file:line` + proposed change + behavior-preservation note, no edit of any file, no nested sub-agent, no user question, only the report written; see [Report-Only Mode](#report-only-mode---report-only).34- **Read FIRST:** `code-review-rules.md` (anti-patterns/checklists) then `project-structure-reference.md`, both under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) — before any modification.3536> **MANDATORY IMPORTANT MUST ATTENTION** Plan task to READ:37>38> - `code-review-rules.md` under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) — anti-patterns, review checklists **(READ FIRST)**39> - `project-structure-reference.md` — project patterns/structure40>41> If not found, search for: project documentation, coding standards, architecture docs.4243**Workflow:**44451. **Phase 0: Detect** — Classify target types present in the project (source, UI/client, tests, configuration, or other) and scope462. **Identify Targets** — Recent git changes or specified files (skip generated/migration/vendor)473. **Analyze** — Apply simplification dimensions (see below)484. **Apply** — One refactoring type at a time following KISS/DRY/YAGNI495. **Verify** — Run related tests, confirm no behavior changes; when a caller runs the tests once, last (`SYNC:verify-last-order`, e.g. a `--tests=defer` review fix loop), verify statically instead — re-read the diff against the covering tests and run none, the caller's single verify proves them506. **Self-Recursive Check** — Re-run this skill's simplification analysis until the current round's exit bar is clear: Round 1 requires zero validated findings at any severity, with no-edit LOW deferral allowed; every applied fix requires a fresh full review (`SYNC:review-policy`). From Round 2 onward only validated CRITICAL/HIGH/MEDIUM findings reopen the loop, while LOW findings are recorded as deferred and do not justify another cycle. Failed binary gates always block.517. **Self-Review Gate (MANDATORY when code changed)** — If this skill modified any files, self-invoke `$code-quality-review` scoped to ONLY those changed files; skip + log if nothing changed, or when the caller passed `--defer=review` (record `Self-review deferred to caller post-fix FULL review`)5253**Key Rules:**5455- **AI surface?** Only if the code holds a model call, prompt, agent, tool/MCP, retrieval or eval (see `node .claude/scripts/ai-signal-scan.cjs`): read `.claude/skills/shared/protocols/ai-engineering-gate.md`; never simplify away a timeout, retry bound, step or cost cap, output validation, approval gate or retrieval evidence check; otherwise skip this line.56- Preserve all existing functionality — no behavior changes57- Apply conventions supported by `docs/project-config.json`, its referenced project docs, and relevant existing code; treat an explicit N/A or absent stack as a signal to verify the target, not as a missing pattern to invent58- Easy to Change is the primary simplification goal for source files; DRY, SOLID, abstraction, and patterns are valid only when they lower future edit sites or cognitive load59- Tests pass after every change60- Apply simplification only when certain it preserves behavior — NEVER apply when unsure6162## Contents6364- [Quick Summary](#quick-summary)65- [Report-Only Mode (`--report-only`)](#report-only-mode---report-only)66- [Phase 0: Artifact Detection](#phase-0-artifact-detection)67- [First Principle — Easy to Change · Easy to Scale · Easy to Maintain](#first-principle--easy-to-change--easy-to-scale--easy-to-maintain)68- [Simplification Mindset](#simplification-mindset)69- [Simplification Dimensions](#simplification-dimensions)70- [Project Patterns](#project-patterns)71- [Graph Intelligence (optional advice)](#graph-intelligence-optional-advice)72- [Execution](#execution)73- [Constraints](#constraints)74- [Self-Recursive Verification (MANDATORY after simplifications)](#self-recursive-verification-mandatory-after-simplifications)75- [Self-Review Gate (MANDATORY when this skill changed code)](#self-review-gate-mandatory-when-this-skill-changed-code)76- [Next Steps](#next-steps)77- [AI Agent Integrity Gate (NON-NEGOTIABLE)](#ai-agent-integrity-gate-non-negotiable)78- [Self-Recursive Simplification Loop](#self-recursive-simplification-loop)79- [Prompt-Enhance Closing Anchors](#prompt-enhance-closing-anchors)80- [Closing Reminders](#closing-reminders)8182## Report-Only Mode (`--report-only`)8384> **Use when** a caller needs simplification opportunities as findings without edits — e.g. a review skill running its simplification dimension, a workflow parallel review barrier, or a review batch — and another step owns every fix. `--report-only` in `$ARGUMENTS` selects it; without the flag every step applies unchanged.85>86> **MANDATORY — when `--report-only` is passed, read `.claude/skills/workflow-review-changes/references/caller-mode.md` in full FIRST.** It holds the shared caller rules: a `--report-only` pass returns one report with no source edits, the caller fixes once and requests fresh passes, and a child never mutates source in parallel or runs a nested loop. The rules below are this skill's own.87>88> **Review lens in `workflow-review-changes`.** This mode can serve as the simplification lens inside the review barrier: report the findings, and the review's `fix --target=review` step applies the validated simplifications after findings validation.89>90> 1. **Run steps 1–3 only** (Phase 0 Detect → Identify Targets → Analyze). Apply, Verify, the Self-Recursive loop, and the Self-Review Gate do not run: edit NO file — source, test, config, or doc. The caller runs its own findings-validation gate and owns every fix and re-review. — why: a simplifier that edits inside a review barrier races the diff every sibling reviewer is reading.91> 2. **Every finding carries:** `file:line` · the simplification dimension · the proposed change (concrete before → after, or the exact edit described) · a behavior-preservation note (the usages and consumers traced — grep/read evidence, plus any graph hint — and why observable behavior stays unchanged) · severity per `SYNC:severity-rubric` · confidence. A proposal whose behavior preservation cannot be proven is reported as `behavior-change risk`, never as a safe simplification. — why: the fixer applies it later without this skill's trace, so the evidence must travel with the finding.92> 3. **No nested fan-out.** Skip the `spawn_agent(agent_type="code-simplifier", ...)` execution path; analyze sequentially in this context.93> 4. **Report file.** Write it to `tmp/reports/code-simplifier-{date}-{slug}.md`, appended per file.94>95> For this mode the declared step order ends at step 3; stopping there is the mode's contract, not a skipped step.9697## Phase 0: Artifact Detection9899**MUST ATTENTION** classify before simplifying — detection drives focus and optional escalation only:100101| Artifact Type | Detection | Key Focus |102| ------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |103| Source | Target paths and file types identified from project config or user scope | Preserve behavior; apply only responsibilities and conventions evidenced for the relevant code |104| UI/client (if any) | Affected UI paths identified from project config or source | Use configured UI, state, lifecycle, and styling conventions only when present; otherwise follow local evidence |105| Tests | Test paths and runner identified by project config or source | Preserve the assertions, async behavior, isolation, and runner conventions that apply to this project |106| Generated/migration/vendor | Generated markers, configured paths, or vendor/migration directories | **SKIP** generated, migration, and vendor code |107108File extensions and stack-specific names in prompts or examples are search clues, not requirements. Classify the actual target using the project's config, references, and source.109110Optional escalation by artifact:111112| Artifact | Escalate only when |113| -------------------- | ------------------------------------------------------- |114| Source code/diffs | Broad review is requested after simplifier loop is clean |115| Security-sensitive | Security-specific risk is present |116| Performance-critical | Performance behavior is part of the change |117| Plans, docs, specs | Artifact review is explicitly requested |118119## First Principle — Easy to Change · Easy to Scale · Easy to Maintain120121> The full gate is `SYNC:core-engineering-principles` (protocol guide below; a hook delivers its text); its closing digest ends this file.122123**Skill focus:** favor project-owned boundaries around external libraries (for example component/service input-output contracts) when they localize future library changes; reject pass-through wrappers that add ceremony without lowering change cost.124125---126127## Simplification Mindset128129**Skeptical-first:** Verify before simplifying. Every change needs proof preserving behavior.130131- NEVER assume code redundant — trace call paths and read implementations first132- Before removing/replacing: grep all usages confirming nothing depends on current form133- Before flagging convention violation: grep 3+ existing examples — codebase convention wins134- Every simplification requires `file:line` evidence of what was verified135- Apply simplification only when certain it preserves behavior; if unsure → DO NOT apply136137## Simplification Dimensions138139Dimension-based reasoning replaces fixed checklists. Each dimension has a `Think:` prompt forcing first-principles reasoning.140141### Dimension 1: Readability142143> **Think:** Would a new engineer understand this in 30 seconds? What forces multiple file traces?144145- Schema visibility: functions computing data structures need output-shape comment146- Non-obvious pipelines: A→B→C transformations need brief pipeline explanation147- Self-documenting signatures: params explain role; remove unused params148- Magic values: replace unexplained numbers/strings with named constants149- Naming clarity: names reveal intent without reading implementation150151### Dimension 2: DRY & Abstraction152153> **Think:** Is the same responsibility repeated, and would a shared abstraction reduce future change cost without hiding intentional differences?154155- Search by behavior and responsibility; names or type suffixes are clues for discovery, not proof that types share a base or contract156- Extract a shared function, module, or type only when repeated behavior and change reasons align and the abstraction reduces edit sites or cognitive load157- YAGNI gate: NEVER extract for hypothetical future use — 3+ similar occurrences prompt comparison, not automatic extraction158159### Dimension 3: Right Responsibility160161> **Think:** Which module or layer owns this invariant under the project's documented architecture and current call paths?162163- Read the project structure and relevant pattern references, then trace callers to identify the owner supported by evidence164- When those docs are silent, follow a consistent existing code pattern; if no owner is evidenced, keep the change local and report the uncertainty165- Place transformations at the boundary documented or demonstrated by this project; do not create an assumed layer, entity, or DTO convention166167### Dimension 4: Complexity Reduction168169> **Think:** What is cognitive load? Can nesting/conditionals flatten?170171- Inspect nesting and method size for obscured intent; use early returns or extraction when they lower cognitive load while preserving behavior. Line/depth counts are clues, never refactor mandates.172- Simplify complex conditions locally; choose a shared dispatch/pattern only when real variation and ownership justify its indirection.173174### Dimension 5: Data Access and Storage (when applicable)175176Apply this dimension only when project config/reference docs identify a persistence system or relevant target code proves it is used, and the changed path reads or writes that system. If no database/storage is configured or evidenced in source, or the changed code does not use its query/index model, mark this dimension `N/A — reason`; do not require paging or indexes for unrelated code.177178> **Think:** Can this particular access path exceed its intended bound, and what evidence shows the configured or code-evidenced store needs a different access path?1791801. **Result bounds:** For a changed list/search/report path over persistent data, check expected result size and the caller contract. When results can grow and the project supports it, use its documented paging/window/cursor convention; otherwise cite the evidence that bounds the result. Names such as `GetAll`, `ToList`, `Find`, or `Skip/Take` are search examples, not defects by themselves.1812. **Index fit:** Only for a database configured or evidenced in source and a changed query path that uses it (or a schema/index change supporting that query), inspect filters, ordering, joins, schema/index definitions, and query plans when available. Recommend an index only when evidence supports it and account for write/storage cost; do not demand indexes on every filter, foreign key, or sort field.1823. **Other storage models:** Follow the configured and code-evidenced access, query, and bound conventions for the storage in use. If persistent data is not in the changed path, record `N/A — reason`.183184## Project Patterns185186- Resolve affected paths through `docs/project-config.json` and its configured docs index; load only relevant backend/API, UI/client, test or other references, honoring custom paths and documented `N/A`.187- Missing/silent references: inspect at least three fitting local examples. If none exists, keep the change minimal and report the gap; never invent a framework convention.188- Names, extensions and examples do not establish applicability. Require config/reference + changed-code evidence for any layer, class, helper, state tool, styling method or storage API.189- Dimension 5 is `N/A — reason` unless config/source confirms a database and the changed path uses its query/index model. UI checks require an evidenced UI surface.190- Before paging/index recommendations, cite config/schema/source evidence and query/runtime behavior.191192## Graph Intelligence (optional advice)193194Optional: when grep and reading files alone may not reveal a high-risk blast radius (shared contract, many callers, cross-module/cross-service flow, public API), the code graph (`.code-graph/graph.db`) can add callers, dependents and impacted tests. Treat it as a hint, NOT proof: the graph can be stale or incomplete (it lags uncommitted edits and unindexed paths) — verify anything that matters by reading the files/grep. Skip it for low-risk or local changes.195196Before simplifying, trace what depends on the target (grep/read; optionally the graph):197198```199python .claude/scripts/code_graph trace <file> --direction downstream --json200```201202Verify simplified code preserves the interface for every traced consumer. When the changed contract crosses a module, process, or service boundary, trace all consumers configured or found in source; message-bus consumers are one example only when the project uses that boundary.203204Additional queries:205206- Optional hint for callers: `python .claude/scripts/code_graph query callers_of <function> --json`207- Check dependents: `python .claude/scripts/code_graph query importers_of <module> --json`208- Batch analysis: `python .claude/scripts/code_graph batch-query file1 file2 --json`209210## Execution211212```213spawn_agent(agent_type="code-simplifier", prompt="Review and simplify [target files]")214```215216**Example:**217218```typescript219// Before220function getData() {221 const result = fetchData();222 if (result !== null && result !== undefined) {223 return result;224 } else {225 return null;226 }227}228229// After230function getData() {231 return fetchData() ?? null;232}233```234235## Constraints236237- **Preserve functionality** — no behavior changes238- **Tests passing** — verify after every change239- **Follow patterns** — use the project's conventions, never invent240- **Doc staleness** — cross-ref changed files against feature docs, test specs, READMEs; flag updates needed241- **Preserve ALL invariants; never weaken a property/mutation test** — a refactor MUST keep every `[HARD]` §4 rule / §5 invariant intact and MUST NOT delete, relax, or trivialize any property test or mutation test that guards them. If a simplification changes observable behavior, that is NOT a silent change — it is a **Dual-Feedback finding** (feed the spec AND the tests, then re-review), report it and stop, never ship it. After simplifying, the package MUST still pass the SAME property/mutation bar it passed before — green tests on a weakened bar are not a pass.242243---244245## Self-Recursive Verification (MANDATORY after simplifications)246247After applying simplifications, follow the [Self-Recursive Simplification Loop](#self-recursive-simplification-loop) below. It owns round closure, deferred LOWs, no-progress/unsafe stops and the subsequent Self-Review Gate. For caller-owned verify-last execution, use the static-verification exception in Workflow Step 5.248249## Self-Review Gate (MANDATORY when this skill changed code)250251> **This skill is a code MUTATOR. It owns the review of its own output.** Once the self-recursive simplification loop above is clean, gate the result:252>253> 0. **Caller deferral.** `--defer=review` in `$ARGUMENTS` means the caller runs a FULL review of the settled whole target after this skill returns (see `.claude/skills/workflow-review-changes/references/caller-mode.md`). Skip steps 1–3, record `Self-review deferred to caller post-fix FULL review`, and return the exact list of files this skill changed so that review covers them. Without the flag — including a bare invocation by another skill — run the gate.254> 1. **Did this skill modify any files?** Determine the exact set of files this skill changed (its own edits — not the whole working tree).255> - **No files changed** → SKIP this gate and **log the skip reason** ("code-simplifier made no changes — no self-review needed"). Done.256> - **Files changed** → continue.257> 2. **Self-invoke `$code-quality-review` scoped to ONLY the changed files.** Pass the explicit changed-file set as the review target — not the full diff, not unrelated files.258> 3. **Integrate the `$code-quality-review` findings.** If it surfaces blocking issues caused by the simplification, fix them (behavior-preserving only) and re-run the self-recursive loop + this gate. If issues are out of simplification scope, report them up — do not silently drop.259>260> **Recursion safety:** `$code-quality-review` is a LEAF review skill — it does NOT invoke `$code-simplifier` back, so there is no cycle. Use `$code-quality-review` here, NEVER `$workflow-review-changes` (its sequence contains a `code-simplifier` step and would recurse) or `$changes-review` (a full-diff review heavier than this file-scoped gate needs).261>262> **Why this gate exists:** `$code-simplifier` rewrites code after the main review batch has already run. Without this gate, the simplifier's output would ship unreviewed. This gate moves that review responsibility into the mutator itself — so the `workflow-review-changes` workflow no longer needs a separate `$code-quality-review` step after `$code-simplifier`.263264Used standalone (outside a review workflow), this self-review gate is sufficient for the simplifier's own changes; you may still finish with `$changes-review` or the active workflow's review gate for broader, whole-changeset coverage.265266## Next Steps267268> **EXEMPT** when invoked by a parent skill or workflow step, when running as a sub-agent, or under `--report-only`: return the result to the caller; skip `ask user question tool`.269270**MANDATORY — NO EXCEPTIONS** after completing, use `ask user question tool`:271272- **"$workflow-review-changes (Recommended)"** — Review all changes before commit273- **"$code-quality-review"** — Full code review274- **"Skip, continue manually"** — user decides275276## AI Agent Integrity Gate (NON-NEGOTIABLE)277278> **Completion ≠ Correctness.** Before reporting work done, prove it:279>280> 1. **Grep every removed name.** Extraction/rename/delete → grep confirms 0 dangling refs across ALL file types.281> 2. **Ask WHY before changing.** Existing values intentional until proven otherwise. No "fix" without traced rationale.282> 3. **Verify ALL outputs.** One build passing ≠ all builds passing. Check every affected stack.283> 4. **Evaluate pattern fit.** Copying nearby code? Verify preconditions match — same scope, lifetime, base class, constraints.284> 5. **New artifact = wired artifact.** Created? Prove registered, imported, reachable by all consumers.285286> **[IMPORTANT]** Use todo tracking to break ALL work into small tasks BEFORE starting. Keep task depth proportional to the work.287288**Prerequisites:** **MUST ATTENTION READ** before executing:289290- `domain-entities-reference.md` under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) — domain entity catalog, relationships, cross-service sync (read when task involves business entities/models)291292> **External Memory:** Complex/lengthy work → write findings to `tmp/reports/`. Prevents context loss, serves as deliverable.293294> **Evidence Gate:** MANDATORY — every claim, finding, recommendation requires `file:line` proof or traced evidence (confidence >80% to act, <80% verify first).295296> **DRY and abstraction fit:** Compare repeated behavior and responsibility before proposing a shared abstraction. Recommend a function, module, or type only when evidence shows the instances share a reason to change and the abstraction reduces future edits; names or suffixes alone do not justify a base type. Verify any project-specific lint/analyzer rule in its config.297298## Self-Recursive Simplification Loop299300**Purpose:** Avoid spending tokens on a fresh-context review of this skill's own findings. The simplifier owns its own convergence loop; broader review workflows can still run after the simplifier reports clean.301302Loop:3033041. Analyze the current target/diff for simplification findings with `file:line` evidence.3052. Apply only behavior-preserving simplifications that satisfy the evidence gate.3063. Run targeted verification after each change set.3074. Re-read the updated diff and re-run this skill's simplification dimensions.3085. Repeat until this skill's current round bar is clear: round 1 has zero validated simplification findings; round 2 have zero validated CRITICAL/HIGH/MEDIUM findings, with LOWs recorded as deferred.309310Stop conditions:311312- The same simplification finding repeats for 3 passes with no progress.313- A simplification needs product/owner input or has behavior-change risk.314- Verification cannot run or cannot prove behavior preservation.315316Rules:317318- Do not spawn a fresh-context reviewer just because simplifications were applied.319- Do not re-review known findings in a fresh context before fixing them.320- Do not hand off until the self-recursive pass clears the current round bar; never silently discard deferred LOWs.321- After the self-recursive loop is clean, run the **Self-Review Gate** — if any files were changed, self-invoke `$code-quality-review` scoped to those files (recursion-safe leaf skill); skip + log if nothing changed or the caller passed `--defer=review`.322323<!-- PROTOCOL-GUIDES:START -->324325> **Protocol guides** — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.326327- `complexity-prevention` — Change-cost lens on complexity (Ousterhout); designing or reviewing code → .claude/skills/shared/protocols/complexity-prevention.md328- `core-engineering-principles` — Core quality gate: easy to change, easy to scale, easy to maintain, judged by future change cost; planning, implementing or reviewing any change → .claude/skills/shared/protocols/core-engineering-principles.md329- `design-patterns-quality` — Design quality: one owner per rule, fitted patterns, no speculative abstraction; designing or reviewing code structure → .claude/skills/shared/protocols/design-patterns-quality.md330- `review-decision-autonomy` — Choose supported review decisions and ask before extending the round budget; running any review or audit skill or mode → .claude/skills/shared/protocols/review-decision-autonomy.md331- `severity-rubric` — One consequence-based Critical, High, Medium, Low scale for every finding and gate; classifying a finding or deciding whether a review round passes → .claude/skills/shared/protocols/severity-rubric.md332- `shared-protocol-duplication-policy` — Protocol copies in carriers are intentional: edit the canonical source, then propagate; editing a shared protocol or its carriers → .claude/skills/shared/protocols/shared-protocol-duplication-policy.md333- `source-test-drift-check` — When source behavior changes, reconcile the affected tests from evidence; code, fix, test or review work changes behavior → .claude/skills/shared/protocols/source-test-drift-check.md334- `subagent-return-contract` — Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.md335- `ui-system-context` — Resolve the project's UI conventions before a UI change; changing a user-interface surface → .claude/skills/shared/protocols/ui-system-context.md336- `understand-code-first` — Read and trace the target and existing patterns before changing code; planning or editing code → .claude/skills/shared/protocols/understand-code-first.md337- `verify-last-order` — Build all phases and write tests, review statically, then verify once with a mutation check; planning or running any code-changing task → .claude/skills/shared/protocols/verify-last-order.md338339<!-- PROTOCOL-GUIDES:END -->340341<!-- SYNC:evidence-based-reasoning:reminder -->342343**IMPORTANT MUST ATTENTION** cite `file:line` evidence for every claim; never speculate. Confidence >80% to act, <60% = do NOT recommend; "not enough evidence" is valid output.344345<!-- /SYNC:evidence-based-reasoning:reminder -->346347<!-- SYNC:complexity-prevention:reminder -->348349**IMPORTANT MUST ATTENTION** assess change amplification, cognitive load, coupling, leaked detail and invariant ownership from project evidence. Extract only when a real owner or consumer lowers change cost; no universal layer order or numeric threshold.350351<!-- /SYNC:complexity-prevention:reminder -->352353<!-- SYNC:severity-rubric:reminder -->354355- **MANDATORY** Classify every finding Critical/High/Medium/Low by consequence using the affected asset, shipped impact, exposure, reversibility, evidence location, and confidence; Critical/High/MEDIUM remain actionable under the round bar, while LOW is recorded/deferred from round 2 onward.356- **MANDATORY** A finding names a reachable trigger path (caller, input, state or event that reaches the defect) and a consequence; an unreachable concern is an observation, and unsettled reachability is `NOT VERIFIABLE` only when the concern would be MEDIUM or higher (an observation otherwise) — never a speculative LOW.357- **MANDATORY** Keep binary gates separate from severity: a failed test, security must-fix, required artifact, or parity check blocks at every round and is never relabeled LOW.358- **MANDATORY** Score-based skills (sre 0-2, perf two-axis) map onto the same four tiers — no parallel severity vocabulary.359360<!-- /SYNC:severity-rubric:reminder -->361362363<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:START -->364365## Prompt-Enhance Closing Anchors366367**IMPORTANT MUST ATTENTION** follow declared step order for this skill; NEVER skip, reorder, or merge steps without explicit user approval; inside a workflow run, `$start-workflow` → Workflow-step mode bounds this368**IMPORTANT MUST ATTENTION** for every step/sub-skill call: set `in_progress` before execution, set `completed` after execution369**IMPORTANT MUST ATTENTION** every skipped step MUST include explicit reason; every completed step MUST include concise evidence370**IMPORTANT MUST ATTENTION** if Task tools unavailable, maintain an equivalent step-by-step plan tracker with synchronized statuses371372<!-- PROMPT-ENHANCE:STEP-TASK-CLOSING:END -->373374375<!-- SYNC:review-decision-autonomy:reminder -->376377**MUST ATTENTION** Decide supported review choices and recommendations, record the rationale, and finish without routine user questions. Keep round-limit extension, indispensable facts and actual action authority; preserve source coverage, validation, tests, read-only boundaries and budgets. Review decisions do not accept open risks or make a failed gate pass.378379<!-- /SYNC:review-decision-autonomy:reminder -->380381## Closing Reminders382383**IMPORTANT MUST ATTENTION Goal:** Lower the cost of the next change — cut coupling, hidden state, duplicated knowledge, unclear intent — by simplifying and refining code for clarity, consistency, and maintainability without altering any observable behavior. — why: every simplification serves future change cost, not aesthetics.384385**IMPORTANT MUST ATTENTION Main steps (run in declared order, never skip/merge):** (1) Phase 0 Detect target and scope from project config/source → (2) Identify Targets (skip generated/migration/vendor) → (3) Analyze the 5 Dimensions and mark inapplicable ones N/A with a reason → (4) Apply one refactoring type at a time → (5) Verify tests after EACH change → (6) Self-Recursive Loop until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred) → (7) Self-Review Gate (`$code-quality-review` on changed files; skipped only under `--defer=review`). — why: AI keeps forgetting the skill's own steps; surfacing them here is the recency anchor.386387**Protocols in force (concise digest of the SYNC/shared blocks this skill carries):**388389- **Subagent Return Contract:** sub-agents return only the summary shape; full detail to report file.390- **UI System Context:** read frontend-patterns, scss-styling-guide, design-system before touching UI files.391- **Shared Protocol Duplication Policy:** inline SYNC duplication is intentional — NEVER extract behind file reference.392- **Source/Test Drift Check:** when source behavior changes, decide from evidence whether tests follow or source is a bug.393- **Understand Code First:** read target + grep 3+ patterns (graph trace is optional advice) before writing or fixing.394- **Design Patterns Quality:** assess abstraction and responsibility using the project's evidenced architecture; do not impose a fixed object, layer, or framework convention.395- **Complexity Prevention:** look for evidence-backed change amplification and unclear ownership using the project's actual module boundaries.396- **Severity Rubric:** classify findings Critical/High/Medium/Low by consequence using `SYNC:severity-rubric`; round 1 blocks on every open validated finding (LOW deferral), round 2 blocks only CRITICAL/HIGH/MEDIUM, and LOW is recorded/deferred. Failed binary gates always block.397- **Parallel Sub-Agent Dispatch:** Tag tasks PAR/SEQ, group PAR into disjoint-write-set waves, spawn each wave in ONE message, barrier before advancing.398399**IMPORTANT MUST ATTENTION** apply a simplification ONLY when certain it preserves behavior — grep all usages + trace consumers (grep/read; an optional graph downstream trace may hint at more) and cite `file:line` BEFORE touching anything; if unsure → DO NOT apply. — why: an unverified "safe" rewrite silently breaks a downstream consumer.400**IMPORTANT MUST ATTENTION** NEVER simplify generated, migration, or vendor files — HARD-SKIP them in Phase 0. — why: regenerated output overwrites edits and migrations are one-time execution paths, not core logic.401**IMPORTANT MUST ATTENTION** run the Self-Recursive Loop (analyze → simplify → verify) until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred); do NOT spawn a fresh-context reviewer for this skill's own findings. — why: re-reviewing your own findings in fresh context burns tokens the convergence loop already owns.402403- **MANDATORY** Evidence Gate — every finding/recommendation needs `file:line` proof or a traced call chain; confidence >80% to act, 60-80% verify first, <60% DO NOT recommend. NEVER use "obviously"/"I think"/"should be" without proof.404- **MANDATORY** break work into small todo tasks via todo tracking BEFORE starting; keep exactly one `in_progress`; mark `completed` immediately; add a final review task. On context loss, the current task list first — resume, never duplicate.405- **MANDATORY** READ `code-review-rules.md` FIRST, then `project-structure-reference.md` — both under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides); search 3+ existing patterns and read the target code BEFORE modification. The code graph is optional advice for high-risk blast radius.406- **MANDATORY** evaluate pattern FIT before copying nearby code — verify same scope, lifetime, base class, constraints; closest example ≠ matching preconditions. — why: a copied pattern with mismatched preconditions compiles but is wrong.407- **MANDATORY** reason by the 5 Simplification Dimensions — readability, evidenced DRY/abstraction, responsibility according to documented architecture and actual ownership, complexity reduction, and configured persistence/query bounds when relevant (otherwise N/A with a reason); every technique answers ONE test: does this make the next change cheaper?408- **MANDATORY IMPORTANT MUST ATTENTION** compare repeated behavior before abstraction and assign responsibility from project docs and traced code; names/suffixes are clues only. After every extraction/move/rename, grep ENTIRE scope for dangling references — zero tolerance. — why: "primary file done" ≠ secondary files clean.409- **MANDATORY IMPORTANT MUST ATTENTION** preserve ALL invariants — NEVER weaken, delete, or trivialize a property/mutation test guarding a `[HARD]` §4 rule or §5 invariant; a behavior change is a Dual-Feedback finding (feed spec AND tests, re-review) — report and stop, never ship silently. — why: green tests on a weakened bar are not a pass.410- **MANDATORY IMPORTANT MUST ATTENTION** verify ALL affected outputs and tests pass after EACH change (apply one refactoring type at a time) — one build green ≠ all green; when a caller runs the tests once, last (`SYNC:verify-last-order`), compile/type-check each change and leave the test run to that caller's single verify. — why: multi-stack changes regress the stack you didn't check.411- **MANDATORY IMPORTANT MUST ATTENTION** Self-Review Gate — when this skill changed code, self-invoke `$code-quality-review` scoped to ONLY the changed files (recursion-safe leaf skill; NEVER `$workflow-review-changes`, whose `code-simplifier` step would recurse, nor the heavier `$changes-review`); skip + log the 412413…(truncated)