Decision Engine

Symptom

The codebase works but feels messy. You are tempted to reorganize before adding the next feature. Or the opposite: something is broken but you keep layering fixes on top instead of fixing the structure.

Common wrong instinct

Most people refactor when they feel uncomfortable, not when the system requires it. They rename files, reorganize folders, and extract abstractions before shipping anything. The result is a cleaner codebase that still has zero users.

Operator rule

Ship until invariants fail. If the system works, if the build passes, and if the defined rules hold, ship the feature. Refactor only when behavior contradicts your invariants or when the architecture prevents a required change.

Three question filter

1. 1Does the current structure prevent me from making this specific change?
2. 2Has an invariant been violated (not just a style preference)?
3. 3Will this refactor produce a measurable improvement I can prove with a build or test?

Example

You want to reorganize the components folder before adding a new page. The components folder is messy but functional. The new page does not require any changes to existing components. Ship the page first. Reorganize later, if ever.

Symptom

You are thinking about database migrations, caching layers, CDN configuration, or load balancers. Your app has fewer than 1,000 users. You have read articles about how to handle millions of requests and you are worried about being unprepared.

Common wrong instinct

Most people add infrastructure before they have traffic. They set up Redis, add a queue system, configure auto-scaling, and build monitoring dashboards for an app that gets 50 requests per day. The infrastructure becomes the project instead of the product.

Operator rule

Do not scale complexity before scale pressure appears. Every layer you add before you need it is a layer you maintain, debug, and pay for. Simplify until the system breaks under real load, then add exactly the layer that fixes that specific bottleneck.

Three question filter

1. 1Do I have evidence (logs, metrics, user reports) that this system is failing under current load?
2. 2Can I name the specific bottleneck this change fixes?
3. 3Am I adding this because of real pressure or because I read about it?

Example

Your app stores user state in Clerk metadata. You are considering migrating to Postgres because 'that is what real apps use.' Your app has 200 users. Clerk metadata works. Keep it. When you hit 10,000 users and read latency becomes measurable, migrate then.

Symptom

Something is not working as expected. You are about to open a debugger, add console logs, or ask Claude to 'fix the bug.' But you have not checked whether the behavior violates a defined rule or is simply unexpected.

Common wrong instinct

Most people treat every unexpected behavior as a bug. They patch the symptom without understanding the cause. The fix works today but introduces a new failure mode next week because the underlying rule was never examined.

Operator rule

If behavior contradicts a defined invariant, it is an invariant failure, not a bug. Check your invariants first. If the behavior violates one, the fix is to restore the invariant. If no invariant covers this behavior, the fix might be to add one.

Three question filter

1. 1Which specific invariant does this behavior violate? Can I name it?
2. 2If no invariant covers this, should I add one before fixing the code?
3. 3Am I fixing the symptom or the rule violation?

Example

A page that should be static is showing as dynamic in the build output. Before debugging the rendering logic, check the invariant: 'Content pages must not call auth() or fetch().' If someone added an auth() call to the page, the fix is removing that call, not restructuring the rendering pipeline.

Symptom

You are about to send a task to an AI model. You are not sure whether to use a fast, inexpensive model (GPT-4o Mini, Claude Haiku, Gemini Flash) or a slower, more capable one (GPT-4o, Claude Opus, Gemini Pro).

Common wrong instinct

Most people default to the strongest model for everything. They send copy edits, simple renames, and formatting tasks to Opus or GPT-4o. The cost adds up and the quality difference for simple tasks is negligible.

Operator rule

Use cheap models for iteration. Use strong models for architecture and debugging. If the task is bounded, has a clear hotspot, and requires no structural reasoning, a cheap model handles it. If the task requires understanding multiple files, diagnosing root causes, or making architectural decisions, use a strong model.

Three question filter

1. 1Does this task require reasoning about the system as a whole, or just editing one file?
2. 2Is the expected output a small, predictable diff, or does it require judgment?
3. 3Could I verify the output in under a minute, or does verification require careful review?

Example

Rewriting three FAQ answers: use a cheap model. The task is bounded, the output is text, and verification is reading the diff. Diagnosing why the build fails on Vercel but passes locally: use a strong model. The task requires cross-referencing env vars, dependency trees, and build logs.

Symptom

You have multiple changes to make. You are wondering if you can send them to separate Claude instances at the same time to move faster.

Common wrong instinct

Most people parallelize too early. They send three tasks to three agents without checking whether the tasks touch overlapping files. Two agents edit the same component. Both produce valid diffs individually. The merge creates a conflict or a subtle break that neither agent anticipated.

Operator rule

Parallelize only when hotspots are isolated and proof discipline exists. Each agent must have its own exclusive file list. No two agents may touch the same file. Every agent must produce a handoff packet with git proof. If you cannot guarantee file isolation, run tasks sequentially.

Three question filter

1. 1Do the file lists for each task have zero overlap?
2. 2Does each task have its own verification step that can run independently?
3. 3Am I prepared to review three handoff packets before merging anything?

Example

Agent A edits app/pricing/page.tsx. Agent B edits app/faq/page.tsx. Agent C edits app/contact/page.tsx. No overlap. Each runs npm run build independently. Each produces a handoff packet. This is safe to parallelize. But if Agent A and Agent B both need to edit Nav.tsx, run them sequentially.