/simplify-implementation

name: simplify-implementation
description: AI DevKit · Analyze and simplify existing implementations to reduce complexity, improve maintainability, and enhance scalability. Use when users ask to simplify code, reduce complexity, refactor for readability, clean up implementations, improve maintainability, reduce technical debt, or make code easier to understand.

Simplify Implementation Assistant

Reduce complexity with an analysis-first approach before changing code.

Hard Rules

• Do not modify code until the user approves a simplification plan.
• Readability over brevity. Some duplication beats the wrong abstraction.
• Prefer reusing an existing function over introducing a new one — but only if it fits cleanly. Do not force-fit a near-match.
• Before improving code, ask whether the function, abstraction, dependency, or custom logic needs to exist at all.
• Prefer platform and standard-library features over custom code or dependencies. Use already-installed dependencies when they cleanly solve the problem; do not add a dependency for logic that is only a few clear lines.
• For breaking changes: modify in place only when all callers are in-repo and updated in the same change. For public/external APIs, add a new function and deprecate the old one (parallel change).
• Delete or inline before adding: remove dead code, one-caller wrappers, redundant guards, stale tests, and unused configuration first.

Workflow

1. Gather Context

• Confirm targets, pain points, and constraints (compatibility, API stability, deadlines).
• Search for past simplification decisions or known constraints: `npx ai-devkit@latest memory search --query "<target area>" --tags "simplify"`

2. Analyze Complexity

• Identify sources (nesting, duplication, coupling, over-engineering, magic values).
• Run an existence check: can this code be deleted, delegated to the standard library, handled by a native platform feature, enforced by the database, or covered by an existing dependency?
• Apply the existence check to tests and scaffolding: remove stale, duplicate, implementation-detail-only, unused, or no-longer-relevant tests, assertions, and fixtures without unique behavioral coverage.
• Apply the reader-load test: can a new reader answer where key values come from and what can change them quickly? Count needless layers and hidden mutable state.
• Assess impact (LOC, dependencies, cognitive load, boundary leakage, scalability blockers).

3. Apply Readability Principles

• Apply the [readability guide](references/readability-guide.md) and its "Reading Test".
• Prefer domain-shaped structures over scattered conditionals when they remove branches, duplicated rules, or invalid states. Do not add an abstraction that only moves code around.

4. Propose Simplifications For each issue, apply a pattern:

• **Extract**: Long functions → smaller, focused functions.
• **Consolidate**: Duplicate code → shared utilities.
• **Flatten**: Deep nesting → early returns, guard clauses.
• **Decouple**: Tight coupling → dependency injection, interfaces.
• **Remove**: Dead code, unused features, excessive abstractions.
• **Replace**: Custom logic → standard-library, native platform, database, or already-installed dependency features.
• **Defer**: Premature optimization → measure-first approach.
• **Redesign**: Repeated implementation friction, patched branches, or synchronized flags → revisit the model before another local cleanup.

5. Prioritize and Plan

• Rank by impact/risk. Present plan with before/after snippets. Request approval.

Red Flags and Rationalizations

| Rationalization | Why It's Wrong | Do Instead | |---|---|---| | "While I'm here, let me refactor this too" | Scope creep breaks things | Only simplify what was requested | | "This abstraction will help later" | Predicted reuse rarely materializes | Remove it unless used twice today | | "Shorter is simpler" | Brevity can hide complexity | Optimize for readability, not line count | | "I'll add a v2 instead of updating callers" | Accumulates dead code and forks the API | Modify in place when callers are in-repo; parallel-change only for external/public APIs | | "Existing fn is close enough — I'll bend it to fit" | Wrong abstraction is costlier than duplication | Reuse only on clean fit; otherwise keep the small duplicate |

Validation

• Preserve meaningful regression, public-contract, and interaction coverage. Update stale tests to intentional behavior; never delete tests merely to make failures pass.
• Verify no regressions, add tests for new helpers, update docs if interfaces changed.

Output Template

• Target and Context
• Complexity Analysis
• Simplification Proposals (prioritized)
• Recommended Order and Plan
• Scalability Recommendations
• Validation Checklist