@openhands/agent-canvas 1.5.2 → 1.6.1

package/dist/node_modules/@openhands/extensions/skills/index.js

@@ -207,7 +207,7 @@ var e = [
 			"/verify",
 			"/babysit"
 		],
-		content: "# /iterate — Drive a PR to Merge-Ready\n\nIterate on a pull request until it passes all verification layers.\nYou push, poll, fix, and push again — the loop only ends when the PR is green\nor a blocker requires human help.\n\nNo scripts — you are the orchestration loop. Uses only standard `gh` CLI\ncommands that work on any GitHub repo.\n\nRequires: `gh` CLI authenticated with repo access, a PR branch.\nWindows PowerShell equivalents for Bash-only assignment, redirection, and quoting patterns in this skill are in `references/windows.md`.\n\n## Discover what the repo has\n\nNot every repo has all three verification layers. Before entering the loop,\ncheck which ones exist. Only poll layers that are actually set up.\n\n```bash\ngh workflow list --json name --jq '.[].name'\n```\n\n- **CI checks** — almost every repo has these. If `gh pr checks` returns results, CI is present.\n- **PR review bot** — look for a workflow named like \"PR Review\" or \"pr-review\" in the output above, or check for `.github/workflows/pr-review*.yml` in the repo. If it's not there, the repo doesn't have automated PR review. Skip step 3 entirely.\n- **QA bot** — look for a workflow named like \"QA\" or \"qa-changes\". If it's not there, the repo doesn't have automated QA. Skip step 4 entirely.\n\nA repo might have only CI. Or CI + review. Or all three. Your \"all passed\"\ncondition is: every *present* layer is green. Don't block waiting for layers\nthat don't exist.\n\n## The loop\n\n1. Push and ensure a draft PR exists.\n2. Poll each present verification layer.\n3. Decide: all passed? fix needed? wait?\n4. If fix needed — fix, commit, push, re-request review from bots, go to 2.\n5. If waiting — sleep per polling cadence, go to 2.\n6. If all present layers passed on the *current* SHA — mark PR ready, done.\n\nIMPORTANT: pushing a fix is NOT the end. After every fix+push you MUST\nre-request review from the review bot (if present) and go back to step 2.\nThe loop only ends when the verifiers pass on your latest SHA. Addressing\nfeedback and pushing a commit is just one iteration — the bot needs to\nreview the new code too.\n\nDo not stop to ask the user whether to continue polling; continue\nautonomously until a strict stop condition is met or the user interrupts.\n\n## Step 1 — Push and ensure PR exists (as draft)\n\nCreate the PR as a draft. This prevents repo automations (merge workflows,\nartifact cleanup, auto-merge) from triggering while you're still iterating.\nYou mark it ready only after all verification layers pass.\n\n```bash\ngit push origin HEAD\ngh pr create --fill --draft 2>/dev/null || true\ngh pr view --json number,url,headRefOid,isDraft --jq '\"\\(.number) \\(.url) \\(.headRefOid) draft=\\(.isDraft)\"'\n```\n\nIf the PR already exists and is not a draft, convert it:\n\n```bash\ngh pr ready --undo\n```\n\n## Step 2 — Poll CI checks\n\n```bash\ngh pr checks --json name,state,bucket --jq '\n  { passed:  [.[] | select(.bucket==\"pass\")]  | length,\n    failed:  [.[] | select(.bucket==\"fail\")]  | length,\n    pending: [.[] | select(.bucket==\"pending\")] | length }'\n```\n\n- Zero failed, zero pending → CI green.\n- Any pending → wait and re-poll.\n- Any failed → diagnose (see \"CI failure classification\" below).\n\nTo inspect a failure:\n\n```bash\nSHA=$(gh pr view --json headRefOid --jq .headRefOid)\ngh run list --commit \"$SHA\" --status failure --json databaseId,name,conclusion \\\n  --jq '.[] | \"\\(.databaseId)\\t\\(.name)\\t\\(.conclusion)\"'\ngh run view <run-id> --log-failed\n```\n\n## Step 3 — Poll PR review (if present)\n\nSkip this step if the repo has no review bot.\n\n```bash\ngh pr view --json reviews --jq '\n  [.reviews[] | select(\n    .authorAssociation == \"OWNER\" or\n    .authorAssociation == \"MEMBER\" or\n    .authorAssociation == \"COLLABORATOR\" or\n    (.author.login | test(\"openhands|all-hands-bot\"; \"i\"))\n  )] | last | { state: .state, reviewer: .author.login, body: .body[0:300] }'\n```\n\n- `APPROVED` → review passed.\n- `CHANGES_REQUESTED` → read the body and inline comments, fix code.\n- `COMMENTED` → may have actionable suggestions; read and decide.\n- No matching review yet → bot may still be running; wait and re-poll.\n\nInline review comments (when changes requested):\n\n```bash\ngh api \"repos/{owner}/{repo}/pulls/{number}/comments\" \\\n  --jq '.[] | select(.user.login | test(\"openhands|all-hands-bot\"; \"i\"))\n        | { path: .path, line: .line, body: .body[0:200] }'\n```\n\nOn a fresh iteration, existing pending review feedback should be checked\nimmediately — not only comments that arrive after monitoring starts.\nAlready-open review comments must not be missed.\n\n## Step 4 — Poll QA report (if present)\n\nSkip this step if the repo has no QA bot.\n\nQA reports are PR issue comments with a status line like `Status: PASS`.\n\n```bash\ngh api \"repos/{owner}/{repo}/issues/{number}/comments\" --paginate \\\n  --jq '[.[] | select(\n    (.user.login | test(\"openhands|all-hands-bot\"; \"i\")) and\n    (.body | test(\"Status:\\\\s*(PASS|FAIL|PARTIAL)\"; \"i\"))\n  )] | last | { author: .user.login, body: .body[0:500], url: .html_url }'\n```\n\n- `PASS` → QA passed.\n- `FAIL` → read details, fix code.\n- `PARTIAL` → some passed, some failed; read details.\n- No QA comment yet → bot may still be running; wait and re-poll.\n\n## Step 5 — Decide and act\n\nFor each present layer, check its status. If a layer is not present in the\nrepo, treat it as passing.\n\n- All present layers green on current SHA → done.\n- CI failed → fix code, or rerun if flaky (see below).\n- Review requested changes → read comments, fix, push.\n- QA failed/partial → read report, fix, push.\n- Anything still pending → sleep per polling cadence, re-poll.\n- PR closed/merged → stop.\n\n**Priority rule:** when both review feedback and flaky CI failures are present,\nprioritize review feedback first. A new commit will retrigger CI, so avoid\nrerunning flaky checks on the old SHA when you're about to push a review fix.\n\nAfter fixing, commit, push, AND re-request review:\n\n```bash\ngit add -A\ngit commit -m \"fix: address <CI failure | review feedback | QA failure>\"\ngit push origin HEAD\n\n# Re-request review from the bot so it reviews the new SHA:\ngh pr comment --body \"Addressed feedback in $(git rev-parse --short HEAD). Ready for another look.\"\ngh api -X POST \"repos/{owner}/{repo}/pulls/{number}/requested_reviewers\" \\\n  -f 'reviewers[]=all-hands-bot'\n```\n\nThen go back to step 2. You are not done until the bot reviews the new\nSHA and all present layers pass.\n\n## CI failure classification\n\nUse `gh` commands to inspect failed runs before deciding to rerun:\n\n```bash\ngh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha\ngh run view <run-id> --log-failed\n```\n\n**Branch-related** (fix the code):\n- Compile/lint/typecheck failures in files you touched\n- Deterministic test failures in changed areas\n- Snapshot or static-analysis violations from your changes\n- Build config changes causing deterministic failures\n\n**Flaky / unrelated** (rerun the jobs):\n- Network/DNS/registry timeouts\n- Runner provisioning or startup failures\n- GitHub Actions infrastructure errors\n- Non-deterministic failures in code you didn't touch\n- Cloud/service rate limits or transient API outages\n\nIf classification is ambiguous, perform one manual diagnosis attempt (inspect\nlogs) before choosing rerun.\n\nRerun: `gh run rerun <run-id> --failed`\n\nRetry budget: at most 3 reruns per SHA. After that, treat as real.\n\nRead `references/heuristics.md` for a concise decision tree.\n\n## Review comment handling\n\nThe review polling in Step 3 surfaces feedback from trusted sources: human\nreviewers (OWNER/MEMBER/COLLABORATOR) and approved review bots (openhands,\nall-hands-bot, etc.). Ignore unrelated bot noise.\n\nReview items come from:\n- PR issue comments\n- Inline review comments\n- Review submissions (COMMENT / APPROVED / CHANGES_REQUESTED)\n\nWhen a comment is actionable and correct:\n1. Fix the code.\n2. Commit with `chore: address PR review feedback (#<n>)`.\n3. Push and continue the loop.\n4. Reply to the review thread referencing the commit SHA.\n5. Resolve the thread.\n\nWhen a comment is non-actionable, already addressed, or you disagree:\nreply briefly explaining why, then resolve the thread. Do not leave\nthreads dangling without a response.\n\nIf a review thread is already resolved in GitHub, ignore it unless new\nunresolved follow-up appears.\n\n### Replying to and resolving review threads\n\nEvery inline review comment creates a thread. After addressing a comment\n(or deciding it's non-actionable), you must:\n\n1. **Reply** to the thread so the reviewer can see how you addressed it:\n\n   ```bash\n   gh api \"repos/{owner}/{repo}/pulls/{number}/comments\" \\\n     -F \"body=Fixed — <describe what you changed>\" \\\n     -F \"in_reply_to=<comment_database_id>\"\n   ```\n\n   Use `-F` (not `-f`) for `in_reply_to` so it is sent as a number.\n\n2. **Resolve** the thread via GraphQL:\n\n   ```bash\n   gh api graphql \\\n     -f query='mutation($id: ID!) {\n       resolveReviewThread(input: { threadId: $id }) {\n         thread { isResolved }\n       }\n     }' \\\n     -f id=\"<thread_node_id>\"\n   ```\n\nTo discover unresolved threads and their IDs:\n\n```bash\ngh api graphql -f query='\nquery($owner: String!, $repo: String!, $pr: Int!) {\n  repository(owner: $owner, name: $repo) {\n    pullRequest(number: $pr) {\n      reviewThreads(last: 100) {\n        nodes {\n          id\n          isResolved\n          path\n          line\n          comments(first: 1) {\n            nodes { databaseId author { login } body }\n          }\n        }\n      }\n    }\n  }\n}' -f owner=\"{owner}\" -f repo=\"{repo}\" -F pr=\"{number}\" \\\n  --jq '.data.repository.pullRequest.reviewThreads.nodes[]\n        | select(.isResolved == false)'\n```\n\n**Rules:**\n- Reply to every thread, even nits. A brief \"Done\" or \"Kept as-is because…\" is fine.\n- Resolve threads you have addressed. Do not leave resolved-in-code threads\n  showing as unresolved in the GitHub UI.\n- Before marking the PR ready, verify zero unresolved threads remain.\n\n### Requesting re-review\n\nIf the PR is green but blocked on review approval and you've addressed all\nfeedback, you can request another look — but only when the user explicitly\nasks, or after confirming with them (avoid spamming humans):\n\n1. Leave a brief PR comment summarizing what changed:\n   ```bash\n   gh pr comment <pr> --body \"Addressed the requested changes in <sha>. Could you take another look?\"\n   ```\n   Do NOT tag humans.\n\n2. Re-request reviewers via the GitHub API:\n   ```bash\n   gh api -X POST repos/{owner}/{repo}/pulls/{number}/requested_reviewers \\\n     -f reviewers[]=<reviewer>\n   ```\n\nPrefer requesting review only once per new head SHA. If the API returns an\nerror indicating reviewers are already requested, treat it as non-fatal.\n\n## Polling cadence\n\n- CI pending or failing: every 30–60 seconds.\n- CI green, waiting for review/QA: start at 60s, back off exponentially\n  (60s → 2m → 4m → 8m → 16m → 32m), cap at 1 hour.\n- Reset to 60s whenever anything changes (new SHA, check status, review\n  comment, mergeability change).\n- If CI stops being green (new commit, rerun, regression): return to 30–60s.\n- After pushing a fix: re-poll immediately.\n- If any poll shows the PR is merged or closed: stop immediately.\n\n## Stop conditions\n\nStop **only** when:\n- All present verification layers passed on current SHA and PR is mergeable.\n- PR merged or closed (stop as soon as a poll confirms this).\n- Flaky retry budget exhausted (3 reruns per SHA).\n- Blocked on something requiring human input (infra outage, permissions,\n  ambiguity that cannot be resolved safely).\n\n**Not** a stop condition:\n- You pushed a fix. That's one iteration — keep going.\n- You addressed review comments. The bot still needs to review new code.\n- CI is green but review bot hasn't re-reviewed yet. Wait.\n- CI is still running/queued.\n- CI is green but mergeability is unknown/pending.\n- CI is green and mergeable, but waiting for possible new review comments\n  per the green-state cadence.\n- PR is green but blocked on review approval (`REVIEW_REQUIRED`); continue\n  polling and surface new review comments without asking for confirmation.\n\n## When done — mark PR ready\n\nOnce all present verification layers pass on the current SHA:\n\n1. Verify all review threads are resolved (zero unresolved remaining).\n2. Convert the draft PR to ready for review:\n\n```bash\ngh pr ready\n```\n\nOnly do this at the very end, after the loop exits successfully.\n\n## Git safety\n\n- Work only on the PR head branch.\n- No destructive git commands.\n- Do not switch branches unless necessary to recover context.\n- Check for unrelated uncommitted changes before editing. If present, ask user.\n- After every fix, commit and push, then re-poll.\n- A push is not a terminal outcome; continue the monitoring loop.\n\nCommit message defaults:\n- `fix: CI failure on PR #<n>`\n- `chore: address PR review feedback (#<n>)`\n\n## Output\n\nProvide concise progress updates during monitoring:\n\n- During long unchanged periods, avoid emitting a full update on every poll;\n  summarize only status changes plus occasional heartbeat updates.\n- Treat push confirmations, intermediate CI snapshots, and review-action\n  updates as progress updates only; do not emit the final summary unless a\n  strict stop condition is met.\n- When CI first transitions to all green for the current SHA, emit a one-time\n  celebratory update. Preferred style:\n  `🚀 CI is all green! 33/33 passed. Still watching for review.`\n\nFinal summary should include:\n- Final PR SHA\n- CI status summary\n- Mergeability / conflict status\n- Fixes pushed\n- Flaky retry cycles used\n- Review threads resolved (count)\n- Remaining unresolved failures or review comments\n\n## References\n\n- Verification stack (layers, signals, retriggering): `references/verification.md`\n- CI/review heuristics and decision tree: `references/heuristics.md`"
+		content: "# /iterate — Drive a PR to Merge-Ready\n\nIterate on a pull request until it passes all verification layers.\nYou push, poll, fix, and push again — the loop only ends when the PR is green\nor a blocker requires human help.\n\nNo scripts — you are the orchestration loop. Uses only standard `gh` CLI\ncommands that work on any GitHub repo.\n\nRequires: `gh` CLI authenticated with repo access, a PR branch.\nWindows PowerShell equivalents for Bash-only assignment, redirection, and quoting patterns in this skill are in `references/windows.md`.\n\n## Discover what the repo has\n\nNot every repo has all three verification layers. Before entering the loop,\ncheck which ones exist. Only poll layers that are actually set up.\n\n```bash\ngh workflow list --json name --jq '.[].name'\n```\n\n- **CI checks** — almost every repo has these. If `gh pr checks` returns results, CI is present.\n- **PR review bot** — look for a workflow named like \"PR Review\" or \"pr-review\" in the output above, or check for `.github/workflows/pr-review*.yml` in the repo. If it's not there, the repo doesn't have automated PR review. Skip step 3 entirely.\n- **QA bot** — look for a workflow named like \"QA\" or \"qa-changes\". If it's not there, the repo doesn't have automated QA. Skip step 4 entirely.\n\nA repo might have only CI. Or CI + review. Or all three. Your \"all passed\"\ncondition is: every *present* layer is green. Don't block waiting for layers\nthat don't exist.\n\n## The loop\n\n1. Push and ensure a draft PR exists.\n2. Poll each present verification layer.\n3. Decide: all passed? fix needed? wait?\n4. If fix needed — fix, refresh any `.pr/` artifacts affected (see below),\n   commit, push, re-request review from bots, go to 2.\n5. If waiting — sleep per polling cadence, go to 2.\n6. If all present layers passed on the *current* SHA — mark PR ready, done.\n\nIMPORTANT: pushing a fix is NOT the end. After every fix+push you MUST\nre-request review from the review bot (if present) and go back to step 2.\nThe loop only ends when the verifiers pass on your latest SHA. Addressing\nfeedback and pushing a commit is just one iteration — the bot needs to\nreview the new code too.\n\nDo not stop to ask the user whether to continue polling; continue\nautonomously until a strict stop condition is met or the user interrupts.\n\n## Step 1 — Push and ensure PR exists (as draft)\n\nCreate the PR as a draft. This prevents repo automations (merge workflows,\nartifact cleanup, auto-merge) from triggering while you're still iterating.\nYou mark it ready only after all verification layers pass.\n\n```bash\ngit push origin HEAD\ngh pr create --fill --draft 2>/dev/null || true\ngh pr view --json number,url,headRefOid,isDraft --jq '\"\\(.number) \\(.url) \\(.headRefOid) draft=\\(.isDraft)\"'\n```\n\nIf the PR already exists and is not a draft, convert it:\n\n```bash\ngh pr ready --undo\n```\n\n## Step 2 — Poll CI checks\n\n```bash\ngh pr checks --json name,state,bucket --jq '\n  { passed:  [.[] | select(.bucket==\"pass\")]  | length,\n    failed:  [.[] | select(.bucket==\"fail\")]  | length,\n    pending: [.[] | select(.bucket==\"pending\")] | length }'\n```\n\n- Zero failed, zero pending → CI green.\n- Any pending → wait and re-poll.\n- Any failed → diagnose (see \"CI failure classification\" below).\n\nTo inspect a failure:\n\n```bash\nSHA=$(gh pr view --json headRefOid --jq .headRefOid)\ngh run list --commit \"$SHA\" --status failure --json databaseId,name,conclusion \\\n  --jq '.[] | \"\\(.databaseId)\\t\\(.name)\\t\\(.conclusion)\"'\ngh run view <run-id> --log-failed\n```\n\n## Step 3 — Poll PR review (if present)\n\nSkip this step if the repo has no review bot.\n\n```bash\ngh pr view --json reviews --jq '\n  [.reviews[] | select(\n    .authorAssociation == \"OWNER\" or\n    .authorAssociation == \"MEMBER\" or\n    .authorAssociation == \"COLLABORATOR\" or\n    (.author.login | test(\"openhands|all-hands-bot\"; \"i\"))\n  )] | last | { state: .state, reviewer: .author.login, body: .body[0:300] }'\n```\n\n- `APPROVED` → review passed.\n- `CHANGES_REQUESTED` → read the body and inline comments, fix code.\n- `COMMENTED` → may have actionable suggestions; read and decide.\n- No matching review yet → bot may still be running; wait and re-poll.\n\nInline review comments (when changes requested):\n\n```bash\ngh api \"repos/{owner}/{repo}/pulls/{number}/comments\" \\\n  --jq '.[] | select(.user.login | test(\"openhands|all-hands-bot\"; \"i\"))\n        | { path: .path, line: .line, body: .body[0:200] }'\n```\n\nOn a fresh iteration, existing pending review feedback should be checked\nimmediately — not only comments that arrive after monitoring starts.\nAlready-open review comments must not be missed.\n\n## Step 4 — Poll QA report (if present)\n\nSkip this step if the repo has no QA bot.\n\nQA reports are PR issue comments with a status line like `Status: PASS`.\n\n```bash\ngh api \"repos/{owner}/{repo}/issues/{number}/comments\" --paginate \\\n  --jq '[.[] | select(\n    (.user.login | test(\"openhands|all-hands-bot\"; \"i\")) and\n    (.body | test(\"Status:\\\\s*(PASS|FAIL|PARTIAL)\"; \"i\"))\n  )] | last | { author: .user.login, body: .body[0:500], url: .html_url }'\n```\n\n- `PASS` → QA passed.\n- `FAIL` → read details, fix code.\n- `PARTIAL` → some passed, some failed; read details.\n- No QA comment yet → bot may still be running; wait and re-poll.\n\n## Step 5 — Decide and act\n\nFor each present layer, check its status. If a layer is not present in the\nrepo, treat it as passing.\n\n- All present layers green on current SHA → done.\n- CI failed → fix code, or rerun if flaky (see below).\n- Review requested changes → read comments, fix, push.\n- QA failed/partial → read report, fix, push.\n- Anything still pending → sleep per polling cadence, re-poll.\n- PR closed/merged → stop.\n\n**Priority rule:** when both review feedback and flaky CI failures are present,\nprioritize review feedback first. A new commit will retrigger CI, so avoid\nrerunning flaky checks on the old SHA when you're about to push a review fix.\n\nAfter fixing, commit, push, AND re-request review:\n\n```bash\ngit add -A\ngit commit -m \"fix: address <CI failure | review feedback | QA failure>\"\ngit push origin HEAD\n\n# Re-request review from the bot so it reviews the new SHA:\ngh pr comment --body \"Addressed feedback in $(git rev-parse --short HEAD). Ready for another look.\"\ngh api -X POST \"repos/{owner}/{repo}/pulls/{number}/requested_reviewers\" \\\n  -f 'reviewers[]=all-hands-bot'\n```\n\nThen go back to step 2. You are not done until the bot reviews the new\nSHA and all present layers pass.\n\n## CI failure classification\n\nUse `gh` commands to inspect failed runs before deciding to rerun:\n\n```bash\ngh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha\ngh run view <run-id> --log-failed\n```\n\n**Branch-related** (fix the code):\n- Compile/lint/typecheck failures in files you touched\n- Deterministic test failures in changed areas\n- Snapshot or static-analysis violations from your changes\n- Build config changes causing deterministic failures\n\n**Flaky / unrelated** (rerun the jobs):\n- Network/DNS/registry timeouts\n- Runner provisioning or startup failures\n- GitHub Actions infrastructure errors\n- Non-deterministic failures in code you didn't touch\n- Cloud/service rate limits or transient API outages\n\nIf classification is ambiguous, perform one manual diagnosis attempt (inspect\nlogs) before choosing rerun.\n\nRerun: `gh run rerun <run-id> --failed`\n\nRetry budget: at most 3 reruns per SHA. After that, treat as real.\n\nRead `references/heuristics.md` for a concise decision tree.\n\n## Review comment handling\n\nThe review polling in Step 3 surfaces feedback from trusted sources: human\nreviewers (OWNER/MEMBER/COLLABORATOR) and approved review bots (openhands,\nall-hands-bot, etc.). Ignore unrelated bot noise.\n\nReview items come from:\n- PR issue comments\n- Inline review comments\n- Review submissions (COMMENT / APPROVED / CHANGES_REQUESTED)\n\nWhen a comment is actionable and correct:\n1. Fix the code.\n2. Commit with `chore: address PR review feedback (#<n>)`.\n3. Push and continue the loop.\n4. Reply to the review thread referencing the commit SHA.\n5. Resolve the thread.\n\nWhen a comment is non-actionable, already addressed, or you disagree:\nreply briefly explaining why, then resolve the thread. Do not leave\nthreads dangling without a response.\n\nIf a review thread is already resolved in GitHub, ignore it unless new\nunresolved follow-up appears.\n\n### Replying to and resolving review threads\n\nEvery inline review comment creates a thread. After addressing a comment\n(or deciding it's non-actionable), you must:\n\n1. **Reply** to the thread so the reviewer can see how you addressed it:\n\n   ```bash\n   gh api \"repos/{owner}/{repo}/pulls/{number}/comments\" \\\n     -F \"body=Fixed — <describe what you changed>\" \\\n     -F \"in_reply_to=<comment_database_id>\"\n   ```\n\n   Use `-F` (not `-f`) for `in_reply_to` so it is sent as a number.\n\n2. **Resolve** the thread via GraphQL:\n\n   ```bash\n   gh api graphql \\\n     -f query='mutation($id: ID!) {\n       resolveReviewThread(input: { threadId: $id }) {\n         thread { isResolved }\n       }\n     }' \\\n     -f id=\"<thread_node_id>\"\n   ```\n\nTo discover unresolved threads and their IDs:\n\n```bash\ngh api graphql -f query='\nquery($owner: String!, $repo: String!, $pr: Int!) {\n  repository(owner: $owner, name: $repo) {\n    pullRequest(number: $pr) {\n      reviewThreads(last: 100) {\n        nodes {\n          id\n          isResolved\n          path\n          line\n          comments(first: 1) {\n            nodes { databaseId author { login } body }\n          }\n        }\n      }\n    }\n  }\n}' -f owner=\"{owner}\" -f repo=\"{repo}\" -F pr=\"{number}\" \\\n  --jq '.data.repository.pullRequest.reviewThreads.nodes[]\n        | select(.isResolved == false)'\n```\n\n**Rules:**\n- Reply to every thread, even nits. A brief \"Done\" or \"Kept as-is because…\" is fine.\n- Resolve threads you have addressed. Do not leave resolved-in-code threads\n  showing as unresolved in the GitHub UI.\n- Before marking the PR ready, verify zero unresolved threads remain.\n\n### Requesting re-review\n\nIf the PR is green but blocked on review approval and you've addressed all\nfeedback, you can request another look — but only when the user explicitly\nasks, or after confirming with them (avoid spamming humans):\n\n1. Leave a brief PR comment summarizing what changed:\n   ```bash\n   gh pr comment <pr> --body \"Addressed the requested changes in <sha>. Could you take another look?\"\n   ```\n   Do NOT tag humans.\n\n2. Re-request reviewers via the GitHub API:\n   ```bash\n   gh api -X POST repos/{owner}/{repo}/pulls/{number}/requested_reviewers \\\n     -f reviewers[]=<reviewer>\n   ```\n\nPrefer requesting review only once per new head SHA. If the API returns an\nerror indicating reviewers are already requested, treat it as non-fatal.\n\n## Polling cadence\n\n- CI pending or failing: every 30–60 seconds.\n- CI green, waiting for review/QA: start at 60s, back off exponentially\n  (60s → 2m → 4m → 8m → 16m → 32m), cap at 1 hour.\n- Reset to 60s whenever anything changes (new SHA, check status, review\n  comment, mergeability change).\n- If CI stops being green (new commit, rerun, regression): return to 30–60s.\n- After pushing a fix: re-poll immediately.\n- If any poll shows the PR is merged or closed: stop immediately.\n\n## Stop conditions\n\nStop **only** when:\n- All present verification layers passed on current SHA and PR is mergeable.\n- PR merged or closed (stop as soon as a poll confirms this).\n- Flaky retry budget exhausted (3 reruns per SHA).\n- Blocked on something requiring human input (infra outage, permissions,\n  ambiguity that cannot be resolved safely).\n\n**Not** a stop condition:\n- You pushed a fix. That's one iteration — keep going.\n- You addressed review comments. The bot still needs to review new code.\n- CI is green but review bot hasn't re-reviewed yet. Wait.\n- CI is still running/queued.\n- CI is green but mergeability is unknown/pending.\n- CI is green and mergeable, but waiting for possible new review comments\n  per the green-state cadence.\n- PR is green but blocked on review approval (`REVIEW_REQUIRED`); continue\n  polling and surface new review comments without asking for confirmation.\n\n## Keep `.pr/` artifacts fresh\n\nBy convention, a PR may carry generated artifacts (diagrams, reports, generated\ndocs, fixtures) in a `.pr/` folder. These are derived from the code, so they go\nstale when you push fixes.\n\nAfter each fix — and before marking the PR ready — check `.pr/`:\n\n1. If there's no `.pr/` folder or it's empty, skip this entirely.\n2. For each artifact, work out how it was generated (a script, a documented\n   command, a comment in the file, or the PR/commit history).\n3. If you can figure out how — and the code it derives from changed — regenerate\n   it and commit the update, so the artifact matches the latest code.\n4. If you can't tell how it was generated, leave it alone. Don't guess.\n\nThe rule is simple: if you know how an artifact was made and the code moved on,\nkeep it up to date; otherwise don't touch it.\n\n## When done — mark PR ready\n\nOnce all present verification layers pass on the current SHA:\n\n1. Verify all review threads are resolved (zero unresolved remaining).\n2. Ensure `.pr/` artifacts are up to date with the latest code (see above).\n3. Convert the draft PR to ready for review:\n\n```bash\ngh pr ready\n```\n\nOnly do this at the very end, after the loop exits successfully.\n\n## Git safety\n\n- Work only on the PR head branch.\n- No destructive git commands.\n- Do not switch branches unless necessary to recover context.\n- Check for unrelated uncommitted changes before editing. If present, ask user.\n- After every fix, commit and push, then re-poll.\n- A push is not a terminal outcome; continue the monitoring loop.\n\nCommit message defaults:\n- `fix: CI failure on PR #<n>`\n- `chore: address PR review feedback (#<n>)`\n\n## Output\n\nProvide concise progress updates during monitoring:\n\n- During long unchanged periods, avoid emitting a full update on every poll;\n  summarize only status changes plus occasional heartbeat updates.\n- Treat push confirmations, intermediate CI snapshots, and review-action\n  updates as progress updates only; do not emit the final summary unless a\n  strict stop condition is met.\n- When CI first transitions to all green for the current SHA, emit a one-time\n  celebratory update. Preferred style:\n  `🚀 CI is all green! 33/33 passed. Still watching for review.`\n\nFinal summary should include:\n- Final PR SHA\n- CI status summary\n- Mergeability / conflict status\n- Fixes pushed\n- Flaky retry cycles used\n- Review threads resolved (count)\n- Remaining unresolved failures or review comments\n\n## References\n\n- Verification stack (layers, signals, retriggering): `references/verification.md`\n- CI/review heuristics and decision tree: `references/heuristics.md`"
 	},
 	{
 		name: "jira-issue-to-pr",
@@ -427,6 +427,12 @@ var e = [
 		],
 		content: "# Swift Installation Guide for Debian Linux\n\nThis document provides instructions for installing Swift on Debian 12 (Bookworm).\n\n> This setup is intended for non-UI development tasks on Swift on Linux.\n> On Windows, run these Debian commands inside WSL2 or a Linux container. For native Windows Swift, use the Windows toolchain from Swift.org instead.\n\n## Prerequisites\n\nBefore installing Swift, you need to install the required dependencies for your system. You can find the most up-to-date list of dependencies for your specific Linux distribution and version at the [Swift.org tarball installation guide](https://www.swift.org/install/linux/tarball/).\n\nFOR EXAMPLE, the dependencies you may need to install for Debian 12 could be:\n\n```bash\nsudo apt-get update\nsudo apt-get install -y \\\n  binutils-gold \\\n  gcc \\\n  git \\\n  libcurl4-openssl-dev \\\n  libedit-dev \\\n  libicu-dev \\\n  libncurses-dev \\\n  libpython3-dev \\\n  libsqlite3-dev \\\n  libxml2-dev \\\n  pkg-config \\\n  tzdata \\\n  uuid-dev\n```\n\n## Download and Install Swift\n\n1. Find the latest Swift version for Debian:\n\n   Go to the [Swift.org download page](https://www.swift.org/download/) to find the latest Swift version compatible with Debian 12 (Bookworm).\n\n   Look for a tarball named something like `swift-<VERSION>-RELEASE-debian12.tar.gz` (e.g., `swift-6.0.3-RELEASE-debian12.tar.gz`).\n\n   The URL pattern is typically:\n   ```\n   https://download.swift.org/swift-<VERSION>-release/debian12/swift-<VERSION>-RELEASE/swift-<VERSION>-RELEASE-debian12.tar.gz\n   ```\n\n   Where `<VERSION>` is the Swift version number (e.g., `6.0.3`).\n\n2. Download the Swift binary for Debian 12:\n\n```bash\ncd /workspace\nwget https://download.swift.org/swift-6.0.3-release/debian12/swift-6.0.3-RELEASE/swift-6.0.3-RELEASE-debian12.tar.gz\n```\n\n3. Extract the archive:\n\n> **Note**: Make sure to install Swift in the `/workspace` directory, but outside the git repository to avoid committing the Swift binaries.\n\n4. Add Swift to your PATH by adding the following line to your `~/.bashrc` file:\n\n```bash\necho 'export PATH=/workspace/swift-6.0.3-RELEASE-debian12/usr/bin:$PATH' >> ~/.bashrc\nsource ~/.bashrc\n```\n\n> **Note**: Make sure to update the version number in the PATH to match the version you downloaded.\n\n## Verify Installation\n\nVerify that Swift is correctly installed by running:\n\n```bash\nswift --version\n```"
 	},
+	{
+		name: "technical-writing",
+		description: "Guides technical explanations toward flowing, direct, conversational prose. This skill should be used for engineering chat, design discussion, architecture analysis, code-review explanations, and technical recommendations that should be concise without becoming fragmented or vague.",
+		triggers: [],
+		content: "# Technical Writing\n\nWrite the way a sharp senior engineer speaks in chat: direct, conversational, and confident. Favor flowing technical prose over report language, slide-deck fragments, or documentation boilerplate.\n\nFollow the user's requested format when they explicitly ask for formal documentation, a report, or slides. Otherwise, apply these rules to technical explanations, design feedback, architecture discussion, issue and pull-request replies, and recommendations.\n\n## Lead with the answer\n\nOpen with the verdict and its central caveat in one or two plain sentences. Do not use a bold heading as a substitute for the answer.\n\nMatch the length to the question and err short:\n\n- A yes/no or confirmation question usually needs 2 to 4 sentences.\n- A choice between alternatives usually needs a few paragraphs.\n- A genuinely multi-part design question may need a longer structured answer.\n\nBefore sending, remove any paragraph that does not change what the reader understands, decides, or does next. Cut unrequested background, restatements of the problem, and generic advice the reader already knows.\n\n## Complete the argument\n\nEvery paragraph and every bullet should carry a complete argument: claim, mechanism, and consequence together. Do not leave the reader to infer why a fact matters.\n\nWeak:\n\n> MoR increases scan cost, latency, and metadata overhead.\n\nBetter:\n\n> MoR is cheap to write, but every read has to reconcile delete files against data files, so scans get slower and less reliable until something compacts them - and now that compaction is part of the system you operate.\n\n## Match the form to the content\n\nVary the structure because different kinds of content need different forms:\n\n- Use short bold headings on their own line for distinct sections or comparison axes, such as cost versus operations.\n- Use a numbered list for a genuine sequence, diagnostic procedure, or ranked set of hypotheses. Start each item with a short bold lead and continue in full sentences.\n- Use plain bullets for parallel, enumerable facts.\n- Use paragraphs for reasoning, causality, and narrative.\n\nShortening does not mean flattening a useful structure into uniform paragraphs. Keep the structure and cut low-value sentences within it.\n\n## Keep connected reasoning together\n\nDo not shred connected reasoning into bullets. If the ideas connect with \"because,\" \"so,\" or \"but,\" those connections are the explanation and belong in prose.\n\nNever write a bold label followed by a clipped noun phrase as if it were a complete bullet.\n\n## Sound conversational, not dramatic\n\nUse contractions when they fit. Prefer \"so\" and \"but\" to \"therefore\" and \"however.\"\n\nState the claim directly. Avoid scaffolding such as:\n\n- \"It is worth noting\"\n- \"Importantly\"\n- \"The deciding mechanism is\"\n\nAvoid theatrical labels and hype adjectives. Explain the concrete cost instead of calling something \"the poison,\" \"the trap,\" \"brutally expensive,\" or \"the killer feature.\"\n\nLet sentences breathe. Do not create drama with a sequence of short, staccato sentences.\n\nDo not use setup phrases that delay the point, including:\n\n- \"here's the thing\"\n- \"here's the kicker\"\n- \"the part nobody warns you about\"\n- \"what nobody tells you\"\n- \"the dirty secret\"\n- \"the truth is\"\n- \"plot twist\"\n- \"the reality is\"\n- \"here's what's wild\"\n\nDo not use contrastive \"not just X, but Y\" constructions. State the full point directly instead of negating a weaker framing first.\n\n## Cut without compressing\n\nShortness comes from removing low-value content, not from clipping sentences. Keep articles, verbs, and the words needed to express the mechanism clearly. Replace strings of abstract nouns with a concrete actor and action.\n\n## End only when a conclusion helps\n\nAdd a bottom line only when the answer weighs a real decision. State the recommendation and the condition that would change it in one plain sentence.\n\nShort factual and confirmation answers should simply end.\n\n## Final pass\n\nBefore sending, check:\n\n1. Does the first sentence give the answer?\n2. Is the central caveat next to the answer?\n3. Does every paragraph or bullet explain why its claim matters?\n4. Does the structure match the content?\n5. Did connected reasoning stay in prose?\n6. Can any paragraph be removed without changing the reader's next step?\n7. Did any dramatic setup, clipped phrasing, or fake contrast survive?\n8. Is a bottom line present only when the reader has a real decision to make?\n\n## Source\n\nAdapted from the public [Writing style](https://prose.ami.rip/STYLE.md) agent instructions at prose.ami.rip."
+	},
 	{
 		name: "theme-factory",
 		description: "Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.",