Let a coding agent correct the spec it's building from

Handing a spec to an agent is the start of the loop, not the end. The most useful thing an agent learns is often that the spec it was handed is wrong somewhere. This use case is how that correction gets back into the spec instead of dying in a diff: the agent records what it found, proposes the exact fix, and a person decides.

The input

A spec in flight: an IntentSpec handed to Claude Code, Cursor, or any agent connected to your Pathmode workspace with an API key, and an agent that, mid-build, hits something the spec got wrong. A constraint that can't be enforced. An outcome assuming a data shape that doesn't exist. A dedupe key that turns out not to be unique. Findings and proposals are written to the workspace, so keyless local mode does not have them.

The flow

1. The agent records a finding, not a workaround. Through the Pathmode MCP server, the agent calls record_implementation_finding with two required parts: assumption (what the spec took for granted) and finding (what building revealed). Optionally a correction and a target pointing at the check it falsifies. The reply hands back a finding id, which is what a proposal answers.

2. The finding flips the falsified check. If the finding targets a verification check (target: "check:<id>"), recording it flips that check to failing in the same write. A finding and a failing check are the same event, so the status is everywhere at once.

3. The agent proposes the exact correction. When it can name what the spec should say instead, it calls propose_spec_change against the finding: which field, whether to replace, add, or remove, the value as it read it, the value it should be, and the reason. The proposal is bound to the exact revision of intent.md the agent read; if the spec has moved since, it is refused rather than silently rebased. It does not change the spec, and the agent cannot apply it. The observation is also stored as unreviewed agent evidence, anchored to the claim it contradicts, so the evidence behind the spec shows what the build saw. The agent keeps building against the authorized revision.

4. It rides into the next prompt. Open findings travel with the spec on every export and MCP pull, and the agent's own pending proposals are listed at the top of its next prompt with one instruction: do not propose this again, and do not build on the proposed value. The next agent reads "the spec assumed X; building showed Y" before it starts, so it never rebuilds the dead premise.

5. You decide, in Pathmode. A proposal gets one of three answers: accept it, reject it with a reason, or counter-propose the correction you actually want. A finding without a proposal keeps its two moves in the editor: reconcile (fold the correction into the spec) or dismiss (the premise stands). Accepting never edits the file. The repository owns intent.md, so the accepted 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.

The output

A spec that converged instead of drifting:

• The contradiction is recorded, with what the spec assumed versus what the build revealed, not lost in a PR thread
• The falsified check reads "failing" everywhere the spec is read, until it's re-verified
• The correction is exact: a field, an old value, a new value, and a reason, bound to the revision it was made against
• The next agent starts from the correction, not the stale premise
• The resolution was a human call: accepted, countered, rejected, or dismissed in Pathmode, with the audit trail kept and the applied revision authorized again

Why this beats a PR comment

A PR comment is read once, by whoever reviews that PR, and then it's archaeology. The spec is read by every future agent and every teammate who opens the intent. Putting the correction where the next reader actually looks is the difference between a loop that converges and one that repeats itself. And a proposal beats a prose correction: it is a change a person can accept in one move, and the system knows when it has actually been applied.

Try it yourself

1. Connect the Pathmode MCP server to your agent with a workspace API key (see the wiring playbook)
2. Hand it a real spec and let it build
3. When it hits something the spec got wrong, have it call record_implementation_finding, then propose_spec_change with the finding id
4. Open the intent in Pathmode and accept, counter, or reject the proposal
5. Let the agent apply the accepted correction to intent.md on its next run, then authorize the new revision

Related

• Playbook: When the Build Contradicts the Spec
• Playbook: Wire Pathmode Into Your Coding Agent
• Use case: Hand off a spec to Claude Code without losing context
• Use case: Let your agent pull intent live with the Pathmode MCP server