@olegkoval/agent-skills 1.19.0 → 1.20.0

package/packages/marketing/viral-launch/adapters/cursor/skills/viral-launch/references/launch-checklist.md

@@ -0,0 +1,42 @@
+# Launch checklist
+
+Use this checklist before calling a project launch-ready.
+
+## Repo
+
+- README headline says what the project does and for whom.
+- First screen contains a demo, screenshot, or quickstart.
+- Install steps work from a clean checkout.
+- Examples cover the highest-intent use cases.
+- License and contribution expectations are clear.
+- Known limitations are stated without weakening the launch angle.
+
+## Message
+
+- One-sentence positioning is specific.
+- The hook names a real problem or desire.
+- Differentiation is concrete.
+- Claims are backed by repo content, screenshots, demos, benchmarks, or examples.
+- Copy avoids fake urgency, fake social proof, and generic hype.
+
+## Distribution
+
+- Launch channels are chosen for the actual audience.
+- Each channel gets native copy, not pasted generic copy.
+- Assets include at least one short post, one longer post, and one direct outreach note.
+- Launch timing includes a response window for comments, issues, and feedback.
+
+## Shareability
+
+- There is a public artifact people can link to.
+- The demo shows a before/after or clear transformation.
+- Users have a reason to share the output, not only the product.
+- Any referral or waitlist mechanism is tied to user value.
+
+## Metrics
+
+- Activation event is defined.
+- Share event is defined.
+- Conversion event is defined.
+- Feedback collection path is defined.
+- Launch review date is defined before launch.

package/packages/marketing/viral-launch/adapters/grok/skills/viral-launch/references/external-skills.md

@@ -0,0 +1,12 @@
+# External skills
+
+Skill search found these related launch and marketing skills:
+
+- `coreyhaines31/marketingskills@launch-strategy` - broad launch strategy skill, about 37K installs in Skills CLI search; source repo `coreyhaines31/marketingskills` has about 20K GitHub stars.
+- `refoundai/lenny-skills@launch-marketing` - product management and launch marketing skill, under 1K installs in Skills CLI search.
+
+Prefer this local `olko:viral-launch` skill when the work is specifically to make a repository launch-ready. Consider installing `coreyhaines31/marketingskills@launch-strategy` when the user wants a broader marketing strategy workflow:
+
+```bash
+npx skills add coreyhaines31/marketingskills@launch-strategy -g -y
+```

package/packages/marketing/viral-launch/adapters/grok/skills/viral-launch/references/launch-checklist.md

@@ -0,0 +1,42 @@
+# Launch checklist
+
+Use this checklist before calling a project launch-ready.
+
+## Repo
+
+- README headline says what the project does and for whom.
+- First screen contains a demo, screenshot, or quickstart.
+- Install steps work from a clean checkout.
+- Examples cover the highest-intent use cases.
+- License and contribution expectations are clear.
+- Known limitations are stated without weakening the launch angle.
+
+## Message
+
+- One-sentence positioning is specific.
+- The hook names a real problem or desire.
+- Differentiation is concrete.
+- Claims are backed by repo content, screenshots, demos, benchmarks, or examples.
+- Copy avoids fake urgency, fake social proof, and generic hype.
+
+## Distribution
+
+- Launch channels are chosen for the actual audience.
+- Each channel gets native copy, not pasted generic copy.
+- Assets include at least one short post, one longer post, and one direct outreach note.
+- Launch timing includes a response window for comments, issues, and feedback.
+
+## Shareability
+
+- There is a public artifact people can link to.
+- The demo shows a before/after or clear transformation.
+- Users have a reason to share the output, not only the product.
+- Any referral or waitlist mechanism is tied to user value.
+
+## Metrics
+
+- Activation event is defined.
+- Share event is defined.
+- Conversion event is defined.
+- Feedback collection path is defined.
+- Launch review date is defined before launch.

package/packages/software-development/qodoloop/SKILL.md

@@ -42,7 +42,19 @@ Qodo has **no check run to poll** — there is nothing in `gh pr checks` to wait
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working
+tree** (`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean — refusing to start, would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging
+only the files a fix touched is safe *because* the tree started clean, so
+nothing else could be sitting in those files. Skip this check and a file
+with pre-existing local edits will have those edits swept into the fix
+commit right along with it — the exact failure `git add -A` had, just
+narrower.
 
 ### 2. Loop (max 5 iterations)
 

package/packages/software-development/qodoloop/adapters/claude/skills/qodoloop/SKILL.md

@@ -43,7 +43,19 @@ Qodo has **no check run to poll** — there is nothing in `gh pr checks` to wait
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working
+tree** (`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean — refusing to start, would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging
+only the files a fix touched is safe *because* the tree started clean, so
+nothing else could be sitting in those files. Skip this check and a file
+with pre-existing local edits will have those edits swept into the fix
+commit right along with it — the exact failure `git add -A` had, just
+narrower.
 
 ### 2. Loop (max 5 iterations)
 

package/packages/software-development/qodoloop/adapters/claude/skills/qodoloop/references/graphql-queries.md

@@ -0,0 +1,151 @@
+# GraphQL queries reference
+
+Field names verified by introspection against GitHub's live GraphQL schema
+(`AddPullRequestReviewThreadReplyInput`) and against a real Qodo install's
+comment output — not guessed.
+
+**The bot's login string is spelled differently in REST vs GraphQL.** REST
+(`.user.login` on `issues/.../comments`) returns `qodo-code-review[bot]`.
+GraphQL (`author.login` on `reviewThreads`) returns `qodo-code-review` — no
+`[bot]` suffix — confirmed live against a real PR with real Qodo inline
+threads. Using the REST spelling in a GraphQL filter silently matches
+nothing, which reads as "no findings" instead of "wrong filter" — exactly the
+kind of bug that has no crash and no error to notice. Use `[bot]` only in
+REST-based jq filters (`.user.login`); use the bare name everywhere you're
+filtering a GraphQL `author.login`.
+
+## Fetch unresolved Qodo threads (paginated)
+
+```graphql
+query($cursor: String) {
+  repository(owner: "OWNER", name: "REPO") {
+    pullRequest(number: PR_NUMBER) {
+      reviewThreads(first: 100, after: $cursor) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          isResolved
+          comments(first: 1) {
+            nodes { body path line author { login } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Filter client-side to `qodo-code-review` (GraphQL spelling — see the note
+above) and `isResolved == false` — the author isn't filterable server-side in
+this shape. **Follow `pageInfo.hasNextPage`/`endCursor` until it's exhausted**;
+stopping after the first page silently drops every thread past the 100th on a
+PR with a lot of findings:
+
+A page fetch can occasionally come back malformed (a transient API hiccup,
+not anything specific to this query — reproduced live, then failed to
+reproduce on an identical immediate retry). Retry once per page before
+giving up rather than letting the whole loop crash on it:
+
+```bash
+CURSOR=null
+ALL_THREADS='[]'
+while :; do
+  for attempt in 1 2; do
+    PAGE=$(gh api graphql -f query='
+      query($cursor: String) {
+        repository(owner: "OWNER", name: "REPO") {
+          pullRequest(number: PR_NUMBER) {
+            reviewThreads(first: 100, after: $cursor) {
+              pageInfo { hasNextPage endCursor }
+              nodes {
+                id
+                isResolved
+                comments(first: 1) { nodes { body path line author { login } } }
+              }
+            }
+          }
+        }
+      }' -f cursor="$CURSOR")
+    jq -e . >/dev/null 2>&1 <<< "$PAGE" && break
+    [ "$attempt" = "2" ] && { echo "page fetch failed twice, aborting" >&2; exit 1; }
+  done
+
+  ALL_THREADS=$(jq -c --argjson acc "$ALL_THREADS" \
+    '$acc + .data.repository.pullRequest.reviewThreads.nodes' <<< "$PAGE")
+
+  HAS_NEXT=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage' <<< "$PAGE")
+  [ "$HAS_NEXT" = "true" ] || break
+  CURSOR=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor' <<< "$PAGE")
+done
+
+echo "$ALL_THREADS" | jq \
+  '.[] | select(.comments.nodes[0].author.login == "qodo-code-review") | select(.isResolved == false)'
+```
+
+## Parsing a thread's finding out of `comments.nodes[0].body`
+
+The body is markdown with embedded HTML. Extract:
+- **Title + severity**: first line has a badge image; `alt="Remediation recommended"` = actionable, `alt="Informational"` = optional. The finding title/tags follow on the next line (e.g. `3\. pickclaimroaster branch untested <code>📘 Rule violation</code> ...`).
+- **Agent Prompt**: the fenced ```` ```...``` ```` block under a `<summary>` reading either `Agent Prompt` or `Agent prompt` (Qodo's casing differs between the inline-comment surface and the rollup issue-comment surface — match case-insensitively). This block is the whole fix spec: issue description, context, fix focus files/lines, and often a suggested fix. Use it verbatim as the task.
+
+If a thread somehow has no Agent Prompt block (seen only on the rollup's
+lower-severity "Optional" entries in some cases), fall back to the finding's
+plain-text description above the badge.
+
+## Reply to a thread
+
+```bash
+gh api graphql -f query='
+  mutation($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $threadId, body: $body}) {
+      comment { id }
+    }
+  }' -f threadId="$THREAD_ID" -f body="$REPLY_TEXT"
+```
+
+Pass the thread id and reply text as GraphQL **variables** (`-f`), never
+interpolated straight into the query string. A reply containing a quote,
+backtick, or embedded newline breaks — or, worse, injects into — a
+hand-built query string; `gh api graphql -f` handles the escaping correctly
+when the value travels as a variable instead.
+
+`pullRequestReviewThreadId` and `body` are the only required input fields
+(`pullRequestReviewId` and `clientMutationId` are optional — omit them).
+
+## Resolve a thread (batch)
+
+```graphql
+mutation {
+  t1: resolveReviewThread(input: {threadId: "ID1"}) { thread { isResolved } }
+  t2: resolveReviewThread(input: {threadId: "ID2"}) { thread { isResolved } }
+}
+```
+
+Only resolve a thread whose fix is already pushed and confirmed durable on
+the branch (SKILL.md §2E-F) — resolving first and pushing second means a
+failed push leaves GitHub showing the finding as handled when it isn't. Never
+resolve a blocked/skipped finding at all; reply to it and leave it open.
+
+## Fetch the rollup issue comment (context only, not the source of truth)
+
+Useful for the human-readable summary counts (bugs/rule-violations) in your
+final report, or as a fallback if `reviewThreads` ever comes back empty for a
+PR that clearly has a completed review. Select the latest by `created_at`.
+Whether Qodo edits this comment in place across passes or posts a new one
+each time is **unconfirmed** — every PR checked had exactly one, untouched
+since creation, which doesn't distinguish the two. Sort by `created_at` and
+take the last one either way; it's correct under both behaviors:
+
+```bash
+gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments?per_page=100" \
+  | jq -s 'add
+    | map(select(.user.login == "qodo-code-review[bot]"))
+    | map(select(.body | startswith("<h3>Code Review by Qodo</h3>")))
+    | sort_by(.created_at)
+    | last'
+```
+
+A rate-limit/paused comment reads `<h3>Qodo is busy working</h3>` while
+in-flight, or contains "Qodo reviews are paused" / "review limit" when
+terminally blocked — check for that text before assuming a missing review
+comment just means "still running".

package/packages/software-development/qodoloop/adapters/cursor/skills/qodoloop/SKILL.md

@@ -44,7 +44,19 @@ Qodo has **no check run to poll** — there is nothing in `gh pr checks` to wait
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working
+tree** (`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean — refusing to start, would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging
+only the files a fix touched is safe *because* the tree started clean, so
+nothing else could be sitting in those files. Skip this check and a file
+with pre-existing local edits will have those edits swept into the fix
+commit right along with it — the exact failure `git add -A` had, just
+narrower.
 
 ### 2. Loop (max 5 iterations)
 

package/packages/software-development/qodoloop/adapters/cursor/skills/qodoloop/references/graphql-queries.md

@@ -0,0 +1,151 @@
+# GraphQL queries reference
+
+Field names verified by introspection against GitHub's live GraphQL schema
+(`AddPullRequestReviewThreadReplyInput`) and against a real Qodo install's
+comment output — not guessed.
+
+**The bot's login string is spelled differently in REST vs GraphQL.** REST
+(`.user.login` on `issues/.../comments`) returns `qodo-code-review[bot]`.
+GraphQL (`author.login` on `reviewThreads`) returns `qodo-code-review` — no
+`[bot]` suffix — confirmed live against a real PR with real Qodo inline
+threads. Using the REST spelling in a GraphQL filter silently matches
+nothing, which reads as "no findings" instead of "wrong filter" — exactly the
+kind of bug that has no crash and no error to notice. Use `[bot]` only in
+REST-based jq filters (`.user.login`); use the bare name everywhere you're
+filtering a GraphQL `author.login`.
+
+## Fetch unresolved Qodo threads (paginated)
+
+```graphql
+query($cursor: String) {
+  repository(owner: "OWNER", name: "REPO") {
+    pullRequest(number: PR_NUMBER) {
+      reviewThreads(first: 100, after: $cursor) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          isResolved
+          comments(first: 1) {
+            nodes { body path line author { login } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Filter client-side to `qodo-code-review` (GraphQL spelling — see the note
+above) and `isResolved == false` — the author isn't filterable server-side in
+this shape. **Follow `pageInfo.hasNextPage`/`endCursor` until it's exhausted**;
+stopping after the first page silently drops every thread past the 100th on a
+PR with a lot of findings:
+
+A page fetch can occasionally come back malformed (a transient API hiccup,
+not anything specific to this query — reproduced live, then failed to
+reproduce on an identical immediate retry). Retry once per page before
+giving up rather than letting the whole loop crash on it:
+
+```bash
+CURSOR=null
+ALL_THREADS='[]'
+while :; do
+  for attempt in 1 2; do
+    PAGE=$(gh api graphql -f query='
+      query($cursor: String) {
+        repository(owner: "OWNER", name: "REPO") {
+          pullRequest(number: PR_NUMBER) {
+            reviewThreads(first: 100, after: $cursor) {
+              pageInfo { hasNextPage endCursor }
+              nodes {
+                id
+                isResolved
+                comments(first: 1) { nodes { body path line author { login } } }
+              }
+            }
+          }
+        }
+      }' -f cursor="$CURSOR")
+    jq -e . >/dev/null 2>&1 <<< "$PAGE" && break
+    [ "$attempt" = "2" ] && { echo "page fetch failed twice, aborting" >&2; exit 1; }
+  done
+
+  ALL_THREADS=$(jq -c --argjson acc "$ALL_THREADS" \
+    '$acc + .data.repository.pullRequest.reviewThreads.nodes' <<< "$PAGE")
+
+  HAS_NEXT=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage' <<< "$PAGE")
+  [ "$HAS_NEXT" = "true" ] || break
+  CURSOR=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor' <<< "$PAGE")
+done
+
+echo "$ALL_THREADS" | jq \
+  '.[] | select(.comments.nodes[0].author.login == "qodo-code-review") | select(.isResolved == false)'
+```
+
+## Parsing a thread's finding out of `comments.nodes[0].body`
+
+The body is markdown with embedded HTML. Extract:
+- **Title + severity**: first line has a badge image; `alt="Remediation recommended"` = actionable, `alt="Informational"` = optional. The finding title/tags follow on the next line (e.g. `3\. pickclaimroaster branch untested <code>📘 Rule violation</code> ...`).
+- **Agent Prompt**: the fenced ```` ```...``` ```` block under a `<summary>` reading either `Agent Prompt` or `Agent prompt` (Qodo's casing differs between the inline-comment surface and the rollup issue-comment surface — match case-insensitively). This block is the whole fix spec: issue description, context, fix focus files/lines, and often a suggested fix. Use it verbatim as the task.
+
+If a thread somehow has no Agent Prompt block (seen only on the rollup's
+lower-severity "Optional" entries in some cases), fall back to the finding's
+plain-text description above the badge.
+
+## Reply to a thread
+
+```bash
+gh api graphql -f query='
+  mutation($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $threadId, body: $body}) {
+      comment { id }
+    }
+  }' -f threadId="$THREAD_ID" -f body="$REPLY_TEXT"
+```
+
+Pass the thread id and reply text as GraphQL **variables** (`-f`), never
+interpolated straight into the query string. A reply containing a quote,
+backtick, or embedded newline breaks — or, worse, injects into — a
+hand-built query string; `gh api graphql -f` handles the escaping correctly
+when the value travels as a variable instead.
+
+`pullRequestReviewThreadId` and `body` are the only required input fields
+(`pullRequestReviewId` and `clientMutationId` are optional — omit them).
+
+## Resolve a thread (batch)
+
+```graphql
+mutation {
+  t1: resolveReviewThread(input: {threadId: "ID1"}) { thread { isResolved } }
+  t2: resolveReviewThread(input: {threadId: "ID2"}) { thread { isResolved } }
+}
+```
+
+Only resolve a thread whose fix is already pushed and confirmed durable on
+the branch (SKILL.md §2E-F) — resolving first and pushing second means a
+failed push leaves GitHub showing the finding as handled when it isn't. Never
+resolve a blocked/skipped finding at all; reply to it and leave it open.
+
+## Fetch the rollup issue comment (context only, not the source of truth)
+
+Useful for the human-readable summary counts (bugs/rule-violations) in your
+final report, or as a fallback if `reviewThreads` ever comes back empty for a
+PR that clearly has a completed review. Select the latest by `created_at`.
+Whether Qodo edits this comment in place across passes or posts a new one
+each time is **unconfirmed** — every PR checked had exactly one, untouched
+since creation, which doesn't distinguish the two. Sort by `created_at` and
+take the last one either way; it's correct under both behaviors:
+
+```bash
+gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments?per_page=100" \
+  | jq -s 'add
+    | map(select(.user.login == "qodo-code-review[bot]"))
+    | map(select(.body | startswith("<h3>Code Review by Qodo</h3>")))
+    | sort_by(.created_at)
+    | last'
+```
+
+A rate-limit/paused comment reads `<h3>Qodo is busy working</h3>` while
+in-flight, or contains "Qodo reviews are paused" / "review limit" when
+terminally blocked — check for that text before assuming a missing review
+comment just means "still running".

package/packages/software-development/qodoloop/adapters/grok/skills/qodoloop/SKILL.md

@@ -43,7 +43,19 @@ Qodo has **no check run to poll** — there is nothing in `gh pr checks` to wait
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working
+tree** (`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean — refusing to start, would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging
+only the files a fix touched is safe *because* the tree started clean, so
+nothing else could be sitting in those files. Skip this check and a file
+with pre-existing local edits will have those edits swept into the fix
+commit right along with it — the exact failure `git add -A` had, just
+narrower.
 
 ### 2. Loop (max 5 iterations)
 

package/packages/software-development/qodoloop/adapters/grok/skills/qodoloop/references/graphql-queries.md

@@ -0,0 +1,151 @@
+# GraphQL queries reference
+
+Field names verified by introspection against GitHub's live GraphQL schema
+(`AddPullRequestReviewThreadReplyInput`) and against a real Qodo install's
+comment output — not guessed.
+
+**The bot's login string is spelled differently in REST vs GraphQL.** REST
+(`.user.login` on `issues/.../comments`) returns `qodo-code-review[bot]`.
+GraphQL (`author.login` on `reviewThreads`) returns `qodo-code-review` — no
+`[bot]` suffix — confirmed live against a real PR with real Qodo inline
+threads. Using the REST spelling in a GraphQL filter silently matches
+nothing, which reads as "no findings" instead of "wrong filter" — exactly the
+kind of bug that has no crash and no error to notice. Use `[bot]` only in
+REST-based jq filters (`.user.login`); use the bare name everywhere you're
+filtering a GraphQL `author.login`.
+
+## Fetch unresolved Qodo threads (paginated)
+
+```graphql
+query($cursor: String) {
+  repository(owner: "OWNER", name: "REPO") {
+    pullRequest(number: PR_NUMBER) {
+      reviewThreads(first: 100, after: $cursor) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          isResolved
+          comments(first: 1) {
+            nodes { body path line author { login } }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Filter client-side to `qodo-code-review` (GraphQL spelling — see the note
+above) and `isResolved == false` — the author isn't filterable server-side in
+this shape. **Follow `pageInfo.hasNextPage`/`endCursor` until it's exhausted**;
+stopping after the first page silently drops every thread past the 100th on a
+PR with a lot of findings:
+
+A page fetch can occasionally come back malformed (a transient API hiccup,
+not anything specific to this query — reproduced live, then failed to
+reproduce on an identical immediate retry). Retry once per page before
+giving up rather than letting the whole loop crash on it:
+
+```bash
+CURSOR=null
+ALL_THREADS='[]'
+while :; do
+  for attempt in 1 2; do
+    PAGE=$(gh api graphql -f query='
+      query($cursor: String) {
+        repository(owner: "OWNER", name: "REPO") {
+          pullRequest(number: PR_NUMBER) {
+            reviewThreads(first: 100, after: $cursor) {
+              pageInfo { hasNextPage endCursor }
+              nodes {
+                id
+                isResolved
+                comments(first: 1) { nodes { body path line author { login } } }
+              }
+            }
+          }
+        }
+      }' -f cursor="$CURSOR")
+    jq -e . >/dev/null 2>&1 <<< "$PAGE" && break
+    [ "$attempt" = "2" ] && { echo "page fetch failed twice, aborting" >&2; exit 1; }
+  done
+
+  ALL_THREADS=$(jq -c --argjson acc "$ALL_THREADS" \
+    '$acc + .data.repository.pullRequest.reviewThreads.nodes' <<< "$PAGE")
+
+  HAS_NEXT=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.hasNextPage' <<< "$PAGE")
+  [ "$HAS_NEXT" = "true" ] || break
+  CURSOR=$(jq -r '.data.repository.pullRequest.reviewThreads.pageInfo.endCursor' <<< "$PAGE")
+done
+
+echo "$ALL_THREADS" | jq \
+  '.[] | select(.comments.nodes[0].author.login == "qodo-code-review") | select(.isResolved == false)'
+```
+
+## Parsing a thread's finding out of `comments.nodes[0].body`
+
+The body is markdown with embedded HTML. Extract:
+- **Title + severity**: first line has a badge image; `alt="Remediation recommended"` = actionable, `alt="Informational"` = optional. The finding title/tags follow on the next line (e.g. `3\. pickclaimroaster branch untested <code>📘 Rule violation</code> ...`).
+- **Agent Prompt**: the fenced ```` ```...``` ```` block under a `<summary>` reading either `Agent Prompt` or `Agent prompt` (Qodo's casing differs between the inline-comment surface and the rollup issue-comment surface — match case-insensitively). This block is the whole fix spec: issue description, context, fix focus files/lines, and often a suggested fix. Use it verbatim as the task.
+
+If a thread somehow has no Agent Prompt block (seen only on the rollup's
+lower-severity "Optional" entries in some cases), fall back to the finding's
+plain-text description above the badge.
+
+## Reply to a thread
+
+```bash
+gh api graphql -f query='
+  mutation($threadId: ID!, $body: String!) {
+    addPullRequestReviewThreadReply(input: {pullRequestReviewThreadId: $threadId, body: $body}) {
+      comment { id }
+    }
+  }' -f threadId="$THREAD_ID" -f body="$REPLY_TEXT"
+```
+
+Pass the thread id and reply text as GraphQL **variables** (`-f`), never
+interpolated straight into the query string. A reply containing a quote,
+backtick, or embedded newline breaks — or, worse, injects into — a
+hand-built query string; `gh api graphql -f` handles the escaping correctly
+when the value travels as a variable instead.
+
+`pullRequestReviewThreadId` and `body` are the only required input fields
+(`pullRequestReviewId` and `clientMutationId` are optional — omit them).
+
+## Resolve a thread (batch)
+
+```graphql
+mutation {
+  t1: resolveReviewThread(input: {threadId: "ID1"}) { thread { isResolved } }
+  t2: resolveReviewThread(input: {threadId: "ID2"}) { thread { isResolved } }
+}
+```
+
+Only resolve a thread whose fix is already pushed and confirmed durable on
+the branch (SKILL.md §2E-F) — resolving first and pushing second means a
+failed push leaves GitHub showing the finding as handled when it isn't. Never
+resolve a blocked/skipped finding at all; reply to it and leave it open.
+
+## Fetch the rollup issue comment (context only, not the source of truth)
+
+Useful for the human-readable summary counts (bugs/rule-violations) in your
+final report, or as a fallback if `reviewThreads` ever comes back empty for a
+PR that clearly has a completed review. Select the latest by `created_at`.
+Whether Qodo edits this comment in place across passes or posts a new one
+each time is **unconfirmed** — every PR checked had exactly one, untouched
+since creation, which doesn't distinguish the two. Sort by `created_at` and
+take the last one either way; it's correct under both behaviors:
+
+```bash
+gh api --paginate "repos/{owner}/{repo}/issues/<PR_NUMBER>/comments?per_page=100" \
+  | jq -s 'add
+    | map(select(.user.login == "qodo-code-review[bot]"))
+    | map(select(.body | startswith("<h3>Code Review by Qodo</h3>")))
+    | sort_by(.created_at)
+    | last'
+```
+
+A rate-limit/paused comment reads `<h3>Qodo is busy working</h3>` while
+in-flight, or contains "Qodo reviews are paused" / "review limit" when
+terminally blocked — check for that text before assuming a missing review
+comment just means "still running".

package/packages/software-development/qodoloop/adapters/kiro/steering/qodoloop.md

@@ -35,7 +35,19 @@ Qodo has **no check run to poll** — there is nothing in `gh pr checks` to wait
 gh pr view --json number,headRefName,headRefOid -q '{number, branch: .headRefName, sha: .headRefOid}'
 ```
 
-Check out the branch if not already on it.
+Check out the branch if not already on it, **then require a clean working
+tree** (`git status --porcelain` empty) before touching anything:
+
+```bash
+[ -z "$(git status --porcelain)" ] || { echo "working tree not clean — refusing to start, would risk committing unrelated changes"; exit 1; }
+```
+
+This is the precondition step E's scoped `git add <file>` depends on: staging
+only the files a fix touched is safe *because* the tree started clean, so
+nothing else could be sitting in those files. Skip this check and a file
+with pre-existing local edits will have those edits swept into the fix
+commit right along with it — the exact failure `git add -A` had, just
+narrower.
 
 ### 2. Loop (max 5 iterations)