docs: replace retired gitcrawl gh workflow examples

[steipete]

Related workflow guidance: steipete/agent-scripts@01ae83e

Additional instructions

Keep Allow edits from maintainers enabled. This branch is in the upstream repository and is available for maintainer updates.

What Problem This Solves

Resolves a problem where agents following the bundled Gitcrawl skill invoke retired gitcrawl gh pr status/view/checks commands and receive an exit-2 migration error. The public documentation already describes the move to Octopool, but the skill still advertised the former readiness, auto-hydration, cache controls, and JSON field names. Routine workflow examples also blurred first-time Octopool setup with an already-working installation.

Why This Change Was Made

Keep one clear ownership boundary: Gitcrawl supplies local archive discovery and explicit archive hydration; the existing Octopool-backed bare PATH gh supplies supported cached GitHub metadata reads and forwards authorized writes. Exact candidates use gitcrawl threads --numbers --include-closed --json before current metadata is checked through native gh JSON fields.

The skill and relevant migration/maintainer documentation remove obsolete recipes, distinguish existing setups from first-time setup, and state that the retired-command error is not an authentication failure. No runtime, authentication, token, PATH, configuration, dependency, or release changes are included.

User Impact

Agents can inspect an archived issue or PR without invoking the removed compatibility cache, then verify current GitHub state without bypassing or reconfiguring the existing shim. PR refs use headRefName/headRefOid; checks use bucket/link. Local archive state remains explicitly distinct from current GitHub state.

Evidence

• Before: installed Gitcrawl 0.9.3 rejects gitcrawl gh pr view 132182 -R openclaw/openclaw --json number,title,state,url,headSha with exit 2 and gitcrawl gh moved to octopool. The same failure was reported with 0.9.2.
• After: the archive command and bare PATH gh commands below succeed. For the catalog-lifetime cancellation fix, the archive still reports open while the GitHub metadata reports merged, demonstrating why the final metadata check matters. Octopool confirms the metadata read uses its shared cache.
• node scripts/build-docs-site.mjs passes, including internal-link validation.
• git diff --check passes. The canonical skill link resolves to this repository; an audit of its shell examples finds no retired gitcrawl gh commands.
• Fresh Codex autoreview passed with no accepted/actionable findings. Exact-head CI passed on e1aa9c97e104c4cd88408dd801965caa175709ce, including Linux/macOS Go gates, coverage, builds, smoke checks, and snapshot builds. Docker, CodeQL, and secret-scan checks also passed; the optional code-smith check was intentionally skipped.
• Pre-merge state: ready, mergeable, and clean. ClawSweeper found no code or security defects and requested captured terminal evidence. The configured-installation captures below address that proof request and its rank-up move. Source and reviewed head are unchanged; no CI rerun or code repair was needed.
• Documentation only: three Markdown files, +60 / -29 lines; production and test code deltas are both zero.

Captured terminal evidence — 2026-08-29

These commands ran against the configured installation after the documentation patch. Every command exited 0. The jq projections omit unrelated archive content and check URLs; the gh commands use the existing PATH shim, without authentication, token, PATH, or configuration changes.

gitcrawl --version

0.9.3

gitcrawl threads openclaw/openclaw --numbers 132182 --include-closed --json | jq '{repository,threads:[.threads[]|{number,title,state,updated_at}]}'

{
  "repository": "openclaw/openclaw",
  "threads": [
    {
      "number": 132182,
      "title": "fix(code-mode): cancel resumed cells when their catalog closes",
      "state": "open",
      "updated_at": "2026-08-29T04:25:32.18947Z"
    }
  ]
}

gh pr view 132182 -R openclaw/openclaw --json number,title,state,url,isDraft,headRefName,headRefOid

{"headRefName":"steipete/code-mode-catalog-lifetime-b4970f","headRefOid":"65ce5c1d903b301332ad35ac5bacb87b2d45b79a","isDraft":false,"number":132182,"state":"MERGED","title":"fix(code-mode): cancel resumed cells when their catalog closes","url":"https://github.com/openclaw/openclaw/pull/132182"}

gh pr checks 132182 -R openclaw/openclaw --json name,state,bucket,link | jq '{checkCount:length,returnedFields:(.[0]|keys)}'

{
  "checkCount": 256,
  "returnedFields": [
    "bucket",
    "link",
    "name",
    "state"
  ]
}

The archive still says open; the configured GitHub metadata read says MERGED for the same PR. This directly demonstrates the documented archive-first discovery → current metadata handoff rather than treating archive state as merge-time truth.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 29, 2026, 5:34 PM ET / 21:34 UTC.

ClawSweeper review

What this changes

The PR updates Gitcrawl’s bundled skill and public docs to replace retired gitcrawl gh examples with local archive reads followed by the Octopool-backed gh workflow.

Merge readiness

⛔ Blocked until real behavior proof is added - 3 items remain

Keep this PR open: its documentation changes align with the current Gitcrawl command boundary, but it needs captured after-fix terminal evidence for the external contributor proof gate before merge.

Priority: P3
Reviewed head: e1aa9c97e104c4cd88408dd801965caa175709ce

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The documentation patch is coherent and source-aligned, but required real workflow evidence is not captured.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The changed guidance directs operators from local gitcrawl threads data to configured gh metadata. The PR body describes successful runs but provides neither captured terminal output nor a linked artifact recording the after-fix archive-versus-live result. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The changed guidance directs operators from local gitcrawl threads data to configured gh metadata. The PR body describes successful runs but provides neither captured terminal output nor a linked artifact recording the after-fix archive-versus-live result. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	6 items	Retired command behavior: Current main routes gitcrawl gh to a migration handler that prints the Octopool notice and returns a usage error; this supports removing the obsolete skill recipes. Replacement archive command: The current threads command accepts --include-closed, --numbers, and --json, opens the local runtime read-only, and filters the requested archive rows. Released stale guidance: Release v0.9.3’s bundled skill still contains the retired gitcrawl gh pr status, view, and checks examples that this branch replaces.
Findings	None	None.
Security	None	None.

How this fits together

Gitcrawl keeps a local archive of GitHub threads for search and triage; maintainers then use a configured GitHub CLI path to verify current metadata before acting. The changed documentation guides that handoff from local archive rows to fresh pull-request data.

flowchart LR
  A[Local GitHub archive] --> B[Gitcrawl thread lookup]
  B --> C[Archive state]
  C --> D[Octopool-backed gh]
  D --> E[Fresh GitHub metadata]
  E --> F[Maintainer action]

Loading

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The changed guidance directs operators from local gitcrawl threads data to configured gh metadata. The PR body describes successful runs but provides neither captured terminal output nor a linked artifact recording the after-fix archive-versus-live result. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Resolve merge risk (P1) - Without captured after-fix terminal output, the archive-to-live-metadata workflow described by the new guidance remains unverified in a configured installation.
• Complete next step (P2) - This open PR has no mechanical repair finding; contributor-supplied real workflow proof is the remaining merge gate.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation delta	3 Markdown files; +60 / -29; production +0, tests +0	The patch is confined to operator guidance and does not alter the Gitcrawl runtime.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Keep the local-archive-first documentation and add a redacted terminal trace showing the exact replacement commands returning the distinct archive and live metadata results.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Keep the local-archive-first documentation and add a redacted terminal trace showing the exact replacement commands returning the distinct archive and live metadata results.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: the retired command’s handler emits the migration error, while threads accepts the documented archive flags. The local installed gitcrawl binary and GitHub network access were unavailable, so this review did not execute the commands.

Is this the best way to solve the issue?

Yes. The replacement archive lookup and native gh field names match the checked-in command contract; captured after-fix output is still needed to substantiate the configured workflow.

AGENTS.md: found, but no applicable review policy affected this item.

Codex review notes: model internal, reasoning high; reviewed against a339673de8b5.

Labels

Label changes:

• add P3: This is a bounded documentation workflow correction with no runtime or user-data change.
• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed guidance directs operators from local gitcrawl threads data to configured gh metadata. The PR body describes successful runs but provides neither captured terminal output nor a linked artifact recording the after-fix archive-versus-live result. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Label justifications:

• P3: This is a bounded documentation workflow correction with no runtime or user-data change.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The changed guidance directs operators from local gitcrawl threads data to configured gh metadata. The PR body describes successful runs but provides neither captured terminal output nor a linked artifact recording the after-fix archive-versus-live result. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Retired command behavior: Current main routes gitcrawl gh to a migration handler that prints the Octopool notice and returns a usage error; this supports removing the obsolete skill recipes. (internal/cli/gh_migrated.go:11, a339673de8b5)
• Replacement archive command: The current threads command accepts --include-closed, --numbers, and --json, opens the local runtime read-only, and filters the requested archive rows. (internal/cli/app.go:2528, a339673de8b5)
• Released stale guidance: Release v0.9.3’s bundled skill still contains the retired gitcrawl gh pr status, view, and checks examples that this branch replaces. (.agents/skills/gitcrawl/SKILL.md:80, 47232a77749f)
• Introduced documentation scope: The verified PR delta changes only the bundled Markdown skill, gh migration guide, and maintainer archive guide; the new guidance explicitly distinguishes existing and first-time Octopool setup. (docs/gh-shim.md:15, e1aa9c97e104)
• Proof gap: The PR body asserts that the replacement commands succeeded, but supplies command text and narrative rather than captured post-change terminal output or a linked runtime artifact. (e1aa9c97e104)
• Feature-history routing: History identifies the original Gitcrawl-to-Octopool migration as commit a45f16c and the archive-workflow documentation as merged commit e7ea843. (docs/maintainer-archive.md:91, a45f16c5ac01)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• TurboTheTurtle: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add redacted terminal output or a terminal screenshot for the documented gitcrawl threads and gh pr view commands; after updating the PR body, request @clawsweeper re-review if a new review does not start automatically.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.