# Core Ideas

Turn an agent failure into an environment problem you can improve and verify.

## More code, more rework

An agent changes several files, but the feature still misses the point. Before changing models, locate the failure: a mistaken goal, missing information, a verification gap, or a design that makes errors easy. Each calls for a different intervention.

Figure: Four failure categories suggest four changes to the environment. ([d02-failure-sort](/diagrams/d02-failure-sort.en.svg))

## Delivery starts a maintenance obligation

Generation speed explains how code arrives. It says little about the next person who must change it. Duplicate implementations, unused branches, and unclear interfaces all make that next decision harder.

Ask what observable behavior a piece of code serves. Which acceptance criterion would fail if it disappeared? If nobody can answer, establish the requirement before deciding whether to keep the implementation.

> If your code sucks, your agent will too.
>
> — Matt Pocock, [source](https://x.com/mattpocockuk/status/2089336734530109837), 2026-08-17

## Give a collaborator a workable environment

An agent needs a way into the project: reliable navigation, shared domain terms, a runnable application, and usable feedback. Repeating a request for care cannot supply a missing fact.

- **Wrong goal** Return to [alignment](/en/alignment-and-prototypes) and agree on behavior.
- **Missing information** Improve [document navigation](/en/agent-documents) and domain language.
- **Verification gap** Build a [feedback loop](/en/implementation-and-feedback).
- **Design defect** Examine [states and module boundaries](/en/state-and-module-boundaries).

> **Our inference**
> Our synthesis: types, interfaces, state models, and checks can reduce opportunities for error. Improve the boundary implicated by this failure; this does not establish a universally best architecture.

An improvement must handle the failing input correctly and keep the valid path working. Hiding the failure or rejecting every request would fail that test.

## Exercise: success without configuration

A submission form displays a sent confirmation even when its service address is missing. Predict whether one more reminder to check configuration would prevent recurrence. Then describe a repair at each of the four layers below.

Figure: Expose false success from a missing service address; reject invalid configuration and verify both invalid and valid paths. ([s02-silent-success](/art/s02-silent-success.en.svg))

### Make false success visibly fail

- Task: submit with the service address missing and record the incorrect confirmation.
- Boundary: stop the send operation on invalid configuration and return an explicit failure.
- Check: missing configuration produces an error; valid configuration still permits sending.
- Review: provide the steps, logs, and visible results for both configurations.

Suggested approach: The boundary rejects invalid configuration, a behavior check catches a returning false confirmation, and review examines evidence from actual operation. State what each layer catches.

## What counts as done?

Deliver a reproducible failure, a repair at the responsible boundary, and a passing result. Another reader should be able to identify where the same mistake would be stopped next time. Relying on an agent's memory leaves that question unanswered.

Also examine the valid request. Did the repair introduce unexplained branches or duplicate an entire implementation? Include the resulting maintenance burden in the discussion.

## Quick reference


## Sources

- [Matt Pocock · 2026-08-17](https://x.com/mattpocockuk/status/2089336734530109837)

Independent, unofficial, noncommercial study notes. This site has no affiliation with or endorsement from Matt Pocock. Referenced works belong to their authors; MIT reuse carries separate copyright and license notices.

The diagram CSS on this page is adapted from Archify (https://github.com/tt-a1i/archify) under the MIT licence; the complete licence follows.

### Full licence: Archify (tt-a1i/archify)

```text
MIT License

Copyright (c) 2026 tt-a1i (Archify)
Copyright (c) 2025 Cocoon AI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```