The PR Shepherd resolves only the conflicts it understands

The PR Shepherd in the factory at software-factory.dev does something most automations skip. It resolves merge conflicts. But only the ones it has decided it is allowed to touch.

A move for every way a pull request stalls

It runs on a schedule, every two hours, with the cron line 0 */2 * * *. Each run it lists every open, non-draft pull request and asks what has gone wrong.

Pull requests stall in predictable ways. The reviewer never started. CI finished but no review landed. A review asked for changes and no one followed up. A branch sat open too long. Two branches solve the same issue. One conflicts with main.

For each of those the Shepherd has a move. It closes duplicates, re-triggers a stalled review with an empty commit, runs stuck CI again, summarizes an ancient pull request for a human.

Reading the conflict markers

The conflict handling is the part worth copying. When a branch conflicts with main, the Shepherd checks it out and tries to rebase. A clean rebase runs lint, typecheck, and tests, then force-pushes. If the rebase hits conflicts, it does not give up, and it does not blindly resolve either. It reads the markers.

It resolves two conflict kinds:

• Additive, where both sides only added new lines at the same point and nothing overlaps.
• Non-overlapping, where each side edited a different part of the same hunk.

Both have one obvious answer: keep both.

One conflict kind it will not touch. A semantic conflict, where both sides changed the same lines with incompatible intent. There it aborts the rebase and adds the needs-human label. No guessing.

Encoding where competence ends

That refusal is the whole design. The easy part is the rebase command. The hard part is encoding, precisely, where its competence ends. An automation that resolves every conflict it meets will eventually merge two intentions that were never meant to coexist, and you find that out in production.

The factory you can leave running is the one that knows what it must hand back.

You can read the whole automation in the PR Shepherd definition on GitHub (opens in a new tab).

Where does your own tooling draw that line today, and is the line written down or just assumed?

Further reading

• Human accountability →
• Agentic Software Factory: Advanced Team Training →