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. 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.
Reconcile in the editor
Findings are recorded by agents. They are resolved by people, in the spec editor, never by another agent and never silently.
Open the intent and each open finding sits at the top with 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. You reconcile it. 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
- Let it ride into the next agent's prompt instead of fixing it only in your head
- Reconcile or dismiss it in the editor, 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.