| 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:
- 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.
- You need to browse by theme. Open
laws/README.md for the full categorized index (Architecture, Decisions, Design, Operations, Planning, Quality, Scale, Security, Teams).
- 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.
