3 Investigate before committing

Research becomes useful engineering work when a finding can change a live decision. Without that connection, it can produce a large collection of facts while leaving the actual uncertainty untouched.

In our running example, the team is considering a new publication mechanism for acquired resources. Before designing it, someone should determine whether the existing API already preserves the old resource until a new candidate is ready. A familiar method name is not enough. Its contract, callers, state transitions, and failure behavior matter.

The investigation may reveal that the existing mechanism fits. It may expose a narrow missing operation. Or it may show that the current abstraction confuses transfer completion with consumer readiness. Those outcomes lead to different amounts of work.

Give research a decision and a stopping condition

A useful brief has four elements: the question, the decision affected, the evidence needed, and the condition under which further investigation would stop changing the choice.

For example:

Determine whether the current resource API can publish a verified candidate while preserving existing readers of the old version. Inspect its contract and two actual callers. Exercise the failure boundary if the code does not establish it clearly. If the API already provides this behavior on supported storage, reuse it; otherwise describe the smallest missing promise.

The brief is bounded without demanding a predetermined answer. It does not ask the investigator to “research acquisition architecture” indefinitely. It names what evidence would support reuse and what would justify a change.

A stopping condition is not a timer that makes uncertainty disappear. It is an account of what the decision needs. If the missing evidence remains consequential, report the gap. If further detail would not change the selected reversible step, proceed and retain the limitation.

Investigate the system as it exists now

Puma's architectural discussions emphasize the danger of treating an old integration assumption as a current requirement. A consumer designed around an earlier API may need updating rather than forcing the provider to restore a now-unnecessary behavior. The general lesson is to inspect the current boundary before proposing a repair.

Start with the actual entry point. Follow the successful path, then the error and cancellation paths. Identify what callers rely on and which facts are merely accidental. Read the relevant tests, but distinguish their assertions from observed execution. A test file can explain the intended contract even when it has not been run in the current environment.

Sillito, Murphy, and De Volder's observational work identified programmers' questions ranging from finding a starting point to understanding relationships across code. Search results often needed integration before they answered the real question. The study is not an optimal-search recipe, but it supports describing the relationship you need to understand rather than equating investigation with locating a symbol. Questions Programmers Ask During Software Evolution Tasks.

Treat existing implementation as a constraint with a price

Current code constrains a change because compatibility, migration, and maintenance cost are real. It is not necessarily immutable. A design that exists for historical reasons may be the very thing preventing the intended outcome.

Consider three possibilities. The desired behavior can fit the current interface directly. It can fit after a narrow refactor. Or accommodating it would perpetuate a misleading abstraction, making replacement worthwhile. Investigation should give enough evidence to compare these paths. “This is how the system works” is a description, not a complete argument for retaining it.

The same applies to an external library. Check what it actually guarantees. A cancellation method might request cancellation without waiting for resource release. A version number may correlate with a capability without defining it. A provider may expose a common format while requiring distinct runtime support. Verify the relevant promise rather than infer it from a category label.

Bryan Cantrill’s published Oxide discussion offers a useful distinction. He describes a familiar kernel task deliberately selected to favor the agent, and two subtle defects he needed to correct. That is expert-supervised delegation of a largely understood solution, not open-ended design discovery. His estimate of the time he would have needed without AI is not a control condition. The comparison reminds us to identify which uncertainty the agent is actually being asked to resolve. Engineering Rigor in the LLM Age, especially 07:01–14:56.

Keep research from blocking the conversation

Puma wants background research to proceed while the main agent continues discussing the problem. That can work when the handoff preserves decision ownership. A research task returns evidence, alternatives, and limitations; it does not silently replace the shared direction.

The lead should integrate findings as soon as they matter. “The API already supplies the readiness boundary we need” is actionable. A long report that arrives after the plan has committed to a replacement is less useful. Conversely, an unresolved question should remain visible rather than be filled with an optimistic assumption merely to keep the conversation flowing.

Parallel research is often easier to divide than parallel implementation. One investigator can inspect API semantics while another checks platform support. Their findings can still conflict, especially if they examined different versions. Record the revision or documentation version so the disagreement can be reconciled.

Choose an experiment when reading stops helping

Sometimes the cheapest evidence is a small reversible implementation. If a library's behavior is unclear, a minimal characterization test may be more informative than another hour of documentation. The experiment should state what it is testing and what it does not establish.

A local process-kill test can examine cleanup after process termination. It does not prove resilience to power loss. A prototype on one filesystem can expose a flaw but cannot establish all supported platforms. An experiment becomes misleading when its result is promoted beyond the conditions exercised.

Before your next investigation, write the decision it can change. Afterward, return the finding in that same form: what was inspected, what was observed, what conclusion follows, and what remains uncertain. Research is complete enough when the next commitment has a defensible basis, not when there are no more documents to read.