A coding agent picked up a spec: "group duplicate support tickets so the team triages the original, not every copy." It started building and hit the wall the spec never saw. Duplicates don't cluster by ticket. They span threads. The same problem arrives as a reply on one ticket, a fresh ticket from a second user, and a screenshot forwarded into Slack. The spec assumed the dedupe key was the ticket. The build proved the key is the underlying problem.
That is the most valuable thing that happened all day, and in most workflows it vanishes. The agent works around it, drops a line in the PR, and moves on. The spec still says "by ticket." The next agent, next sprint, reads the spec and rebuilds the same dead premise.
Key Takeaway: A decision records what you chose. A finding records what the build proved you wrong about. Both belong in the spec, or the spec stops being true.
The direction verification doesn't cover
Verification Is a Feedback Loop asks one question after the agent walks away: did the intent hold? That is the forward direction, the spec judging the build.
This guide is the other direction: the build judging the spec. Sometimes the implementation is fine and the spec was wrong. A constraint that can't actually be enforced. An outcome that assumed a data shape that doesn't exist. An edge case the real system makes impossible. Verification catches a build that drifted from a correct spec. It has nothing to say about a spec that was wrong from the start. That gap is what a finding fills.
A finding is the inverse of a decision
A decision in Pathmode records a choice you made and why: "we ruled out SSO for v1 because there's no enterprise evidence yet." It travels with the spec so nobody relitigates it.
A finding is the mirror image. It records a claim the spec made that the build contradicted:
- assumption: what the spec took for granted ("duplicates share a ticket id")
- finding: what building revealed ("duplicates span threads; there is no shared id")
- correction (optional): what the spec should say instead
It is not a bug report and not a task. A bug says the code is wrong. A finding says the spec was wrong, which is the more expensive mistake, because every downstream agent inherits it.
💡 Tip: If the fix belongs in the code, it's a bug. If the fix belongs in the spec, it's a finding. The test: would the next agent, reading the current spec, make the same mistake? If yes, write the finding.
How the build writes back
An agent records a finding the moment it hits the contradiction, through the record_implementation_finding MCP tool, without leaving the build. Findings live in the workspace, so this is connected mode; keyless local mode has no store for them. Three things happen, and they are what turn a note into a loop:
- The finding rides into the next agent's prompt. Open findings travel with the spec on every export and every MCP pull. The next agent reads "the spec assumed X; building showed Y" before it writes a line, so it builds from the correction, not the dead premise.
- It can flip a verification check to failing. If the finding targets a specific check (
target: "check:<id>"), recording it flips that check to failing in the same write. The build proving the spec wrong on an asserted check is the same event as that check failing, so the status reaches every reader at once. - It stays open until a human closes it. A finding is a flag, not a fact the agent gets to apply. It rides along, visible, until someone with judgment decides what to do with it.
Propose the exact correction
A finding says the spec is wrong. A proposal says what it should say instead. When the agent can name the fix, it calls propose_spec_change against the finding: the field, whether to replace, add, or remove, the value as it read it, the value it should be, and the reason. In the dedupe story that is one replace on one constraint: "group by ticket id" becomes "group by the underlying problem across threads."
Three properties keep a proposal from becoming a model overwriting your intent:
- It is bound to the revision the agent read. If
intent.mdhas moved since, the proposal is refused, never silently rebased onto text the agent did not see. - It changes nothing on its own. The spec is untouched, and the agent cannot apply its own proposal. Until a signed-in person accepts it, the agent keeps building against the authorized revision, and its next prompt lists the pending proposal with one instruction: do not propose it again, do not build on it.
- It leaves evidence. The observation is stored as unreviewed agent evidence, anchored to the claim it contradicts, so whoever opens the intent sees what the build saw next to the sentence it disproved.
💡 Tip: Record the finding even when you cannot name the correction. Propose only when you can state the exact new value; a vague proposal is a finding wearing a costume.
Decide in the editor
Findings are recorded by agents. They are resolved by people, in Pathmode, never by another agent and never silently. An agent may apply a correction to the file, but only one a person has already accepted.
A proposal gets one of three answers:
- Accept: you agree with the exact correction. Accepting does not edit
intent.md; the repository owns that file. The proposal becomes a change request the repository agent applies on its next run, the finding is marked reconciled when that lands, and the new revision goes back through human authorization before anyone builds on it. - Counter-propose: the spec was wrong, but not in the way the agent thinks. You write the correction you want, and it reaches the agent as a PM request to apply.
- Reject, with a reason: the premise stands, or the fix belongs in the code. The finding stays visible; the proposal stops speaking for it.
A finding without a proposal keeps its two moves:
- Reconcile: you agree the spec was wrong. You fold the correction into the spec (rewrite the constraint, fix the outcome), and the finding stops riding into prompts. If it had flipped a check to failing, reconciling clears that check back to unverified, awaiting a fresh run.
- Dismiss: you judge the finding not worth acting on. The premise stands. The finding stops riding along, but the audit trail keeps it.
That human step is the point. The agent surfaces the contradiction; you decide whether the spec or the build was the thing to change. The loop converges because a person closed it, not because a model overwrote your intent.
Key Takeaway: The agent writes the finding and may propose the fix. You accept, counter, reject, or dismiss. Convergence is a judgment call, not an automatic merge.
Don't turn every surprise into a finding
A finding is expensive attention. It rides into prompts and can fail a check. Spend it only when the spec is what was wrong.
- A typo the agent fixed in passing is a commit, not a finding.
- A genuinely new requirement the build surfaced is a new intent or a new outcome, not a finding against the old premise.
- A finding is for the case where the spec asserted something the build proved false, and the next agent would repeat it.
If your findings list is long and noisy, that's its own signal: either the specs are being written too far from the code, or findings are being used as a scratchpad. A healthy loop produces few findings, and most get reconciled.
Run the loop
Next time an agent contradicts a spec mid-build:
- Record it as a finding (
assumption+finding), not a buried PR comment - Point it at the check it falsifies, if there is one, so the status travels
- If the exact correction is clear, propose it with
propose_spec_changeagainst the finding, and keep building against the authorized revision - Let it ride into the next agent's prompt instead of fixing it only in your head
- Accept, counter, reject, reconcile, or dismiss it in Pathmode, so the spec converges instead of carrying a premise the build already disproved
The spec that gets corrected by the build is the one still worth handing to the next agent.