docs: rewrite the remaining 18 pages to the four-section standard

One agent per page, each rewriting from its SKILL.md up and running its
own evidence hunt across the wiki, the issue tracker and the unreleased
changesets. Question counts track the evidence: wayfinder earns ten,
resolving-merge-conflicts earns three.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs/engineering/resolving-merge-conflicts.md

@@ -1,28 +1,51 @@
 ## What it does
 
-`resolving-merge-conflicts` works through an in-progress git merge or rebase conflict, hunk by hunk, and finishes the operation — resolved, checked, and committed.
+`resolving-merge-conflicts` works through an in-progress git merge or rebase, hunk by hunk, then runs the project's own checks and finishes the operation with a commit.
 
-It resolves by **intent**, not by text. Before touching a hunk it traces each side back to its **primary source** — the commit message, the PR, the original issue — to understand why the change was made, then preserves both intents where they're compatible. It never invents new behaviour to paper over a clash, and it never reaches for `--abort`: the merge always gets finished.
+It refuses to treat a conflict as a text problem. Before touching a hunk it traces each side back to its **primary source** — the commit message, the PR, the original issue — so it is choosing between two intents rather than between two blocks of text, and it preserves both wherever they are compatible. Where they genuinely are not, it picks the side matching the merge's stated goal and names the trade-off. It invents no new behaviour to paper over a clash, and `--abort` is not an option it has: the merge is always carried to a finished commit.
 
 ## When to reach for it
 
 Type `/resolving-merge-conflicts`, or the agent reaches for it automatically when a task fits.
 
-Reach for this when you're mid-merge or mid-rebase and git has stopped on conflicts it can't resolve itself. It's for the conflict in front of you — not for planning the merge or for debugging behaviour that broke afterwards. If the merge is done but something's now failing for reasons you can't see, use [diagnosing-bugs](https://aihero.dev/skills-diagnosing-bugs) instead.
+Reach for it when git has already stopped on conflicts it could not resolve itself. It is scoped to the conflict in front of you, not to anything either side of it:
 
-## Resolving by intent
+| Your situation | Skill |
+| --- | --- |
+| Mid-merge or mid-rebase, conflict markers in the tree | This one |
+| Merge finished, something now misbehaves for reasons you can't see | [diagnosing-bugs](https://aihero.dev/skills-diagnosing-bugs) |
+| Planning how to slice work so branches collide less | Neither — see the parallel-work question below |
 
-The trap in a conflict is treating it as a text problem — picking "ours" or "theirs" to make the markers go away. This skill treats it as an **intent** problem. Each side of a hunk exists because someone wanted something; the resolution has to honour both wants where it can, and where they're genuinely incompatible, pick the one that matches the merge's stated goal and note the trade-off out loud.
+## Primary sources over `ours` and `theirs`
 
-That's why the primary sources matter. You can't preserve an intent you haven't read, so the work starts in the history — commits, PRs, tickets — not in the diff.
+The failure mode this exists to kill is resolving by flag: `--ours`, `--theirs`, or hand-deleting whichever block looks less important, so the markers go away and the build compiles. That resolution can be syntactically perfect and still silently drop a change somebody made on purpose.
+
+You cannot preserve an intent you have not read. So the work starts in the history — commits, PRs, tickets — and only then moves to the diff. Another step in the loop exists for the same reason: the skill finds the repo's own automated checks and runs them before committing, because a merge is the easiest place in git to produce code that satisfies both branches and passes neither's tests.
+
+## Common questions
+
+**Claude Code already resolves conflicts pretty well on its own. Why does this need a skill?**
+
+This was asked directly when the skill was published. Matt's answer: "The 'find the primary sources' + 'run feedback loops' bits are the added value, I'd always need to manually prompt those." An unprompted agent will usually produce a plausible resolution from the diff alone and stop there. The skill's value is the two steps it will not let the agent skip — reading why each side exists, and running the checks afterwards. That is a thin margin over a good model, and it is meant to be: at least one reader has predicted this is a whole skill that becomes a no-op as models improve.
+
+**Should I keep parallel agents off the same files to avoid conflicts in the first place?**
+
+Mostly no. Asked whether he uses zones or similar to minimise conflicts across parallel tasks, Matt's answer was: "Genuinely, AI is so good at doing merge conflicts that this tradeoff is not as harsh as you might think." The one piece of discipline he keeps: "You just make sure that large refactors are done first and that's basically it." A large rename landing after ten branches have forked off it is the case that stays expensive.
+
+One caveat from a user report on parallel worktrees: when sibling sessions each build a ticket in their own tree, the merge back is best done by the session that wrote the change, because it is the one that already knows the intent. Batching everybody's conflicts onto one agent at the end throws away exactly the context step 2 of this skill has to go and reconstruct.
+
+**Why never `--abort`?**
+
+Aborting throws away the resolution work and returns you to the same conflict, unchanged, the next time you try. The skill is written for the case where the merge is going to happen. If you have decided it should not happen, that is a decision to make before invoking, not a branch inside the loop.
 
 ## It's working if
 
-- Each resolved hunk keeps both sides' behaviour, or names the trade-off where it couldn't.
-- No new behaviour appears that wasn't on either branch.
-- The project's own checks — typecheck, tests, format — are found and run green before the commit.
-- The merge or rebase is carried all the way to a finished commit, never aborted.
+- The agent quotes commit messages, PRs or issues at you while resolving, not just diff hunks.
+- Every hunk ends up with both sides' behaviour, or with an explicit note naming what was dropped and why.
+- Nothing appears in the result that was on neither branch.
+- Typecheck, tests and format were located and run green *before* the commit, not after you noticed something broken.
+- You end on a clean tree with the operation completed — including every remaining commit in a multi-commit rebase.
 
 ## Where it fits
 
-A reach-for-it-anytime standalone: you invoke it at the moment a merge or rebase stalls, and it hands you back a clean, committed tree. Its natural neighbour is [diagnosing-bugs](https://aihero.dev/skills-diagnosing-bugs), because a merge that resolves cleanly but misbehaves afterwards is a diagnosis problem, not a conflict one. When you're unsure which skill fits, [ask-matt](https://aihero.dev/skills-ask-matt) routes you.
+A reach-for-it-anytime standalone with no dependencies on any other skill: it starts when git stalls and ends when the tree is clean and committed. Its only real neighbour is [diagnosing-bugs](https://aihero.dev/skills-diagnosing-bugs), which takes over at the point where a merge resolved cleanly but the merged code misbehaves — a diagnosis problem, not a conflict one. It sits off the main idea-to-ship flow entirely, so [ask-matt](https://aihero.dev/skills-ask-matt) is the map for what runs before and after it.