Reduce System Complexity

Reduce System Complexity

Conserve behavior. Minimize mechanism.

Use this skill only after a concrete behavior path or subsystem has been selected and the intended result is net removal of mechanism. It owns the conservation ledger, whole-path mechanism accounting, first-principles minimum, and separate behavior and mechanism gates.

Keep it distinct from:

• improve-codebase-architecture, which discovers and ranks architecture investments;
• codebase-design, which designs a selected module's responsibility and complete caller-facing contract;
• structure-codebase, which owns physical placement, packages, imports, enforcement, and migrations;
• refactoring, which implements ordinary bounded behavior-preserving cleanup without a whole-path reduction claim;
• functional reducer functions, Redux reducers, and state-management choices.

Read references/ledger-template.md before producing a diagnosis or implementation report. Read references/source-notes.md when explaining provenance or comparing this adaptation with its upstream source.

Operating Contract

• Preserve the user's requested scope. Do not widen one path into a repository rewrite.
• Diagnosis is read-only. The report is the only default write; implementation needs explicit authority.
• Follow repository instructions, architecture decisions, glossaries, public contracts, and dirty-worktree constraints. Never destructively reset, checkout, or overwrite user or teammate changes.
• Treat the implementation, tests, traces, history, incidents, and operator knowledge as evidence. Do not inherit the current decomposition as the target, but do not ignore undocumented constraints discovered in it.
• Redact secrets, tokens, personal data, and production payloads from fixtures, traces, snapshots, and reports.
• Scale the ledgers to risk. A local flag removal does not need the ceremony of a distributed migration; a data, authorization, concurrency, compatibility, or external-effect change does.
• Call finite tests and observations preservation evidence, never proof of universal equivalence. State confidence and fidelity gaps.
• Default all provider, integration, migration, failover, rollback, publication, and operational checks to read-only or a disposable sandbox. Never write to a live external system without specific authority for that effect.

Workflow

1. Fix scope, mode, and conserved contract

State:

• the selected entry points, outcomes, callers, data, integrations, and operational path;
• diagnosis or authorized implementation mode;
• what “less mechanism” means for this scope;
• excluded behavior and boundaries;
• irreversible effects or published contracts that constrain the work.

Classify observed behavior before promising to conserve it:

Inventory outputs, effects, errors, ordering, persistence, integrations, authorization, security, privacy, reliability, resource budgets, compatibility, concurrency, retries, migrations, and recovery behavior. Record each in the behavior-and-guarantee ledger with its evidence and gaps.

Characterisation tests reveal what the code does; they do not decide what it ought to do. During diagnosis, record missing oracles without editing. If implementation and test-harness work are separately authorized, load characterisation-tests and finding-seams when current behavior lacks a usable oracle. Load testing for behavior-level oracle design. Record the eventual mutation scope, but defer the automated mutation-testing harness until the reduction slice is otherwise ready for its PR.

At that end-of-phase PR-readiness gate, mutation testing is not meaningful for every proven-unreachable path, configuration-only change, generated boundary, or operational mechanism. Mark it N/A with reachability, configuration, contract, integration, or operational evidence instead. Never invent structural mutants or fake RED to satisfy the workflow.

Implementation remains diagnosis while any material behavior the proposed slice can affect has an unresolved evidence gap.

2. Baseline the whole mechanism

Trace each conserved behavior from trigger to outcome and recovery. Inventory applicable mechanism dimensions with the same scope and counting method that will be used afterward:

• Control — decisions, conditions, ordering, error, retry, fallback, and recovery paths. Cyclomatic complexity may be one local signal, not a cross-system total.
• State and time — states, transitions, mutable owners, caches, queues, tasks, callbacks, locks, synchronization points, and lifecycle phases.
• Structure — modules, representations, layers, hops, internal and external dependencies, cycles, adapters, and translations.
• Variability and operations — flags, modes, configuration, extension points, deployables, jobs, migrations, monitors, runbooks, and failure handling.

Include tests and operational machinery when they impose ongoing ownership cost. Exclude generated artifacts unless their source, build, or runtime mechanism changes. Mark irrelevant dimensions N/A.

For mixed runtimes, include runtime entries and conversions across consumers and implementations in the before/after inventory, rather than counting only wrappers removed at the entry point. Read the Effect runtime reference when that path uses Effect.

Do not combine unlike counts into a synthetic score. A smaller function, directory, or diff is not a reduction when callers, operators, dependencies, or recovery paths inherit the removed burden.

3. Derive a minimum from constraints

Answer independently of the current shape:

1. Which outcomes and non-functional guarantees must exist?
2. Which domain decisions and external constraints are irreducible?
3. Which boundaries are fixed, and who must own state, time, failure, and recovery?
4. What is the shortest coherent path from trigger to observable outcome?

Sketch the minimum plausible mechanism and name the constraint that earns every remaining part. Seek leverage in this order:

1. Delete proven-obsolete paths, options, flags, configuration, fallbacks, and speculative machinery.
2. Unify duplicated policy, representation, state, and ownership.
3. Shrink decision and state spaces.
4. Remove pass-through layers, translation chains, temporal hops, and coordination.
5. Replace custom machinery with an established primitive only when total lifecycle and operational cost fall; use evaluate-existing-solutions for a consequential dependency or tool choice.

Reject proposals that merely rename, split, wrap, relocate, or conceal complexity. A deeper module may improve callers while retaining or increasing internal mechanism; that is a valid codebase-design outcome but not, by itself, a successful reduction.

4. Select a complete reduction

Rank candidates qualitatively:

1. Prefer removal of one complete mechanism over partial hiding.
2. Prefer stronger preservation evidence and fewer fidelity gaps.
3. Use smaller blast radius and easier recovery as tie-breakers.

For the selected candidate, record:

• the exact mechanism and conserved behaviors;
• objective before/target observations per applicable dimension;
• affected callers, data, integrations, operations, and public contracts;
• missing oracles and other proof obligations;
• rollout, observability, compatibility, data migration, and recovery needs;
• the terminal state in which old machinery is gone.
• for a multi-slice program, the plan/ledger identity, terminal slice, and class of each slice: reduction transition or terminal reduction.

Prefer a small reversible slice. When reversal is impossible or unsafe, define a guarded forward-recovery path before implementation. Expand/contract migrations may temporarily add a bridge, flag, dual write, or compatibility shim; give each one an owner, removal condition, and bounded lifetime. Record N/A when a transition introduces no temporary bridge. Do not claim reduction until the terminal state removes the superseded mechanism.

Diagnosis stops here and produces the report. If multiple delivery slices are needed, use planning after the complete reduction and gates are defined.