docs(agents): a red PR is the next unit of work, and check the workspace

Two gaps the first post-migration decoder iteration exposed, both in the same
place — the loop ends before it can observe its own result.

1. Step 1 read notifications but never looked at the agent's own open PRs. It
   opened #23, labelled the issue `state/needs-human`, and stopped; nothing in
   the brief would ever bring it back to a red check. Next iteration it planned
   to start a new question on top.

2. It called the merge resolved on `cargo build -p sylpheed-cli` — the crate the
   conflict was in. The break was in `sylpheed-viewer`, which neither side of
   the merge edited: one branch added a `ComposeOptions` field, the other had a
   literal construction of it. The crate you just fixed is the one place the
   breakage cannot be.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

docs/agents/decoder-loop.md

@@ -95,6 +95,10 @@ Treat it as a fast index into 9.2 MB of machine code, not as a source of truth.
 ## Each iteration
 
 1. **Read your notifications**, then `git fetch origin && git merge origin/main`.
+   Notifications are **polled — nothing pushes them.**
+   Then **look at your own open PRs.** A PR of yours with a red or still-
+   pending check is your next unit of work, *ahead of any new question*. You
+   opened it and stopped; nobody else is going to make it green.
 2. **Pick one question** — the highest-priority `state/approved` item. Mid-
    question? Continue it.
 3. **Do the smallest experiment that could settle it**, and try to *refute* your
@@ -113,6 +117,20 @@ Treat it as a fast index into 9.2 MB of machine code, not as a source of truth.
 7. **Commit, `push-work`, open the PR**, label the issue `state/needs-human`, and
    **stop.** One unit per iteration; do not stack a second on an unverified first.
 
+## Before you call a merge resolved
+
+**Check the workspace, not the crate you touched** — `cargo check --workspace
+--all-targets`.
+
+🔴 A merge can break a crate that neither side edited. PR #23 resolved a
+conflict in `sylpheed-cli`, confirmed `cargo build -p sylpheed-cli`, and went
+red on `sylpheed-viewer` — where one branch had added a struct field and the
+other had a literal construction of that struct. Neither file was in the
+conflict, so nothing in the merge pointed at it.
+
+The crate you fixed is the one place the break *cannot* be, because you just
+looked at it.
+
 ## Hard rules
 
 * **Do not build the port.** No Godot, no exporter, no transcoding.

docs/agents/port-loop.md

@@ -98,6 +98,9 @@ written down. Steps 1 and 8 are the ones that were missing entirely.
 1. **Read your notifications**, then `git fetch origin && git merge origin/main`.
    Notifications are **polled — nothing pushes them.** If you skip this, nothing
    addressed to you ever arrives, and it looks like silence rather than an error.
+   Then **look at your own open PRs.** A PR of yours with a red or still-
+   pending check is your next unit of work, *ahead of any new item*. You opened
+   it and stopped; nobody else is going to make it green.
 2. **Pick one item** — the highest-priority `state/approved` issue that is yours.
    Mid-item? Continue it.
 3. **Build the smallest thing that reaches a gate.** A gate is an **artifact**,
@@ -122,6 +125,20 @@ written down. Steps 1 and 8 are the ones that were missing entirely.
    set the label. Those are two separate MCP calls (`pull_request_write`,
    `issue_write`), and they are the two most commonly skipped steps in this list.
 
+## Before you call a merge resolved
+
+**Check the workspace, not the crate you touched** — `cargo check --workspace
+--all-targets`.
+
+🔴 A merge can break a crate that neither side edited. PR #23 resolved a
+conflict in `sylpheed-cli`, confirmed `cargo build -p sylpheed-cli`, and went
+red on `sylpheed-viewer` — where one branch had added a struct field and the
+other had a literal construction of that struct. Neither file was in the
+conflict, so nothing in the merge pointed at it.
+
+The crate you fixed is the one place the break *cannot* be, because you just
+looked at it.
+
 ## The wall
 
 The Godot project **never reads a disc format**. No IPFB, RATC, T8aD, XMA or WMV.