agentleFS
l-gevityl-gevity/l-gevity-skills/.agents/skills/structural-simplification/SKILL.md

structural-simplification

Skill88 starsChanged 3 days agoMITView on GitHub

A domain-agnostic complexity model and decision protocol. Complexity is treated as a 4-axis vector — D (diversity), K (coupling), P (depth), n (quantity) — and any proposed restructuring is judged by its per-axis effect rather than by intuition. Applies to code, project organization, runtime topology, data models, workflows, UI layouts, organizational structures, and temporal processes. TRIGGER when: evaluating a refactoring, designing a restructuring, or deciding whether a proposed change makes a system simpler or more complex. SKIP for: trivial renames, content edits, dependency bumps, isolated bug fixes that touch no structure. For subsystem-level design discipline see `architecture-guidelines`; for placement and evidence-weighted dependency-topology constraints see `morphogenetic-architecture`.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Treat a dependency structure as a directed topology with explicit positions, interfaces, locality, and separately measured relationship …

    line 122
  2. Very specific:

    Remove or deprecate special functionality if its structural footprint exceeds its utility and the functionality-complexity-tradeoff verdict …

    line 172
  3. Very specific:

    When an action coordinates multiple independent participants (services, actors, steps, partners), the atomicity decision has direct …

    line 181
  4. Distinctive:

    Model: before-state and after-state.

    line 198
  5. Distinctive:

    Cycle check: If the modeled projection is required to be acyclic, a cycle in the after-state is a hard fault — fix before continuing.

    line 200
  6. Distinctive:

    n: If deleted, what would dependents do?

    line 210

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 subsystem 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 symbolCoder-facing field used in reports
ΔD (diversity)Subsystem-kinds Δ — distinct subsystem/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)Subsystem-count Δ — files, subsystems, 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

AxisSymbolWhat it countsMeasurement recipe
DiversityDDistinct patterns, shapes, conceptsCount distinct patterns / vocabulary items in the structure
CouplingKRelationship count and densityCount edges, then compute density (edges / (n × (n−1)) for directed graphs where n > 1) after defining edge kind and direction
DepthPLongest chain from source to sinkLongest path from any origin to any terminus in the DAG
QuantitynTotal number of subsystemsDirect count of subsystems (use §2 to identify them in your domain)

Domain-agnostic. Subsystem = any discrete node of the structure under review — §2 names it per domain (a function, a service, a screen, a role, a step); 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

DomainSubsystems (nodes)Relationships (edges)
CodeSubsystems, functionsDependencies, calls, imports
Project organizationRepos, packages, workspaces, build targetsPackage dependencies, version constraints, build-time references, ownership
Runtime / deploymentServices, processes, containers, instances, threadsRPC/HTTP calls, message flows, network paths, replication, lifecycle order
Data modelEntities, fields, typesReferences, joins, constraints
WorkflowSteps, stages, decisionsTransitions, triggers, sequencing
UI / spatialScreens, regions, elementsNavigation, data flow, visual links
Organization (people)Roles, teams, systemsAuthority, communication, data exchange
TemporalEvents, states, phasesCausal or sequential ordering

3. Heuristic Checks

Fast proxies — not substitutes for measurement.

CheckSignalAxis
SymmetryStructure more uniform afterD↓
VocabularyDescribable with fewer conceptsD↓
BoundaryFewer relationships crossing boundariesK↓
Cycle brokenDependency cycle eliminatedK↓ + §1 fault
ChainFewer hops source-to-sinkP↓
CountFewer subsystemsn↓
RippleTypical change in this area touches many subsystemsK
Consistency pointsEach public element (route, right, config key) drags N hand-maintained artifacts — handler, guard, contract entry, registry row, tests; removing the element deletes them alln, K

4. Reduction Operations

Each axis has its own operation family — D↓ reduce diversity, K↓ reduce coupling, P↓ reduce depth, n↓ reduce quantity — plus multi-axis moves, each with guardrails on what it may claim. Read references/reduction-operations.md when proposing a simpler alternative, a SIMPLIFY, or a redesign, or when §6 cites a §4 warning; a measurement of a given candidate's four deltas does not need it.

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 subsystem forms cap D. Decompose along domain, abstraction-tier, or layer seams only when the proposed cut improves the measured vector. Decomposition splits one subsystem into several; aspect extraction pulls one aspect out of several subsystems. They are different cuts; judge both by the 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.

RestructuringDKPnVerdict
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 subsystem has no independent role—↑↓↓Candidate proceed; verify internal K and invariants bounded
Extract common subsystem — ≥3 dependents↓↓—↑Candidate proceed; verify lifecycle and ownership match
Bypass a subsystem — the bypassed one has no independent role—↑↓↓Candidate proceed; verify no boundary or policy is bypassed
Introduce mediator between 2 subsystems↑↑↑↑Candidate reject unless it enforces a boundary or decouples time
Merge two cohesive subsystems↓within ↑↓↓Candidate proceed; verify internal K stays bounded
Split overloaded subsystem 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 subsystems 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 subsystems). 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.

DecisionStructural effectAction
Atomicity requiredK↑ P↑Accept coupling; use fail-fast / compensation
Eventual consistencyK↓ 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 subsystems 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:

    PatternAction
    All axes improve or holdProceed if non-structural gates pass
    Mixed (some improve, some worsen)Consult §6 trade-offs, apply §7, then check gates
    No axis improvesReject or redesign unless required by an external gate
  6. Emit a coder-facing decision record (see Reporting Vocabulary for the symbol mapping):

    Subject:              <structure / subsystem / refactor under review>
    Decision:             Proceed | Redesign | Reject
                          (retrospective: KEEP | SIMPLIFY | DELETE)
    Subsystem-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)
    Subsystem-count Δ:    <±n>   (evidence: subsystems 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: Subsystem-kinds Δ [X], Dependency-edges Δ [Y], Max-chain-depth Δ [Z], Subsystem-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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.