code-simplify

What this skill does

# Code Simplify

## Objective

Simplify code while preserving behavior, public contracts, and side effects. Favor explicit code and local clarity over clever or compressed constructs.

## Arguments

- `--no-verify`: Skip verification because a parent orchestrator will verify the final result separately.
- `--no-report`: Skip the full user-facing report. Keep only concise working notes needed by the caller.
- Default: verify touched behavior and present the full report.

## Scope Resolution

1. Verify repository context: `git rev-parse --git-dir`. If this fails, stop and tell the user to run from a git repository.
2. If user provides file paths/patterns, a commit/range, or a `Resolved scope` fenced block with one repo-relative path per line, scope is exactly those targets.
3. Otherwise, scope is **only** session-modified files. Do not include other uncommitted changes.
4. If there are no session-modified files, fall back to all uncommitted tracked + untracked files:
   - tracked: `git diff --name-only --diff-filter=ACMR`
   - untracked: `git ls-files --others --exclude-standard`
   - combine both lists and de-duplicate.
5. Exclude generated/low-signal files unless requested: lockfiles, minified bundles, build outputs, vendored code.
6. If scope still resolves to zero files, report and stop.

## Operating Rules

- Preserve runtime behavior exactly. Keep inputs, outputs, side effects, and error behavior stable.
- Prefer project conventions over personal preferences. Infer conventions from existing code, linters, formatters, and tests.
- Limit scope to user-requested files or recently modified code unless explicitly asked to broaden.
- Make small, reversible edits. Avoid broad rewrites when targeted simplifications solve the problem.
- Call out uncertainty immediately when behavior may change.

## Workflow

### 1) Determine Scope

- Resolve target files using the "Scope Resolution" section above.

### 2) Build a Behavior Baseline

- Read surrounding context, not only changed lines.
- Identify invariants that must not change:
  - function signatures and exported APIs
  - state transitions and side effects
  - persistence/network behavior
  - user-facing messages and error semantics where externally relied on
- Note available verification commands (lint, tests, typecheck).

### 3) Apply Simplification Passes (in this order)

1. Control flow:
   - Flatten deep nesting with guard clauses and early returns.
   - Replace nested ternaries with clearer conditionals.
2. Naming and intent:
   - Rename ambiguous identifiers when local context supports safe renaming.
   - Separate mixed concerns into small helpers with intent-revealing names.
3. Duplication:
   - Remove obvious duplication.
   - Abstract only when at least two real call sites benefit and the abstraction reduces cognitive load.
4. Data shaping:
   - Break dense transform chains into named intermediate steps when readability improves.
   - Keep hot-path performance characteristics stable unless improvement is explicit and measured.
5. Type and contract clarity:
   - Add or tighten type annotations when they improve readability and safety without forcing broad churn.
   - Preserve external interfaces unless asked to change them.

### 4) Enforce Safety Constraints

- Do not convert sync APIs to async (or reverse) unless explicitly requested.
- Do not alter error propagation strategy unless behavior remains equivalent and verified.
- Do not remove logging, telemetry, guards, or retries that encode operational intent.
- Do not collapse domain-specific steps into generic helpers that hide intent.

### 5) Verify

Skip this step when `--no-verify` is set. Otherwise:

- Run the narrowest useful checks first:
  - formatter/lint on touched files
  - targeted tests related to touched modules
  - typecheck when relevant
- If fast targeted checks pass, run broader checks only when risk warrants it.
- If checks cannot run, state what was skipped and why.

### 6) Report

Skip the full report when `--no-report` is set. In that mode, keep only terse working notes covering touched scope, key simplifications, and residual risks for a parent orchestrator.

Otherwise provide:

1. Scope touched (files/functions)
2. Key simplifications with concise rationale
3. Verification commands run and outcomes
4. Residual risks or assumptions

## Simplification Heuristics

- Prefer explicit local variables over nested inline expressions when it reduces cognitive load.
- Prefer one clear branch per condition over compact but ambiguous condition trees.
- Keep function length manageable, but do not split purely for line count.
- Keep comments that explain intent, invariants, or non-obvious constraints.
- Remove comments that restate obvious code behavior.
- Optimize for the next maintainer's comprehension time, not minimum character count.

## Anti-Patterns

- Do not perform speculative architecture rewrites.
- Do not introduce framework-wide patterns while simplifying a small local change.
- Do not replace understandable duplication with opaque utility layers.
- Do not bundle unrelated cleanups into one patch.

## Stop Conditions

- Stop and ask for direction when:
  - simplification requires changing public API/contracts
  - behavior parity cannot be confidently verified
  - the code appears intentionally complex due to domain constraints
  - the requested scope implies a larger redesign rather than simplification

## Output Contract

When `--no-report` is not set, present simplification results like this:

1. Show the exact files and regions changed.
2. Explain each meaningful change in one sentence focused on readability/maintainability gain.
3. Confirm behavior-preservation assumptions explicitly.
4. Summarize verification performed (or clearly state omissions).