From c20a3f548fd0c82832b42c840c316e18e2fe076d Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Wed, 29 Apr 2026 04:23:45 +0100
Subject: [PATCH] docs: update Clownfish cloud PR skill

---
 .agents/skills/clownfish-cloud-pr/SKILL.md | 38 ++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/.agents/skills/clownfish-cloud-pr/SKILL.md b/.agents/skills/clownfish-cloud-pr/SKILL.md
index 06ccc9a2dcf..4c7c384884f 100644
--- a/.agents/skills/clownfish-cloud-pr/SKILL.md
+++ b/.agents/skills/clownfish-cloud-pr/SKILL.md
@@ -13,6 +13,8 @@ cloud from issue/PR refs plus a custom prompt.
 ```bash
 cd ~/Projects/clownfish
 git status --short --branch
+gh variable list --repo openclaw/clownfish --json name,value \
+  --jq 'map(select(.name|test("^CLOWNFISH_"))) | sort_by(.name) | .[] | {name,value}'
 npm run create-job -- \
   --repo openclaw/openclaw \
   --refs 123,456 \
@@ -30,6 +32,26 @@ The script checks for an existing open PR/body match and remote branch named
 `clownfish/<cluster-id>` before writing a duplicate job. Use `--dry-run` to
 inspect the exact job body.
 
+## Ask For A Replacement PR
+
+The skill can trigger replacement PR writing through the normal `create-job`
+and `dispatch` path. Put the maintainer decision in the prompt:
+
+```md
+Treat #123 as useful source work. If the source branch cannot be safely updated
+because it is uneditable, stale, draft-only, unmergeable, or unsafe, create a
+narrow Clownfish replacement PR instead of waiting. Preserve the source PR
+author as co-author, credit the source PR in the replacement PR body, and close
+only that source PR after the replacement PR is opened.
+```
+
+The worker should emit `repair_strategy=replace_uneditable_branch` and list the
+source PR URL in `source_prs`. The deterministic executor opens or updates
+`clownfish/<cluster-id>`, adds non-bot source PR authors as `Co-authored-by`
+trailers, and closes the superseded source PR only after the replacement PR
+exists. New replacement PRs are blocked when the touched area already has
+`CLOWNFISH_MAX_ACTIVE_PRS_PER_AREA` open Clownfish PRs.
+
 ## Validate And Dispatch
 
 ```bash
@@ -46,8 +68,18 @@ npm run dispatch -- jobs/openclaw/inbox/clawsweeper-openclaw-openclaw-123.md \
 ```
 
 Do not use `--dispatch` until the job is committed and pushed; the workflow
-reads the job path from GitHub. Keep `CLOWNFISH_ALLOW_MERGE=0` unless Peter
-explicitly opens the merge gate.
+reads the job path from GitHub. Execute/fix gates are closed unless the repo
+variables are literally `1`; open them only for the execution window:
+
+```bash
+gh variable set CLOWNFISH_ALLOW_EXECUTE --repo openclaw/clownfish --body 1
+gh variable set CLOWNFISH_ALLOW_FIX_PR --repo openclaw/clownfish --body 1
+gh variable set CLOWNFISH_ALLOW_MERGE --repo openclaw/clownfish --body 0
+```
+
+Reset `CLOWNFISH_ALLOW_EXECUTE=0` and `CLOWNFISH_ALLOW_FIX_PR=0` after the
+window. Keep `CLOWNFISH_ALLOW_MERGE=0` unless Peter explicitly opens the merge
+gate.
 
 ## Maintainer Comment Commands
 
@@ -84,6 +116,8 @@ Scheduled routing stays dry until `CLOWNFISH_COMMENT_ROUTER_EXECUTE=1` is set in
 
 - One cluster, one branch, one PR: `clownfish/<cluster-id>`.
 - No security-sensitive work.
+- New replacement PRs are capped per touched area by
+  `CLOWNFISH_MAX_ACTIVE_PRS_PER_AREA`.
 - Do not close duplicates before the fix PR path exists, lands, or is proven
   unnecessary.
 - Codex workers do not get GitHub tokens; deterministic scripts own writes.