Skip to content

Coding-agent skill

Overengineering Preflight

What can we delete, defer, or prove with one basic complete path first?

Use when: A plan is growing steps, infrastructure, abstractions, or deployment machinery faster than evidence warrants them.

Overengineering Preflight

Reduce the plan to the smallest sequence of complete, usable results. Do not confuse architectural motion with delivered value.

Use this as a focused corrective when a plan is growing abstractions, infrastructure, steps, or waves faster than evidence warrants them. It complements the broader Experience and Systems reviews; it is not a required third ritual for ordinary work.

Ground the review

  1. Read the proposal and its phases completely.
  2. Name the person or operator, the problem, and the result they need.
  3. Inspect current code, working surfaces, operational paths, and maintained documentation when available.
  4. Separate verified requirements from assumptions, preferences, future possibilities, and speculative scale.
  5. State what already works and can be reused before proposing machinery.

Do not redesign from prose alone when current reality is available.

Define the smallest useful result

Write one sentence:

> <person or operator> can <finish a useful job> through <real entry point> in <deliberately supported scenario>.

Choose the narrowest honest scenario that proves value. It may be local, manual, single-instance, limited to one data shape, or support only one well-chosen path. Narrow is acceptable. Inaccessible, misleading, or dependent on an unbuilt later wave is not.

Include the surface where the result is actually consumed: interface, API, command, integration, or operator workflow.

Separate milestones from sub-steps

Schemas, handlers, components, test harnesses, deployment plumbing, and behavior-free seams may be necessary. They are enabling work unless someone can use them to finish and verify a real job.

A phase may contain internal sub-steps. Its milestone must close the loop for its intended actor. Research and prototypes are learning work unless the result they deliver is the decision or evidence itself.

Apply the usable-wave gate

Every delivery wave needs:

  • Actor — who receives the result;
  • Result — what they can finish;
  • Entry point — how they reach it;
  • Complete path — the minimum interface, behavior, state, and effect;
  • Supported scenario — the deliberately narrow case;
  • Truthful limits — what remains unsupported or manual;
  • Visible failure — how they know it failed and what they can do;
  • Proof — an end-to-end check at the real entry point.

Reject a wave if a later wave is required before anyone can obtain its stated result. Compilation, unit tests, backend tests, or a merged change may support proof; they are not proof of use by themselves.

Find the thinnest real path

Trace:

  1. entry point;
  2. required authority;
  3. behavior or mutation;
  4. necessary state or external effect;
  5. visible result;
  6. proportionate failure and recovery.

Keep the reliability, security, integrity, and operational controls needed to make this scenario honest. Small does not mean partial or unsafe.

Prefer a walking slice built from existing primitives. Expand breadth, automation, resilience, and scale only when the working slice exposes a specific limitation.

Make every mechanism earn its place

Inventory each new abstraction, service, protocol, datastore, queue, cache, framework, deployment topology, generalized extension point, model call, and coordination mechanism. Ask:

  1. Which current result requires it?
  2. What proves the simpler option is insufficient?
  3. What is the cheapest predecessor that completes the path?
  4. What measurable event would justify this mechanism later?
  5. What migration, maintenance, failure, or security burden does it add?

Defer or delete machinery justified by hypothetical scale, possible future reuse, aesthetic purity, or a variant that does not exist.

Watch especially for:

  • blue-green deployment or orchestration before one repeatable deployment works;
  • horizontal scaling before measuring a single instance;
  • asynchronous pipelines where a direct bounded path is enough;
  • multiple sources of truth introduced for convenience;
  • a generalized platform built for one concrete case;
  • new infrastructure that an existing primitive can absorb;
  • automation of a workflow that has not been proven manually;
  • exhaustive compatibility before one supported scenario;
  • frontend shells without behavior;
  • backend capability with no reachable surface;
  • configuration that merely hands unresolved design decisions to users.

Do not require a generalized abstraction before concrete duplication reveals a stable seam.

Reslice by usable result

  • First wave: the smallest honest end-to-end result. Manual, local, single-instance, or narrow operation is allowed when it is truthful and safe.
  • Later waves: each improves a named limitation—setup, breadth, safety, recovery, multi-user behavior, deployment, performance, or scale—while remaining usable.
  • Sub-steps: necessary internal work listed beneath the result it serves.

Merge waves whose separate results are not useful. Split waves that contain multiple independently useful results. Do not force a fixed wave count.

If a later wave replaces an earlier mechanism, state the migration, deletion, and why the temporary path is worth its cost.

Try to disprove the plan

Ask:

  • Can the intended person use the first wave after it ships?
  • Is an essential interface, setup, packaging, or operational step postponed while the wave is called complete?
  • Is a technical artifact being presented as the result?
  • Does the plan solve a larger or more general problem than requested?
  • Could a manual or single-instance path prove the need first?
  • Which complexity disappears when speculative requirements are removed?
  • Can later sophistication be added without invalidating the useful slice?

Do not preserve the plan's structure merely because someone already spent time writing it.

Return the preflight

Lead with one verdict:

  • Smallest useful plan
  • Useful, but reslice the waves
  • Foundation disguised as delivery
  • Complexity ahead of evidence
  • No complete usable wave yet

Then include only what helps:

  1. Core judgment — strongest idea and central scope problem.
  2. Smallest useful result — actor, entry point, scenario, and proof.
  3. Resliced waves — result, proof, limits, and trigger for later machinery.
  4. Enabling sub-steps — necessary work that is not a milestone.
  5. Delete or defer — mechanism, missing evidence, simpler predecessor, and reconsideration trigger.
  6. Usability gaps — missing interface, setup, packaging, failure, or operational path.
  7. Decisions — only choices that materially change the smallest useful path.

Return a preflight, not a larger replacement specification, unless asked.