The agent's pull request is 80 percent right. Now what?

An agent opened a pull request on your repo. It builds, the tests it wrote are green, and it clearly understood something about the ticket. It also cannot go in: a helper duplicated three directories away from the one that already exists, a config file touched for no reason, and the one edge case your acceptance criteria named, left as a TODO.

So you decide: finish it by hand, send it back with notes, or close it and rewrite the ticket. Search that question and you mostly get reviewers for sale. A tool that reads the diff will not tell you which exit to take, and the three cost very different amounts of your week.

The PR that is clearly useful and clearly not mergeable

This is the median outcome, not a bad draw. Researchers went through 567 pull requests opened by Claude Code across 157 open-source projects and found 83.8% eventually merged (paper posted September 2025, revised this February). Of the merged ones, only 54.9% went in untouched. The other 45.1% needed changes first, "especially for bug fixes, documentation, and adherence to project-specific standards."

So nearly half the PRs good enough to merge still needed a human, mostly for house rules, not broken logic. That is "80 percent right" with numbers attached.

Developers report the same from the other side. In the 2025 Stack Overflow Developer Survey, the top complaint about AI tools was "AI solutions that are almost right, but not quite" at 66% of 31,476 answers, ahead of slower debugging at 45.2%.

So stop asking whether you got a lemon and ask something narrower.

One question decides it

Did the agent misunderstand the problem, or understand it and execute badly?

A misunderstanding means the ticket was wrong, and review comments do not fix a wrong ticket: close the PR and rewrite the task. Bad execution means the gap is mechanical, so finish it or send it back with the missing constraint.

That split is our rule of thumb, not a published finding. No dataset we know of separates "misread the task" from "understood it and fumbled", so the support is circumstantial. Spotify's background-agent team reports that the most common thing their automated judge flags is the agent going outside the instructions in the prompt, a scope failure rather than a coding one.

Run it in that order: ticket, then PR description, then only the files the ticket pointed at.

flowchart TD
  A["Read the ticket, then the PR"] --> B{"Does it aim at the problem the ticket describes?"}
  B -->|"No"| C["It misread the task"]
  B -->|"Yes"| D{"Is the gap mechanical, not conceptual?"}
  D -->|"No"| C
  D -->|"Yes"| E{"Closable in under 30 minutes?"}
  C --> F["Close it. Rewrite the ticket."]
  E -->|"Yes"| G["Finish it. Record the fix."]
  E -->|"No"| H["Return the missing constraint."]

Signals the agent misread the ticket

The PR description restates your ticket in broader words than you used. Yours said "reject uploads over 10 MB at the intent step." The PR says "improve the upload flow." That drift is the diagnosis.

It solved a general version of your specific problem. You asked for one extra if and got a configurable strategy interface, so it aimed at something you did not describe.

The files it changed are not where the problem lives. It fixed the symptom's nearest neighbour, which happens when a ticket names an outcome and no boundary.

It asked nothing on an ambiguous ticket, so it resolved the ambiguity silently and you are reading its guess. And the tests assert the behaviour it built rather than the behaviour the ticket described, which is the quiet expensive one: green CI, wrong target.

The activity record is often faster than the diff. A retitled issue, a status jumped to In Review, or edits to fields the task never mentioned all read as scope drift.

Signals it understood and executed badly

Here everything wrong can be named in one sentence, and none of the sentences are about design. Missing tests for a case the ticket named. A helper duplicated instead of imported. Convention drift, where the PR does it differently and both ways work. A correct happy path with the acceptance-criteria edge case unhandled.

Watch for CI touched to make the run pass rather than the code: deleted assertions, a skipped lint step, a loosened timeout. That is the agent optimising for the signal you gave it, and it still belongs here.

Severity is not the axis. A misunderstanding can produce a tidy, well-tested, entirely wrong PR. Bad execution can produce a mess that arrives at the right answer. Judge the target, not the polish.

The three exits, and what each one costs

The trap is diff size. A big diff feels like work you would throw away, so you finish it. The instinct has the sign backwards. In a study of 33,707 agent-authored pull requests, review effort was predictable at creation time from static features alone, mainly patch size and file types, at an AUC of 0.96. Size is a cost signal, never a progress signal.

Exit	Pick it when	What it costs	What you keep
Finish it yourself	Right target, mechanical gap, under 30 minutes	Your afternoon, and your name on a design you did not choose	The branch and working parts
Send it back	Right target, and you can name the missing constraint in one sentence	One run and a wait, at even odds	Same session and PR, kept context
Close and rewrite	Wrong target	Everything in the branch	What it taught you about your ticket

The 30-minute line is arbitrary; tune it. The point of having one is that "I will just fix this bit" turns a twenty-minute review into four hours. Pick the number before you open the diff, then take the exit out loud. A PR in limbo is worse than a wrong exit, because nobody can tell whether it is waiting on you or dead.

How to send it back so the second attempt is different

You have probably already had a round where you told it and it did the same thing. That 33,707-PR study found the shape of it: agents are strong at narrow automation, weak at iterative refinement, and their PRs get abandoned once feedback turns subjective. So make yours the opposite of subjective.

Return the constraint, not the complaint. "This is wrong" gives the agent nothing it did not already have. "Uploads are rejected at the intent step in storage/usage.ts, not at commit, and there must not be a second check" is a fact it lacked. Every review comment is either a fact the agent was missing or noise.

There is a point where more rounds stop paying. Anthropic's own Claude Code best practices puts a number on it. Past two corrections on the same issue in one session, "the context is cluttered with failed approaches. Run /clear and start fresh with a more specific prompt that incorporates what you learned. A clean session with a better prompt almost always outperforms a long session with accumulated corrections."

That is the agent's own vendor telling you to restart.

The odds are better than people expect. Spotify's judge vetoes about a quarter of thousands of agent sessions, and the agent course corrects half the time.

Returning WEB-13. Target is right, one constraint was missing.

Correct: over-cap uploads rejected before the browser PUT.
Wrong:   the check runs at commit. It must run at intent, in
         storage/usage.ts. Commit cannot stop the upload.
Do not:  add a second check. Move the existing one.
Done is: the existing tests pass unchanged, plus a 2 MB file on Free.

People skip that last line, then wonder why the retry stops somewhere arbitrary. If the agent keeps writing fields it should not touch, narrow that in settings, not in the note.

What to change in the ticket when you restart

If the answer was misread, the fix lives upstream. The failed PR is better evidence about your ticket than rereading it yourself, because it shows how your words land on something with no shared context.

Change one thing, usually the boundary, the negative space, or the done condition. The boundary is which file or layer, because agents will cheerfully fix your problem in the wrong place. The negative space is what must not change, and it is almost always missing. The done condition is not "it works" but the command that proves it.

The full set of fields is its own subject, in write tickets AI agents can finish. The rule from a failed PR is narrower: whatever you were about to type into the review comment belongs in the task description. Same instinct at the start of a pilot, argued in how to scope an AI agent's first job.

Where the tracker holds the decision, and where it does nothing

Taskfolk does not review code: no diff view, no static analysis, no line comments. For a machine reading of the diff you want CodeRabbit, Greptile or Graphite, and why that market exists is the subject of AI made code review the bottleneck. The judgement is yours; the tracker holds the record.

The unit is the session, and sessions reopen. Assigning an issue to a connected agent creates a pending session; the agent claims it and moves through the states below. One in review or needs_input can be patched back to running, carrying the same title, note, reported cost and PR link. Once it is done it is frozen: the API returns a conflict, and a second attempt has to be a new session. So return it while it is in review, not after you let it close.

stateDiagram-v2
    [*] --> pending
    pending --> running
    running --> needs_input
    running --> review
    needs_input --> running
    review --> running
    review --> done
    running --> failed
    done --> [*]
    failed --> [*]

Sending it back is one call.

curl -X PATCH "https://taskfolk.ai/api/v1/workspaces/acme/agent-sessions/$SESSION_ID" \
  -H "Authorization: Bearer tfk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"state":"running","note":"Returned: move the cap check to intent."}'

await fetch(`${base}/agent-sessions/${sessionId}`, {
  method: "PATCH",
  headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
  body: JSON.stringify({ state: "running", note: "Returned: move the check." }),
});

requests.patch(
    f"{base}/agent-sessions/{session_id}",
    headers={"Authorization": f"Bearer {key}"},
    json={"state": "running", "note": "Returned: move the check."},
)

The response is the session, same id and external_url, so the PR link survives. An agent's own key needs nothing else; from a human key an owner or admin adds the agent's agent_id, which also closes out a session the agent walked away from. Every write an agent key makes carries that agent's user id, so "who moved this to In Review at 03:41" has an answer in six weeks. More on that in keeping an audit trail of agent changes.

The hard gate is allowed transitions. Each column carries a "can move to" list, enforced on every status write including the API and automations, so a returned item cannot skip from In Review to Done. For a human beat before the change lands, see human-in-the-loop approval.

What none of this fixes

Nothing here tells you whether a duplicated helper matters in your codebase. Decision rights is a nearby but different question: how reversible a decision is, not what went wrong in one attempt.

The verification badge is weaker than it sounds. It flags a review or done session that left no attributed activity or comment on its issue. One comment defeats it, and a session carrying a real PR link is exactly the case it misses. Checking a done claim is covered in managing a team of AI agents.

Reported cost is reported. The agent spends on its own provider account, which Taskfolk cannot see, so a session showing $2.40 shows it because the agent said so. We can alert on the number, not stop the spend. Taskfolk does not run the agent either: it delivers the trigger and keeps the record while the agent's runtime works.

Repo integration is GitHub only, so a GitLab or Bitbucket PR lives in the session link and nowhere else. And none of it helps if you cannot tell a thinking agent from one that quietly gave up, which is a separate diagnosis.

Next agent PR you open, read the ticket before the diff and write the answer down before you scroll: misread, or fumbled. Then take the exit it points at and leave the reason in the session note.