# Tools live in the tree

> When the method lacks a capability, the gap is closed by a tool that lives in the tree with a command surface of its own, as shown in closing a gap].

Page: Methodology · Build
Canonical: https://banes-lab.com/disciplined-methodology/build#tools-live-in-the-tree

This section is stop 35 of 102 in the learning route. Previous: [20 - A check matches a shape](https://banes-lab.com/disciplined-methodology/build/a-check-matches-a-shape.md). Next: [22 - One home](https://banes-lab.com/disciplined-methodology/build/one-home.md). It builds on [07 - Where a rule lives](https://banes-lab.com/disciplined-methodology/start/from-chat-to-tree.md).

When the method lacks a capability, the gap is closed by a tool that lives in the tree with a command surface of its own, as shown in [E1·a closing a gap](https://banes-lab.com/disciplined-methodology/build#tools-live-in-the-tree-panel-a). That is how [the stance](https://banes-lab.com/disciplined-methodology/start/the-stance.md)'s third sentence, that every manual step is a failure of automation, is held by something other than the developer's memory. Which tools exist, what kind each one is and why it exists follow from the method rather than from preference: a tool exists where a check needs an input, where a developer would otherwise repeat a step, or where an eye would otherwise stand in for a measurement, as shown in [E1·b a look tool](https://banes-lab.com/disciplined-methodology/build#tools-live-in-the-tree-panel-b). A tool that does something irreversible reads its preconditions first, as shown in [E1·c before an irreversible tool](https://banes-lab.com/disciplined-methodology/build#tools-live-in-the-tree-panel-c). The grammar page states the caller's half of the same contract under [semantic operations](https://banes-lab.com/pag/guide/tool-invocation.md): an instruction names an operation, and the binding names the tool.

### Every manual step is a missing tool

The cheapest response to a missing capability is to do the thing by hand, and doing it by hand is where the variation comes in. A ten-minute manual procedure runs weekly for a year, differently each time, and the one week it is skipped is the week it mattered. A manual loop is faster the first time and slower every time after, and nothing records how it was done.

For this reason I close a capability gap with a tool in the tree, never with a manual loop or a workaround. The tool that already owns the concern is extended first, rather than a second tool being added beside it. In practice, a gap is closed by writing a tool with a declared command surface that lives in the tree. The tool shows its contract before it has any effect: its flags are declared, an undeclared flag is refused, and its help is printed on request. A tool that allocates or rewrites values runs in preview and shows its diff before it applies it. Where a mechanism needs something written to a surface, that surface is made writable by a tool before the requirement exists.

To check this, list every step you performed by hand this week. Each one is either a tool that does not exist yet, or a tool that exists and was not used. A one-off script belongs in a scratch location, and it moves into the tree as soon as its [reusability](https://banes-lab.com/records/arch/reusability.md) shows. The discipline applies to anything a second run will need, so a scratch tool that gets a second run has already crossed that line.

The tools fall into kinds by what they stand in for. A generator stands in for a fact that would otherwise be typed by hand, such as an index, a catalogue, a document derived from a manifest or a rendered diagram; this is [derived state](https://banes-lab.com/disciplined-methodology/verify/derived-state.md) written by code. A validator stands in for a review that would otherwise be done from memory, such as finding every route, catching internal names that leak into public copy, or resolving every reference a document makes. A fixer stands in for a repair that has [one correct answer](https://banes-lab.com/disciplined-methodology/verify/one-correct-answer.md), and a probe stands in for an eye. Every kind is reached through [one chain](https://banes-lab.com/disciplined-methodology/ship/one-chain.md), for the reason that section gives.

The probe deserves the most attention, because the eye is the measurement most often trusted and least often right, the failure described in [it looked right](https://banes-lab.com/disciplined-methodology/verify/it-looked-right.md). A visual, numeric or timing defect is diagnosed by adding a probe that writes out a value you can read before anything is changed, which is [observability](https://banes-lab.com/records/arch/observability.md) built for one question, and by binary-searching the pipeline against a known-good control. Adjusting values over repeated runs proves nothing. A look tool therefore returns what the eye cannot see: beside the screenshot, it returns the console log the page produced while rendering, the layout the engine computed and the markup that was actually in the tree. A screenshot the developer hands over counts as the measurement. The tool takes one capture per question rather than relaunching in a loop, because a second capture is exactly the tuning by eye the probe is there to replace.

A tool that performs an irreversible operation skips any standing precondition its code does not implement, and it still reports success. So before such a tool runs, the standing instructions that bear on the operation are compared with what the tool actually does, by reading its code rather than its help, since the help has no reason to mention a precondition the code does not implement. A missing step is first taken by hand and declared, and then built into the tool, so the next run does not depend on the developer or the model remembering it. A step skipped before a deletion cannot be made up later, because what it needed is gone.

The requirement and the means of writing what it needs tend to arrive in different changes, and only the requirement feels like the work. A mechanism is built, it needs an input, the input lives in a file, and nothing in building the mechanism asks how that file gets written. The requirement lands complete, and the write it depends on is left to whichever developer or model runs into it, done by hand without any of the protections a tool's write carries. For this reason the question of what writes a file is asked as soon as that file becomes an input, and the answer is a tool that writes it, in place before the requirement that needs it.

E1·a closing a gap

```mermaid
flowchart TB
gap["A capability gap appears"]
owner{"Does something already own this concern?"}
extend["Extend the owner, so the next consumer inherits it"]
build["Author a tool with a command surface, in the tree"]
loop["A manual loop"]
workaround["A workaround"]
gap --> owner
owner -- yes --> extend
owner -- no --> build
gap -. the tempting moves .-> loop
gap -. the tempting moves .-> workaround
```

E1·b a look tool

```mermaid
flowchart TB
question["A visual question"]
tool["The look tool · one capture per question"]
shot["The screenshot · what the eye sees"]
console["The console log · what the page said while rendering"]
layout["The layout · what the engine computed"]
dom["The markup · what was actually in the tree"]
answer["An answer with a value you can read"]
question --> tool
tool --> shot
tool --> console
tool --> layout
tool --> dom
shot --> answer
console --> answer
layout --> answer
dom --> answer
```

E1·c before an irreversible tool

```mermaid
flowchart TB
invoke["An irreversible operation is about to run"]
preconditions["Enumerate the standing preconditions bearing on it"]
code["Read the tool's code for each · not its help"]
missing{"Does the tool implement every one?"}
hand["Take the missing step by hand first, and declare it"]
encode["Encode the step in the tool for the next invocation"]
run["Run it"]
invoke --> preconditions --> code --> missing
missing -- yes --> run
missing -- no --> hand --> encode --> run
```

## Links to

- [The stance](https://banes-lab.com/disciplined-methodology/start/the-stance.md)
- [Semantic operations](https://banes-lab.com/pag/guide/tool-invocation.md)
- [Reusability](https://banes-lab.com/records/arch/reusability.md)
- [Derived state](https://banes-lab.com/disciplined-methodology/verify/derived-state.md)
- [One correct answer](https://banes-lab.com/disciplined-methodology/verify/one-correct-answer.md)
- [One chain](https://banes-lab.com/disciplined-methodology/ship/one-chain.md)
- [It looked right](https://banes-lab.com/disciplined-methodology/verify/it-looked-right.md)
- [Observability](https://banes-lab.com/records/arch/observability.md)

## Linked from

- [The stance](https://banes-lab.com/disciplined-methodology/start/the-stance.md)
- [One correct answer](https://banes-lab.com/disciplined-methodology/verify/one-correct-answer.md)
- [Posting and waiting are one operation](https://banes-lab.com/disciplined-methodology/collaborate/posting-and-waiting-are-one-operation.md)