complexity-budget-audit
Audit an architecture proposal for machinery the problem has not earned — count moving parts against actual problem size, detect premature abstraction, and identify what could be cut without loss.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- complexity-budget-audit
- description
- Audit an architecture proposal for machinery the problem has not earned — count moving parts against actual problem size, detect premature abstraction, and identify what could be cut without loss.
03 SKILL.md 正文
Complexity Budget Audit
Purpose
Every architecture spends a budget: parts to build, parts to operate, parts to reason about during an incident, parts to onboard a new engineer into. This skill makes that spend explicit and holds it against the size of the problem being solved, so that over-engineering becomes a countable claim rather than a matter of taste.
Run this as the first pass on any proposal. It is cheap, it is domain-independent, and most objections either surface here or do not exist.
When to use
- On every architecture proposal, before any other analysis.
- When a design introduces a new service, layer, boundary, queue, cache, or config surface.
- When a proposal justifies structure with future requirements rather than present ones.
- When two proposals solve the same problem and you need a basis for comparison other than aesthetics.
Step 1 — Establish problem size
Before counting anything the proposal adds, write down what the problem actually is. Be specific and use numbers where they exist.
| Dimension | Question | Record |
|---|---|---|
| Users | How many concurrent, how many total? | |
| Data | How many records, documents, or bytes — today and in twelve months? | |
| Rate | Requests, events, or operations per second at peak? | |
| Behaviors | How many genuinely distinct things must the system do? | |
| Change rate | How often does the requirement set actually shift? | |
| Team | How many people build this, how many operate it? |
If these are unknown, that is itself a finding: a design sized for unknown requirements is sized for imagination. Record the unknowns and note that the proposal is unfalsifiable until they are filled in.
Step 2 — Count the moving parts
Enumerate everything the proposal introduces. Do not summarize — list.
- Runtime parts: processes, services, workers, daemons, background jobs, scheduled tasks.
- Data parts: stores, caches, indices, queues, replicas, migration paths.
- Code parts: layers, interfaces, plugin boundaries, strategy points, adapters, generic type parameters that exist for extensibility.
- Operational parts: deploy targets, config surfaces, secrets, feature flags, environment-specific branches, monitoring integrations.
- Cognitive parts: concepts a new engineer must learn before they can safely change anything.
Produce a total. The absolute number means little on its own; its relationship to Step 1 is the finding.
Step 3 — The machinery ratio
Hold the parts count against the problem size.
The question is not "is this a lot of parts" but does the parts count grow faster than the problem does. Signals that it does:
- Parts scale with anticipated future behaviors rather than current ones.
- Parts exist to make swapping a component easy when no swap is planned.
- Parts exist because a reference architecture from a much larger system included them.
- Parts exist to preserve symmetry — "we did it that way for X, so we do it for Y" — where Y has different requirements.
- The proposal's diagram has more boxes than the system has distinct behaviors.
For each part that fails the ratio, state what you would cut and what the design concretely loses by cutting it. "Loses nothing" and "loses a hypothetical future capability" are both valid answers and both are damning.
Step 4 — Premature abstraction tests
Apply each test to every interface, plugin point, strategy layer, factory, and generic boundary in the proposal.
The Second Implementation Rule
An abstraction is earned by two concrete implementations that exist or are committed. One implementation plus a hypothesis is a prediction, not engineering.
For each abstraction, ask: what is the second implementation, does it exist, and has anyone committed to building it with a date? If the answer is "we might want to swap this later," the abstraction is unearned. Note that removing it is cheap now and adding it later is also cheap — the asymmetry runs against keeping it.
The Configuration Test
Every config knob is a branch in the system's behavior space and a question a future operator must answer. For each knob the proposal adds, ask: who sets this, how do they know what to set it to, and what happens at the default? Knobs that will only ever hold their default are complexity with no corresponding flexibility.
The Indirection Test
Trace the path from an incoming request to the code that does the actual work. Count the hops that exist purely to preserve a boundary rather than to perform a transformation. Each such hop is a place a 3am debugger loses the thread.
The Naming Test
If a layer, service, or module cannot be given a name that describes what it does rather than where it sits — Manager, Handler, Service, Coordinator, Provider — it may not have a coherent responsibility. Weak naming is a symptom of a boundary drawn for structural symmetry rather than for a real seam in the problem.
Step 5 — The subtraction pass
For the proposal as a whole, construct the simplest version that solves the stated problem. Not a rival architecture — a stripped version of the same one.
Then state precisely what breaks when you use the stripped version. Three outcomes:
- Nothing breaks. The proposal is over-built. Report the delta.
- Something specific breaks at a specific threshold. The machinery is earned, provided the threshold is within the planning horizon. Record the threshold; it belongs in the decision record.
- Something might break but you cannot say what or when. The machinery is not yet earned. Report it as an unjustified part and let the proposer supply the mechanism.
Output
Produce, in this order:
- Problem size — the Step 1 table, with unknowns flagged.
- Parts ledger — the enumerated count from Step 2.
- Ratio verdict — over-built, correctly sized, or under-built, with the parts that drove the call.
- Unearned abstractions — each one, with its missing second implementation.
- Subtraction result — the stripped version and precisely what breaks.
- What is right — parts that are clearly earned. Name them so they survive review untouched.
Failure modes of this skill
- Counting as criticism. A high parts count on a genuinely large problem is fine. The ratio is the finding, never the raw number.
- Unfamiliarity read as complexity. A pattern you have not used before is not automatically unearned. Apply the tests, not your instincts.
- Cutting load-bearing structure. Some abstractions look unearned because their second implementation is a compliance requirement, a platform constraint, or a migration already underway. Ask before cutting.
- Auditing into paralysis. If every part passes the tests, say so and move on. A clean audit is a real result.
04 同仓库更多 Skills
twenty-year-land-plan
Apply the Bren discipline of evaluating every land and development decision on a twenty-year horizon, with a comprehensive plan for how the land, the community, and the surrounding public infrastructure evolve together. Deals optimized for a five-year exit are structurally different from deals that compound across generations; insist on knowing which kind you are making. Use when evaluating land, entitlements, master-planned development, or phasing decisions, and when separating five-year exit deals from generational holds.
thematic-gut-check
Apply the Gray discipline of identifying the structural theme behind every real estate deal, testing where that theme sits in its capital-flow lifecycle, and insisting that deals without a named theme — or deals late in a crowded theme — clear a higher bar. A mediocre deal in a strong theme usually beats a clever deal in a weak one. Use when naming the structural thesis behind a deal, judging whether that theme is early or crowded, and setting the bar the deal must clear.
supply-pipeline-gut-check
Apply the Zell discipline of grounding every real estate thesis in the local supply pipeline. Demand counts over adjectives — units under construction, units permitted, units proposed — and convert them into a forward absorption schedule. A deal that ignores the pipeline is a bet on a market you have not actually studied. Use when validating a market thesis, forecasting absorption and rent growth, or counting units under construction, permitted, and proposed.
ruin-scenario-mapping
Apply the Taleb discipline of identifying, for every real estate deal, the specific chain of events that produces ruin — permanent, unrecoverable capital loss — and verifying that no single such chain has non-trivial probability. Deals with any plausible ruin path must be restructured or abandoned. Use when sizing leverage, testing refinancing, covenant, and liquidity risk, or checking whether any single failure chain can permanently wipe out the position.
revenue-cost-architecture
Design a venture's revenue streams, pricing logic, cost structure, and unit economics so the business model has a coherent theory of value capture, not just value creation. Use after the value proposition and customer segment are set and before financial projections, when choosing a pricing model, calculating contribution margin or CAC payback, or checking whether the unit economics hold at scale.
replacement-cost-stress-test
Apply the Buffett discipline of pricing every real estate asset against the cost to rebuild it from scratch. The ratio of purchase price to replacement cost sets a ceiling on long-run downside: below replacement cost, new supply cannot profitably undercut you; at or above it, you are buying a liability disguised as an asset. Use when setting a purchase price, judging downside protection, or testing how exposed an asset is to newly built competing supply.