agentleFS
MohOneXMohOneX/claude-opus-skills/system-decomposition-synthesis/SKILL.md

system-decomposition-synthesis

Skill0 starsChanged 5 months agoMITView on GitHub

Decomposes complex multi-domain problems into well-bounded parts and synthesizes them into a unified model, exposing hidden dependencies and emergent behavior. Use when facing a large ambiguous system or problem spanning multiple domains, designing component boundaries, or when local solutions keep causing global problems.

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Make each part have one reason to change: if two responsibilities change for different reasons and at different rates, they belong in …

    line 13
  2. Distinctive:

    Unify the mental model: when domains interact (e.g., a performance fix that creates a consistency problem that creates a security gap), …

    line 20

≈ “Common” is an estimate: at least 1 in 5 of the 308,232 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

System Decomposition & Synthesis

The art is cutting a system where its joints actually are, then keeping the whole in view. Bad decomposition creates parts that are individually correct and collectively broken; the value is in the boundaries and the interactions, not the pieces.

Decompose along real seams

  1. Cut on low-coupling lines: split where information flow is thinnest, not where the org chart or the nouns suggest. The right boundary minimizes the interface (what crosses it) and maximizes cohesion (what stays together).
  2. Make each part have one reason to change: if two responsibilities change for different reasons and at different rates, they belong in different components. Coupling things with different change rates is the root of most rework.
  3. Define the contract at each boundary explicitly: what crosses, what's guaranteed, what's hidden. A boundary with a leaky or implicit contract is not a real boundary — it's two components pretending to be separate.

Synthesize — model the whole, not the sum

  • Emergent behavior: properties that exist only in the interaction (deadlock, feedback loops, cascading failure, contention). Decomposition hides these; you must explicitly re-examine the assembled system for behavior no single part exhibits.
  • Cross-cutting concerns (security, consistency, observability, performance) don't live in one component — they span all boundaries. Assigning them to "a part" guarantees gaps at the seams.
  • Unify the mental model: when domains interact (e.g., a performance fix that creates a consistency problem that creates a security gap), reason about them as one coupled system, not three reports stapled together.

Adversarial validation

  • Trace a real flow across boundaries: pick an end-to-end request/scenario and follow it through every part. Boundaries that looked clean often reveal chatty round-trips, shared hidden state, or circular dependencies.
  • Hidden dependency hunt: parts that "don't depend on each other" often share a database, a clock, a config, a cache, or an ordering assumption. Find the implicit couplings the diagram doesn't show.
  • The seam-failure test: what happens at the boundary under failure — partial results, version skew, one side down? Boundaries are where failures concentrate and where decomposition's promises break.
  • Conway check: does the decomposition fight the org/communication structure? Boundaries that cut across team lines generate constant friction and erode.
  • Local-optimum trap: does optimizing each part independently degrade the whole (e.g., each service caching aggressively creates global incoherence)?

Non-obvious risks

  • Over-decomposition multiplies interface and coordination cost until the integration is harder than the original problem (distributed-monolith failure).
  • The cleanest-looking decomposition on paper is often the one that ignores the cross-cutting concern that later dominates.
  • Synthesis is the step teams skip: they decompose, solve parts, and ship — then discover the emergent behavior in production.

Output structure

Deliver: the decomposition with each boundary's explicit contract (what crosses, what's hidden) and its single reason-to-change, the cross-cutting concerns handled across seams rather than assigned to one part, the end-to-end flow traced through the parts, the hidden dependencies and seam-failure behaviors surfaced, and the unified model of the emergent whole with its risks.

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.