nodumb

nodumb

Code is the cheap part of a mistake. The most expensive thing is to confidently do the wrong thing, in the wrong place, or based on a fact that no one has verified.

Before continuing, answer three questions:

1. Are we solving the right problem? The request often arrives already in the form of a solution.
2. Are we solving it at the right scale? A local fix may be hiding a general solution, and a general layer may turn out to be unnecessary.
3. Is there a new applicable fact? The next attempt on the same data usually repeats the previous one.

Do not go through the entire skill every time. Choose the needed mode based on the current situation. Before starting a mode, state which of its results could change the next step; if there is no such result, skip the mode.

How to choose a source of fact

Look for the fact where the source of truth about the behavior being checked is located. If it is determined by the current project — first observe the code, state, logs, tests, and history. If the source of truth is outside the current repository — check the primary source for the exact version of the dependency, platform, or service: official documentation, changelog, or the owner's issue tracker.

Formulate external search through contract, version, and exact symptom, and not through a general query like "how to fix". A found statement remains a hypothesis until a local probe or reproduction confirms its applicability to this project. Before the second edit without a new fact, be sure to change the data source; for a detailed choice — references/stuck-new-data.md.

1. Before code

Apply if the wrong direction costs hours, the result is hard to undo, or it is unclear why a specific solution was proposed.

• Formulate the task from the user's perspective, not from the interface or code.
• If the setup will remain in a ticket, plan, or another durable artifact, separate the verified from the assumed. For statements that determine the direction of the decision, specify the verification source.
• Consider a new fact a basis for a decision only within the verified scope of applicability. If the entities, premises, conditions, method of measurement, base, scale, or model change, treat the transfer as a separate inference: justify it deductively through the preservation of premises and relations, empirically in the target context, or both. Without verification, call the inference for the new model a hypothesis.
• A hypothesis that can be safely verified now using available code, history, documentation, or a command should be verified before being recorded. If it cannot be, call it a hypothesis and specify what is needed for verification: unavailable data, human involvement, or an expansion of scope.
• A question that depends on human choice should be called an unresolved decision, not a hypothesis. If the answer creates a fork, record the branches and the condition for the choice.
• Check how a person handles it now and what should become better.
• Name a sign of success that can be observed.
• Find the most expensive fork and give one recommendation.
• If the proposed solution changes the architecture, product model, or several independent scenarios, first measure the size of the problem: how many scenarios are broken, how often this happens, and how a person handles it now.
• Compare the cheapest solution with the proposed one. For each, name the user outcome, the scope of change, and the risk to existing behavior. If the outcome is the same, choose the cheap one. The expensive one is justified only if the cheap one leaves specific confirmed cases unresolved.
• Before returning to a previously rejected architectural idea, check the decisions and project memory. Name the new fact that makes the previous decision no longer valid; without a new fact, do not reopen the fork.
• Explicitly agree only on an irreversible decision, a significant uncertainty, or a scope change. In other cases, state the assumption and continue.
• Treat data, permissions, and public behavior as amplifiers of the cost of error, not as automatic reasons for a question. Stop for a human choice only if a new access policy needs to be defined, data loss or migration must be allowed, or an existing public contract must be changed. If the behavior is already unambiguously defined by a verified contract, execute it and continue.

Questions for review — references/before-code-questions.md. Plan format — references/plan-format.md.

2. Before a mass edit

Apply if the current task requires making the same change in several independent places.

• First determine the product phase. In a prototype and MVP, do not build a system for the sake of code cleanliness: it is more important to test the hypothesis quickly.
• In the established part of the product, count the places and values before editing.
• Check whether the repetitions really have the same reason to change.
• If the absence of a shared place is already hindering current work, extract a minimal source: a contract, token, component, adapter, or script.
• If it is not hindering or the reasons are different, leave the decisions local.
• Start with one small area and verify it before the mass transfer.

Do not create a design system, component library, or another layer just "for the future." A normal result of the check is a shared layer is not needed yet.

Details: references/scaling-phases.md for choosing the phase, references/scaling-triggers.md for counting and references/scaling-build-system.md for the value system. The original case — references/scaling-postmortem.md.

3. When debugging has stalled

Before the second edit, obtain a new fact. After two failed edits, consider that the previous method is exhausted.

• First reproduce the symptom on the branch where it occurs.
• Formulate the hypothesis so that the test could refute it.
• Change the data source: log, state dump, minimal example, change history, documentation, issue tracker, or a working analogue.
• Only after a new observation, change the code.
• If a fix was declared but not confirmed, first replace the verification method rather than making another edit.

Ways to obtain new data — references/stuck-new-data.md. Questions about the framing itself — references/stuck-question-premise.md. Analysis after a long deadlock — references/stuck-postmortem.md.

How to respond

Start with a recommendation. Briefly state what is known, where the main uncertainty lies, what to do next, and how to verify the result. Do not turn this into a mandatory template for small tasks.