From a97433655a749791f6a81198ea319cf7494965e9 Mon Sep 17 00:00:00 2001
From: Brummel <mould@mycelium.de>
Date: Mon, 11 May 2026 19:15:10 +0200
Subject: [PATCH] =?UTF-8?q?skills/implement:=20reorder=20Step=203=20?=
 =?UTF-8?q?=E2=80=94=20switch=20to=20main=20BEFORE=20Boss=20edits?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The orchestrator-agent ends its run with the worktree on
iter/<iter_id>. Step 3 previously listed 'append INDEX line' as
item 3 and 'switch+merge' as item 4 — natural reading order is
top-to-bottom, so the INDEX append (and any other Boss edit) was
landing on the iter branch by mistake. Observed three times on
2026-05-11 during the iter 23.4 family's prep iters.

Fix: explicit warning at the top of Step 3, plus reorder so the
'git switch main && git merge --ff-only' happens before any
Boss-side edit. Summary rewrites (step 2's decision) now defer to
step 5, which runs after the switch, so they also land on main.
---
 skills/implement/SKILL.md | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md
index 64a1ef1..cd1c0e3 100644
--- a/skills/implement/SKILL.md
+++ b/skills/implement/SKILL.md
@@ -114,21 +114,30 @@ orchestrator-agent.
 
 ### Step 3 — Boss merge step (on DONE or PARTIAL)
 
-1. Open the per-iter journal file on the branch:
-   `git show iter/<iter_id>:docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md`
-   (or check out the branch if a closer look is needed).
-2. Accept the agent's Summary section as-is, OR rewrite it with
-   Boss-level framing. The rest of the journal file is factual and
-   preserved verbatim.
-3. Append one line to `docs/journals/INDEX.md`:
-   `- YYYY-MM-DD — iter <iter_id>: <one-line title> → <YYYY-MM-DD>-iter-<iter_id>.md`
-4. Fast-forward main to the iter branch:
+> **Switch to main FIRST.** The orchestrator-agent ends its run with
+> the worktree on `iter/<iter_id>` (Phase 0 created the branch and
+> all per-task commits land on it). Any Boss commit issued before
+> `git switch main` lands on the iter branch by mistake — including
+> the INDEX-append below. This is a recurring papercut. Do the
+> switch before any Boss-side edit.
+
+1. Open the per-iter journal file on the branch (read-only, branch-
+   independent): `git show iter/<iter_id>:docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md`.
+2. Decide whether the agent's Summary section is acceptable or needs
+   a Boss-level rewrite. The rest of the journal file is factual and
+   preserved verbatim. Defer the actual edit to step 5 — it lands on
+   main, not on the iter branch.
+3. Fast-forward main to the iter branch:
    `git switch main && git merge --ff-only iter/<iter_id>`. Since the
    iter branch was created from local `main` (Phase 0 of the
    orchestrator-agent) and no commits have landed on main since, the
    fast-forward is always linear.
-5. Optionally delete the branch: `git branch -D iter/<iter_id>`.
-6. If trigger is done-state and the user is away, write a
+4. Append one line to `docs/journals/INDEX.md` and commit:
+   `- YYYY-MM-DD — iter <iter_id>: <one-line title> → <YYYY-MM-DD>-iter-<iter_id>.md`
+5. If the Summary needed rewriting (step 2), edit the journal file
+   on main now and commit.
+6. Optionally delete the branch: `git branch -D iter/<iter_id>`.
+7. If trigger is done-state and the user is away, write a
    `docs/WhatsNew.md` entry + `notify.sh` per CLAUDE.md's
    "Done-state notifications" subsection.