engineering-codex

name

engineering-codex

description

Surface the right classical law, pattern, or heuristic at the right moment during code review, architecture decisions, estimation debates, debugging, technical-debt conversations, team and org observations, operations and reliability work, security design, and any "should we do X" discussion. TRIGGER when the user (a) names a classical law (Conway's, Brooks's, Hyrum's, Postel's, Gall's, Tesler's, CAP, Murphy's, Demeter, SOLID, DRY, KISS, YAGNI, Pareto, Dunning-Kruger, Goodhart's, Parkinson's, Hofstadter's, Chesterton's Fence, Worse-Is-Better, Rule of Three, Information Hiding, Hoare's Billion-Dollar Mistake, Twelve-Factor App, Four Golden Signals, Error Budgets, SLO, Chaos Engineering, Blameless Postmortem, Principle of Least Privilege, Defense in Depth, etc.), (b) asks for a second opinion, what could go wrong, tradeoffs, or a sanity check, (c) is estimating or planning, (d) is debating a refactor, rewrite, abstraction, or new framework, (e) is discussing team structure, hiring, or org design, (f) is dealing with flaky tests, tech debt, or production incidents, (g) is designing authn/authz/access control or debating security posture, or (h) is setting reliability targets or building cloud-native services. SKIP when the user is in pure execution mode on a well-scoped task and no law clearly applies. Do not force a citation.

Engineering Codex

This skill gives you access to the laws, patterns, heuristics, and playbooks stored in this repo. Laws are the most developed bucket. Patterns, heuristics, and playbooks are growing.

How to use it

One law, not a lecture. When a law genuinely applies, cite it by name in-line with a one-sentence summary and the file path. At most two laws per response unless the user is explicitly asking for a broader survey. Never dump a list of loosely-relevant laws.

Format when citing:

Hyrum's Law: with enough users, every observable behavior becomes a dependency. Worth reading before you change that response format. See laws/architecture/hyrums-law.md.

Finding the right law. You have three lookup paths, in order of cost:

1. You already know the law (Conway's, Brooks's, CAP, DRY, etc.). Just read laws/<category>/<slug>.md directly. Slugs match the common name: conways-law, brooks-law, cap-theorem, dry-principle, yagni, kiss-principle, law-of-demeter, hyrums-law, etc.
2. You need to browse by theme. Open laws/README.md for the full categorized index (Architecture, Decisions, Design, Operations, Planning, Quality, Scale, Security, Teams).
3. You need to search by concept. Grep the laws/ tree for keywords. Example: grep -ril "estimation" laws/.

Don't make up laws. If you're not sure which law applies, read before you cite. A wrong attribution is worse than no citation.

When to go deep. If the user asks "tell me about X" for a specific law, read the full file (the statement, what it says, why it happens, where it shows up, what to do with it, when it misleads, further reading) and answer from it. Include one further-reading link if it's load-bearing.

Patterns, heuristics, playbooks. These live at the repo top level (patterns/, heuristics/, playbooks/). The lookup approach is the same: read the category README.md, then the specific file. Cite with the same one-line summary plus file path. Do not invent entries that are not there.

Categories and what they're for

• Architecture (laws/architecture/): shaping systems, designing APIs, or debating distributed-system tradeoffs. CAP, Hyrum's, Gall's, Tesler's, Leaky Abstractions, Second-System, Fallacies of Distributed Computing, Unintended Consequences, Zawinski's.
• Decisions (laws/decisions/): judgment calls, weighing evidence, acting under uncertainty. Chesterton's Fence, Dunning-Kruger, Hanlon's Razor, Occam's Razor, Sunk Cost, Map vs Territory, Confirmation Bias, Amara's Law, Lindy, First Principles, Inversion, Pareto, Cunningham's, Worse-Is-Better.
• Design (laws/design/): code review and module design. DRY, KISS, YAGNI, SOLID, Demeter, Least Astonishment, Rule of Three, Information Hiding, Hoare's Billion-Dollar Mistake.
• Operations (laws/operations/): running systems in production. Twelve-Factor App, Four Golden Signals, Error Budgets and SLOs, Chaos Engineering, Blameless Postmortem.
• Planning (laws/planning/): estimation and target-setting. Premature Optimization, Parkinson's, Ninety-Ninety, Hofstadter's, Goodhart's, Gilb's.
• Quality (laws/quality/): tests, bugs, debt, and long-lived codebases. Boy Scout Rule, Murphy's, Postel's, Broken Windows, Technical Debt, Linus's, Kernighan's, Testing Pyramid, Pesticide Paradox, Lehman's Laws, Sturgeon's.
• Scale (laws/scale/): parallelism, perf ceilings, and network effects. Amdahl's, Gustafson's, Metcalfe's.
• Security (laws/security/): securing systems by design. Principle of Least Privilege, Defense in Depth.
• Teams (laws/teams/): org design, hiring, conflict, or blame-the-process moments. Conway's, Brooks's, Dunbar, Ringelmann, Price's, Putt's, Peter Principle, Bus Factor, Dilbert Principle.

Common trigger → law pairings

Moment	Laws to consider first
"How long will this take?"	Hofstadter's, Ninety-Ninety, Parkinson's
"Should we rewrite?"	Second-System Effect, Gall's, Lindy, Sunk Cost, Worse-Is-Better
"Let's add a metric / OKR"	Goodhart's, Gilb's, Error Budgets
Adding people to a late project	Brooks's, Ringelmann, Dunbar
Changing a public API	Hyrum's, Postel's, Law of Unintended Consequences
Debating an abstraction	Leaky Abstractions, Tesler's, YAGNI, KISS, Rule of Three, Information Hiding
Removing old code you don't understand	Chesterton's Fence, Lindy
Org chart reshuffle	Conway's, Dunbar, Bus Factor
"Fix this one bug" in old code	Broken Windows, Boy Scout Rule, Lehman's
Flaky tests / low coverage	Testing Pyramid, Pesticide Paradox, Linus's
Prioritizing work	Pareto, Amdahl's (for perf), Inversion
"This feels over-engineered"	YAGNI, KISS, Premature Optimization, Second-System, Rule of Three
Production incident postmortem	Murphy's, Hanlon's Razor, Unintended Consequences, Blameless Postmortem
Building a new cloud service	Twelve-Factor App, Four Golden Signals, Fallacies of Distributed Computing
Setting reliability targets	Error Budgets and SLOs, Four Golden Signals, Goodhart's
Deciding whether to inject failure	Chaos Engineering, Murphy's, Fallacies of Distributed Computing
Granting access to a system	Principle of Least Privilege, Defense in Depth
Designing authn / authz	Defense in Depth, Principle of Least Privilege, Least Astonishment
Choosing a language for a greenfield project	Hoare's Billion-Dollar Mistake, Worse-Is-Better, Lindy

Attribution

Every law entry cites the original coiner (Conway 1968, Brooks 1975, Wright ~2011, Martin, Knuth, Liskov, and so on) in its frontmatter and body. When citing a law in depth, credit the person who coined it, not the curator of any particular list. Short direct quotes from the original author are acceptable and should be attributed to them.