galls-law
Skill6 starsChanged 34 days agoMITView on GitHub
Apply Gall's Law when someone proposes building a complex system from scratch, planning a big-bang rewrite, designing a greenfield platform, or debating whether to "just rebuild it the right way." Trigger on phrases like "let's rewrite this properly", "we need to start fresh", "the architecture is too complex to fix", "let's build the perfect system", or any situation where someone wants to leap directly to a sophisticated, full-featured solution. Gall's Law is a powerful antidote to over-engineering and big-bang thinking.
In this repository79 other files it gives its agents.
- adr-phase-coverageSkill
- aposd-red-flag-reviewSkill
- apple-on-device-aiSkill
- artifact-gatesSkill
- asc-app-create-uiSkill
- asc-build-lifecycleSkill
- asc-cli-usageSkill
- asc-crash-triageSkill
- asc-id-resolverSkill
- asc-localize-metadataSkill
- asc-metadata-syncSkill
- asc-notarizationSkill
- asc-ppp-pricingSkill
- asc-release-flowSkill
- asc-revenuecat-catalog-syncSkill
- asc-shots-pipelineSkill
- asc-signing-setupSkill
- asc-submission-healthSkill
- asc-subscription-localizationSkill
- asc-testflight-orchestrationSkill
- asc-wall-submitSkill
- asc-workflowSkill
- asc-xcode-buildSkill
- choose-boring-technologySkill
- ci-preflightSkill
- conways-lawSkill
- cost-routingSkill
- cost-tier-routingSkill
- cunninghams-lawSkill
- ddd-strategic-auditSkill
- ddd-tactical-reviewSkill
- debug-test-captureSkill
- developing-ios-appsSkill
- doerrs-lawSkill
- fitts-lawSkill
- fix-regression-guardSkill
- goodharts-lawSkill
- greenspuns-tenth-ruleSkill
- gsd-core-hooksSkill
- hofstadters-lawSkill
- hyrums-lawSkill
- ios-accessibilitySkill
- ios-simulator-boot-healthSkill
- kerckhoffs-principleSkill
- kernighans-lawSkill
- knuths-optimization-principleSkill
- lady-lovelaces-objectionSkill
- leaky-abstractionsSkill
- linuss-lawSkill
- mobile-ios-designSkill
- money-boundary-judgmentSkill
- moores-lawSkill
- no-deferSkill
- norvigs-lawSkill
- parkinsons-lawSkill
- peter-principleSkill
- postels-lawSkill
- post-fix-traceSkill
- qa-test-architectSkill
- rubber-duckSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
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
- Distinctive: line 40
Ask: can we achieve our goals by evolving the existing system incrementally?
- Distinctive: line 41
If rewrite is truly necessary: do it alongside the old system.
- Distinctive: line 56
If we're doing a rewrite, are we planning to run old and new in parallel?
≈ “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.
Files
Gall's Law
"A complex system that works has evolved from a simple system that worked. A complex system built from scratch won't work." — John Gall, 1975
The core idea
You cannot design a working complex system directly. Complex systems that actually work all share the same history: they started as simple systems that worked, and grew from there. Every attempt to build the final, complete, sophisticated system from the start will fail — or produce something that doesn't actually work in production.
This isn't a counsel of despair. It's a guide to how to succeed: start simple, ship, learn, and evolve.
Why complex systems fail when built from scratch
- Unknown unknowns: You don't know all the requirements until you've operated a simpler version.
- Emergent complexity: Real-world usage surfaces edge cases, failure modes, and interaction effects that no design can anticipate in advance.
- Integration risk: Each new component multiplies integration complexity. Building many components at once means many things to go wrong before you have any working baseline.
- Feedback starvation: Complex systems take longer to build, so you go longer without the real-world feedback that shapes good design.
The rewrite trap
This law is most important when teams want to do a "big rewrite." The existing system feels painful, messy, and unmaintainable. The natural impulse is: throw it away and build the right thing.
But the existing system, however ugly, encodes years of learned behavior — edge cases handled, failure modes understood, user expectations embedded. Throwing it away means throwing away that knowledge and rebuilding it from scratch while also building new features.
The result: the rewrite takes 3-5x longer than expected, the new system reproduces all the old bugs plus new ones, and the organization is worse off than if they had incrementally improved the original.
How to apply it
For new systems:
- Identify the simplest version that provides real value and can be used in production.
- Ship that. Get feedback. Learn.
- Grow the system based on what you learn from real usage.
For rewrites:
- Ask: can we achieve our goals by evolving the existing system incrementally?
- If rewrite is truly necessary: do it alongside the old system. Run them in parallel. Migrate piece by piece. Never cut over all at once.
- Preserve existing behavior — even the weird bits — until you've understood why they exist.
For platform/API design:
- Release a minimal API that covers the core use case.
- Observe how people actually use it.
- Expand from there, adding complexity only where real demand exists.
The strangler fig pattern
In software, the Strangler Fig Pattern (from Martin Fowler) operationalizes Gall's Law for rewrites: incrementally replace pieces of the old system with the new system, routing traffic progressively until the old system is "strangled" and can be removed. No big bang. Always a working system.
Key questions to surface
- Is there a simpler version of this that we could ship and learn from first?
- If we're doing a rewrite, are we planning to run old and new in parallel?
- What assumptions are baked into this design that we haven't yet validated with real users?
- What's the smallest complete thing we could build that gives us real feedback?
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
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.

