reduce-system-complexity

Reduce mechanism in a selected system while conserving observable behavior and guarantees.

Updated May 18, 2024
One-click install
npx skills add https://github.com/joshhornby/dotfiles --skill reduce-system-complexity-joshhornby
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: reduce-system-complexity
Source: https://github.com/joshhornby/dotfiles/tree/main/.claude/skills/reduce-system-complexity
Command: npx skills add https://github.com/joshhornby/dotfiles --skill reduce-system-complexity-joshhornby

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Software systems accumulate branches, states, flags, layers, and operational machinery that outlive their purpose, and naive cleanup often just relocates complexity to callers or operators. This Skill provides a disciplined workflow to remove mechanism from a selected behavior path while proving that observable behavior and non-functional guarantees are conserved. ## Core Features & Use Cases - Conservation Ledger: Classifies documented contracts, relied-upon behavior, intended behavior, bugs, and obsolete internals, then tracks preservation evidence and fidelity gaps for each. - Whole-Mechanism Accounting: Baselines control flow, state and time, structure, and operational variability across the full path, then derives a minimum mechanism from real constraints rather than the current shape. - Separate Behavior and Mechanism Gates: Distinguishes reduction transitions from terminal reductions, blocking any net-reduction claim until superseded machinery and temporary migration bridges are actually removed. - Use Case: A service has three retry layers, two feature flags, and a pass-through adapter chain around one API call. Use this Skill to diagnose which mechanism is obsolete, plan a safe expand/contract removal, and produce an evidence-backed report showing like-for-like before/after deltas. ## Quick Start Ask the assistant to use the reduce-system-complexity skill to diagnose the retry and flag machinery in the payment service and propose a behavior-preserving reduction.

Frequently Asked Questions about reduce-system-complexity

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I reduce complexity in a codebase without breaking behavior?

Select one concrete behavior path, baseline its mechanism across control, state, structure, and operations, then derive a minimum from real constraints. Apply small reversible slices with passing behavior oracles, and only claim reduction after both behavior and mechanism gates pass.

What is the difference between refactoring and system complexity reduction?

Refactoring performs bounded behavior-preserving cleanup without a whole-path reduction claim. Complexity reduction targets net removal of mechanism across an entire path, requiring evidence that burden was not relocated to callers, operators, or recovery paths.

When should I not use a complexity reduction workflow?

Avoid it for routine cleanup, architecture investment discovery, module contract design, physical tree restructuring, new behavior, functionality cuts, or speculative rewrites. It also does not apply to Redux or functional reducer functions despite the similar name.

Can a reduction temporarily add mechanism like feature flags or dual writes?

Yes, expand/contract migrations may add a temporary bridge, flag, or compatibility shim, but each needs an owner, removal condition, and bounded lifetime. No net-reduction claim is allowed until the terminal slice removes the superseded mechanism and expired bridges.

What evidence proves complexity was actually removed rather than moved?

Recount the same mechanism dimensions over the same scope and method before and after, map every new part to what it replaces, and inspect callers, adapters, operations, and recovery for exported burden. Finite tests count as preservation evidence, never proof of universal equivalence.