Structural Simplification

Structural Simplification

Core Directives

1. Complexity has four axes: D (diversity), K (coupling), P (depth), n (quantity). Score each independently; never collapse into a single number.
2. Compare before and after. Intuition is not a metric.
3. Conform when semantics match. Reusing an existing pattern shrinks D globally only when the semantics, lifecycle, and constraints actually fit.
4. Remove over mitigate, safely. Removing a part or special case beats handling it when functionality, migration, rollback, and external constraints permit removal.

Reporting Vocabulary

The skill may reason with axis symbols, but reports are for a coding agent that must choose an edit, test, lint rule, or rejection. Use the coder-facing field names below in every emit block, gate table, and cross-skill citation.

Naming guardrails. P is max-chain-depth, never "depth" alone — bare "depth" collides with the layer field in morphogenetic-architecture. Symbols appear in exactly three places: inside a formula, inside this table, and inside §§1–7 (the internal model). Anywhere else in narrative, use the coder-facing field name.

1. The Complexity Model

Domain-agnostic. Parts = any discrete unit; relationships = any connection (dependency, flow, sequence, authority). Multi-axis interactions usually cost more than any single-axis change alone; verify against the domain's actual constraints.

[!IMPORTANT] Cycles are property violations, not just high K. A cycle breaks the DAG assumption only when the chosen projection is required to be acyclic, such as imports, ownership, authority, or layer dependencies. See §5 for the topology framing that rules those cycles out; morphogenetic-architecture §2 defines the hard invariant and hands enforceable static constraints to architecture-as-code. If the domain intentionally contains cycles (feedback loops, state machines, workflows), define the acyclic projection or cycle semantics before scoring.

2. Domain Mapping

3. Heuristic Checks

Fast proxies — not substitutes for measurement.

4. Reduction Operations

D↓ — Reduce Diversity

[!WARNING] Unification guardrail — referencing-list uniformity. Merging vocabulary items (rights, routes, types, statuses, config keys) is safe only when every member is uniform with respect to every other list that references them — ban/allow lists, separation-of-duties pairs, fixed scopes, party or tenant restrictions, protocol mappings. A merged item cannot be half-banned or half-granted: one non-uniform member blocks the merge or must stay separate. Enumerate the referencing lists and check uniformity before claiming a D↓ or n↓ from Unification, Generalization, or Merging.

K↓ — Reduce Coupling

P↓ — Reduce Depth

[!WARNING] A facade hides chain depth; it does not reduce it. Verify actual P, not visible P.

n↓ — Reduce Quantity

Multi-axis — Reduce Simultaneously

5. Topology Constraint

Treat a dependency structure as a directed topology with explicit positions, interfaces, locality, and separately measured relationship fields. Bounded public surfaces and local neighbor sets cap K, directional static edges cap P, cohesive positions bound n, and consistent component forms cap D. Decompose along domain, abstraction-tier, or layer seams only when the proposed cut improves the measured vector.

For dependency projections that require acyclicity, reject cycles before scoring trade-offs. For runtime feedback, name the cycle semantics and measure the chosen acyclic projection separately.

For declared placement, observed fields, candidate boundary decisions, and enforcement handoffs, see morphogenetic-architecture.

6. Trade-off Matrix

Reducing one axis usually raises another. Examples lean software but the moves apply to any structure.

7. Asymmetric Trade-offs

Cases where net axis effect is positive despite local cost.

7a. Conformance (Pattern Alignment)

Accept local structural cost to eliminate a unique shape from D only when the standard pattern fits the same semantics, lifecycle, ownership, and external constraints. One snowflake among ten uniform parts can inflate D disproportionately, but a real domain distinction should be named and preserved.

7b. Scope Reduction (Deletion)

Remove or deprecate special functionality if its structural footprint exceeds its utility and the functionality-complexity-tradeoff verdict allows safe removal. Special cases are complexity multipliers: D↑ (unique patterns), K↑ (conditional paths), P↑ (extended chains), n↑ (supporting parts). The cost of a feature includes every special case it forces elsewhere, plus the migration and compatibility work needed to remove it safely.

7c. Atomicity Requirements

When an action coordinates multiple independent participants (services, actors, steps, partners), the atomicity decision has direct structural cost. Decide before implementation — see architecture-guidelines §5 Atomicity.

Anti-Pattern: designing multi-step operations without deciding atomicity first.

8. Decision Protocol

1. Model before-state and after-state. Record D, K, P, n for each (internal axes; see Reporting Vocabulary for the coder-facing field names).

2. Cycle check. If the modeled projection is required to be acyclic, a cycle in the after-state is a hard fault — fix before continuing. If the domain permits cycles, record the cycle semantics and score the chosen acyclic projection separately.

3. Answer the forcing questions in writing (one line each):

   • D: What unique pattern does this introduce that no sibling uses? (Name the 2nd concrete instance; absence = Rule-of-3 violation.)
   • K: Which previously-independent parts does this link?
   • P: How long is the longest dependency chain a typical change traverses? (>3 hops → max-chain-depth is itself the cost.)
   • n: If deleted, what would dependents do? (If "use the thing it wraps," it's a no-op facade.)
   • Counterfactual: Does §7a or §7b apply? What is the 12-month removal cost?

4. Check non-structural gates. Confirm the candidate still satisfies required behavior, security/privacy, compliance, observability, performance, migration, and rollback constraints. Structural improvement is not permission to break a required property.

5. Classify:

   Pattern	Action
   All axes improve or hold	Proceed if non-structural gates pass
   Mixed (some improve, some worsen)	Consult §6 trade-offs, apply §7, then check gates
   No axis improves	Reject or redesign unless required by an external gate

6. Emit a coder-facing decision record (see Reporting Vocabulary for the symbol mapping):

   Subject:              <structure / module / refactor under review>
   Decision:             Proceed | Redesign | Reject
                         (retrospective: KEEP | SIMPLIFY | DELETE)
   Component-kinds Δ:    <±n>   (evidence: novel pattern, 2nd concrete instance)
   Dependency-edges Δ:   <±n>   (evidence: what newly couples to what)
   Max-chain-depth Δ:    <±n>   (evidence: longest path before → after)
   Module-count Δ:       <±n>   (evidence: parts added / removed)
   Cycle:                Pass | Fail
   Non-structural gates: Pass | Fail | Not evaluated
   Trade-off:            <§6 row matched; §7 sub-section if asymmetric>
   Rationale:            <1–3 sentences tying the four deltas and forcing-Q answers → decision>
   Next action:          <edit, test, lint rule, measurement, or smaller alternative>
   Verification:         <command / graph check / review evidence, or Not run + reason>
   

[!IMPORTANT] If no axis improves, state: "Complexity Warning: Component-kinds Δ [X], Dependency-edges Δ [Y], Max-chain-depth Δ [Z], Module-count Δ [W]. A simpler alternative is [...]."

9. See also

• architecture-guidelines — first-principles discipline that informs Δ scoring (YAGNI, Rule of 3, DRY, SoC).
• morphogenetic-architecture — placement and topology rationale; static cycles remain forbidden while explicit runtime feedback is modeled separately.
• functionality-complexity-tradeoff — consumes D, K, P, n deltas in its cost ledger.
• defect-shift-left — earliest stage to catch each axis violation.
• continuous-improvement — when a recurring axis violation signals a missing rule.