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.

Internal symbol	Coder-facing field used in reports
ΔD (diversity)	Component-kinds Δ — distinct component/interface/pattern types added or removed
ΔK (coupling)	Dependency-edges Δ — imports, calls, package edges, or runtime links added or removed
ΔP (depth)	Max-chain-depth Δ — longest import/call/build chain before vs after
Δn (quantity)	Module-count Δ — files, modules, jobs, services, or instances added or removed

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

Axis	Symbol	What it counts	Measurement recipe
Diversity	D	Distinct patterns, shapes, concepts	Count distinct patterns / vocabulary items in the structure
Coupling	K	Relationship count and density	Count edges, then compute density (edges / (n × (n−1)) for directed graphs where n > 1) after defining edge kind and direction
Depth	P	Longest chain from source to sink	Longest path from any origin to any terminus in the DAG
Quantity	n	Total number of parts	Direct count of parts (use §2 to identify parts in your domain)

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

Domain	Parts (nodes)	Relationships (edges)
Code	Components, modules, functions	Dependencies, calls, imports
Project organization	Repos, packages, workspaces, build targets	Package dependencies, version constraints, build-time references, ownership
Runtime / deployment	Services, processes, containers, instances, threads	RPC/HTTP calls, message flows, network paths, replication, lifecycle order
Data model	Entities, fields, types	References, joins, constraints
Workflow	Steps, stages, decisions	Transitions, triggers, sequencing
UI / spatial	Screens, regions, elements	Navigation, data flow, visual links
Organization (people)	Roles, teams, systems	Authority, communication, data exchange
Temporal	Events, states, phases	Causal or sequential ordering

---

3. Heuristic Checks

Fast proxies — not substitutes for measurement.

Check	Signal	Axis
Symmetry	Structure more uniform after	D↓
Vocabulary	Describable with fewer concepts	D↓
Boundary	Fewer relationships crossing boundaries	K↓
Cycle broken	Dependency cycle eliminated	K↓ + §1 fault
Chain	Fewer hops source-to-sink	P↓
Count	Fewer parts	n↓
Ripple	Typical change in this area touches many parts	K
Consistency points	Each public unit (route, right, config key) drags N hand-maintained artifacts — handler, guard, contract entry, registry row, tests; removing the unit deletes them all	n, K

---

4. Reduction Operations

D↓ — Reduce Diversity

Operation	Mechanism
Unification	Merge distinct things that serve the same role
Normalization	Reduce variants to a single canonical form
Generalization	Replace N specific cases with one general case
Abstraction	Hide variation behind a common interface
Symmetrization	Impose mirror structure so parts become interchangeable
Deduplication	Eliminate redundant copies
Patternization	Apply a recurring structure — differences become instances, not exceptions
Cohesion	Group what changes together; the unit expresses one concept

[!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

Operation	Mechanism
Encapsulation	Hide internals so others cannot form dependencies on them
Indirection	Insert a mediator — two parts no longer reference each other directly
Inversion	Flip a dependency (depend on abstraction, not concretion)
Stratification	Impose directed acyclic ordering (layering)
Temporal decoupling	Replace synchronous direct binding with asynchronous mediation

P↓ — Reduce Depth

Operation	Mechanism
Flattening	Merge adjacent layers with no independent reason to exist
Inlining	Pull deep content up to the level that uses it
Direct binding	Replace A→B→C with A→C where B adds no value (raises K — verify product)

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

n↓ — Reduce Quantity

Operation	Mechanism
Elimination	Remove a part entirely — absolute edge count can drop with every deleted incident edge; recompute both edge count and density
Merging	Collapse two parts into one (may raise internal K — verify product)

Multi-axis — Reduce Simultaneously

Operation	Mechanism
Decomposition	Split along natural seams → K↓, D↓, P↓ in local subgraphs
Factoring	Extract common part → D↓ (dedup) + K↓ (N deps collapse to 1)
Separation of concerns	One responsibility per unit → D↓ internal + K↓ external

---

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.

Restructuring	D	K	P	n	Verdict
Add abstraction tier — ≥3 concrete instances	↑	↓	↑	↑	Candidate proceed (§7a Conformance); verify semantics match
Add abstraction tier — <3 instances or speculative	↑	↑	↑	↑	Candidate reject — Rule of 3; verify no external constraint
Add facade — over a 4-step chain	↑	—	hides P	↑	Keep only if K↓ measurable; never claim P↓ (§4 warning)
Flatten — intermediate part has no independent role	—	↑	↓	↓	Candidate proceed; verify internal K and invariants bounded
Extract common part — ≥3 dependents	↓	↓	—	↑	Candidate proceed; verify lifecycle and ownership match
Bypass a part — bypassed has no independent role	—	↑	↓	↓	Candidate proceed; verify no boundary or policy is bypassed
Introduce mediator between 2 parts	↑	↑	↑	↑	Candidate reject unless it enforces a boundary or decouples time
Merge two cohesive parts	↓	within ↑	↓	↓	Candidate proceed; verify internal K stays bounded
Split overloaded part along an SoC seam	↓	↓	↑	↑	Candidate proceed; verify caller paths remain understandable

---

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.

Decision	Structural effect	Action
Atomicity required	K↑ P↑	Accept coupling; use fail-fast / compensation
Eventual consistency	K↓ P↓	Document acceptable partial-failure states

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.