.agents/skills/clawsweeper/SKILL.md
Use this skill for Slate issue-ledger triage and processing: issue clusters, duplicate/stale/invalid decisions, small high-confidence repro/fix candidates, PR-body issue claim sync, and execution prompts for the active Slate v2 rewrite.
This is adapted from ../openclaw/.agents and the current
../clawsweeper checkout: ClawSweeper, duplicate-tagging,
small-bugfix-sweep, gitcrawl, maintainer-triage, testing, work-lane, proof, and
security-boundary discipline. Keep the useful discipline. Drop the OpenClaw
bot/app/automerge/comment-sync/dashboard machinery.
This is one skill on purpose. Do not load or recreate these as separate Plate-local skills unless a future workflow needs a real standalone command.
gitcrawl: archive-first candidate discovery, local mirror freshness, related
closed/open thread search.tag-duplicate-prs-issues: duplicate proof bar and one-cluster discipline,
without prtags writes or GitHub comment sync.openclaw-small-bugfix-sweep: one-by-one high-certainty issue loop, skip
rules, narrow local proof.openclaw-pr-maintainer: maintainer evidence bar, no speculative closure,
no claim without repro/root-cause/fix-path proof.openclaw-testing: cheapest safe verification path for the touched surface.openclaw-test-performance: evidence-first benchmark/profiling discipline,
only for v2-performance-benchmark rows.clawsweeper-upstream: AGENTS-grounded review, work-candidate routing, real
behavior proof, security quarantine, and storm-control lessons from
../clawsweeper.When the user asks to refresh or sync this skill from ../clawsweeper, do not
process Slate issues. Refresh the upstream checkout and import only portable
review discipline:
test -d ../clawsweeper || git clone https://github.com/openclaw/clawsweeper.git ../clawsweeper
git -C ../clawsweeper pull --ff-only
sed -n '1,260p' ../clawsweeper/README.md
sed -n '1,260p' ../clawsweeper/CHANGELOG.md
sed -n '1,220p' ../clawsweeper/docs/work-lane.md
sed -n '1,240p' ../clawsweeper/docs/pr-review-comments.md
sed -n '1,220p' ../clawsweeper/docs/commit-sweeper.md
sed -n '1,220p' ../clawsweeper/docs/limits.md
sed -n '1,220p' ../clawsweeper/instructions/closure-policy.md
sed -n '1,220p' ../clawsweeper/instructions/security-boundary.md
sed -n '1,220p' ../clawsweeper/instructions/low-signal-prs.md
sed -n '1,420p' ../clawsweeper/prompts/review-item.md
Import:
Do not import:
After editing this source rule, run pnpm install and verify generated skill
sync with targeted rg plus the project completion check.
Read these first, in order:
docs/slate-issues/gitcrawl-live-open-ledger.mddocs/slate-issues/gitcrawl-v2-sync-ledger.md when it existsdocs/slate-issues/open-issues-ledger.mddocs/slate-issues/gitcrawl-clusters.mddocs/slate-v2/ledgers/fork-issue-dossier.mddocs/slate-v2/ledgers/issue-coverage-matrix.mddocs/slate-v2/references/pr-description.md.tmp/slate-v2 when a claim depends on code.The live gitcrawl ledger is generated live input only. The v2 sync ledger owns
current manual issue classifications. The frozen open issues ledger is the
682-issue historical classification seed, not current live truth. The fork
issue dossier owns long-form fork-local issue sections. The issue coverage
matrix owns exact implementation claims. The PR description must stay synced
with exact claims, counts, proof references, and non-claims.
Use the Homebrew tap install unless the user explicitly asks for a source build:
brew install openclaw/tap/gitcrawl
gitcrawl --version
gitcrawl check-update --json
gitcrawl doctor --json
gitcrawl status --json
If Homebrew reports that gitcrawl is shadowed by an older local build, fix the
PATH entry or call the brewed binary directly. The normal brewed path is:
/opt/homebrew/bin/gitcrawl
Current stable release baseline: 0.4.3. Stable control probes:
gitcrawl check-update --json
gitcrawl metadata --json
gitcrawl status --json
gitcrawl doctor --json
Use status --json for fast archive inventory and doctor --json when token,
config, DB health, model, or sync freshness matter. metadata --json is the
crawlkit control manifest for launchers/automation.
The gh shim is optional. Prefer the explicit subcommand or side-by-side
gitcrawl-gh if a workflow needs cached gh reads:
gitcrawl gh issue view <number-or-url> -R ianstormtaylor/slate --json number,title,state,url,body,labels,author
gitcrawl gh pr status <number-or-url> -R ianstormtaylor/slate --compact
ln -sf "$(command -v gitcrawl)" "$HOME/bin/gitcrawl-gh"
gitcrawl-gh issue view <number-or-url> -R ianstormtaylor/slate --json number,title,state,url,body,labels,author
Only replace global gh when the user asks. If gh is shadowed by the shim,
set GITCRAWL_GH_PATH to the real GitHub CLI path to avoid recursion.
<update> ModeWhen the argument is exactly <update>, run a ClawSweeper tooling refresh
instead of issue triage. Do not process issues, edit ledgers, or update PR
claims in this mode.
Update flow:
Update the Homebrew tap metadata and installed binary:
brew update
brew upgrade openclaw/tap/gitcrawl || brew install openclaw/tap/gitcrawl
gitcrawl --version
gitcrawl check-update --json
gitcrawl doctor --json
gitcrawl status --json
If gitcrawl is shadowed by an older local source-build symlink, either
retarget that symlink to /opt/homebrew/bin/gitcrawl when it is clearly
agent-owned, or record the shadowing caveat and call /opt/homebrew/bin/gitcrawl
directly.
Inspect the updated API surface from the installed binary:
gitcrawl --help
gitcrawl metadata --json
gitcrawl status --json
gitcrawl doctor --json
gitcrawl search issues "composition" -R ianstormtaylor/slate --state open --json number,title,state,url --limit 2
If ../gitcrawl exists, scan the fresh repo docs and skill for new command
shapes before editing this rule:
git -C ../gitcrawl pull --ff-only
sed -n '1,220p' ../gitcrawl/docs/installation.md
sed -n '1,260p' ../gitcrawl/docs/commands.md
sed -n '1,260p' ../gitcrawl/docs/gh-shim.md
sed -n '1,260p' ../gitcrawl/.agents/skills/gitcrawl/SKILL.md
sed -n '1,220p' ../gitcrawl/CHANGELOG.md
Update .agents/rules/clawsweeper.mdc for new or changed gitcrawl install,
command, JSON, sync, search, cluster, TUI, or gh-shim APIs. Also update the
stable baseline version above when the brewed version changes.
Regenerate generated agent files from the source rule:
pnpm install
Verify the source rule and generated skill are in sync:
rg -n "Current stable release baseline|check-update|metadata --json|status --json|sync --numbers|sync-if-stale|gitcrawl gh pr status|durable-clusters|gitcrawl-gh" .agents/rules/clawsweeper.mdc .agents/skills/clawsweeper/SKILL.md
pnpm lint:fix
If a new gitcrawl release documents commands that are only on main and not in
the brewed binary, record them as optional future probes instead of making the
ClawSweeper workflow depend on them. The unreleased 0.4.4 changelog is not a
workflow contract until gitcrawl check-update --json and gitcrawl --version
prove the release exists locally.
Fixes #... unless the exact original repro is proven end to end.cluster-synced means architecture pressure is absorbed. It is not a closure
claim.improves-claimed means current v2 work materially improves the issue but
does not prove exact closure.fixes-claimed means exact repro proof exists and the PR may claim it.needs-repro; do not design for
ghosts..tmp/slate-v2/AGENTS.md when it exists and follow it unless
higher-priority instructions conflict.cluster-synced states are routing aids, not proof that an issue is fixed.Use the existing bucket names exactly:
v2-input-runtimev2-dom-selectionv2-react-runtimev2-core-enginev2-clipboard-serializationv2-api-dxv2-performance-benchmarkneeds-reproskip-invalidskip-duplicateskip-staleskip-maintainer-noisedocs-examplesecosystem-boundaryalready-accountedDo not invent a new bucket unless the ledger and active plan are updated in the same turn.
When gitcrawl is available and has Slate data, use it first for candidate
discovery, duplicate attempts, related closed issues, and cluster neighbors.
Treat it as candidate generation only.
Start with local readiness and freshness:
gitcrawl status --json
gitcrawl doctor --json
Read status --json for state, last_sync_at, database path/size, and
thread/cluster counts. Read doctor --json for version, token sources, DB
health, models, repository_count, thread_count, open_thread_count, and
cluster_count. A missing GitHub token blocks sync and live shim fallthroughs;
it does not block read-only archive inspection when the local database already
has the needed rows.
Useful shapes:
gitcrawl threads ianstormtaylor/slate --numbers <issue-or-pr-ref> --include-closed --json
gitcrawl neighbors ianstormtaylor/slate --number <issue-or-pr-ref> --limit 20 --json
gitcrawl search ianstormtaylor/slate --query "<title, scope, or failure phrase>" --mode hybrid --limit 20 --json
gitcrawl search issues "<title, scope, or failure phrase>" -R ianstormtaylor/slate --state open --sync-if-stale 5m --json number,title,state,url,updatedAt,labels --limit 20
gitcrawl cluster-detail ianstormtaylor/slate --id <cluster-id> --member-limit 20 --body-chars 280 --json
gitcrawl cluster-detail ianstormtaylor/slate --id <cluster-id> --source run --member-limit 20 --body-chars 280 --json
gitcrawl durable-clusters ianstormtaylor/slate --include-closed --json
gitcrawl runs ianstormtaylor/slate --kind sync --limit 5 --json
gitcrawl sync ianstormtaylor/slate --numbers <issue-or-pr-ref> --include-comments --with pr-details --json
gitcrawl gh issue view <issue-or-pr-ref> -R ianstormtaylor/slate --json number,title,state,url,body,comments,labels,author,closedAt
gitcrawl gh pr status <pr-ref> -R ianstormtaylor/slate --compact
gitcrawl gh pr view <pr-ref> -R ianstormtaylor/slate --json number,title,state,url,isDraft,author,headRef,baseRef,files,commits,checks,statusCheckRollup
gitcrawl gh pr checks <pr-ref> -R ianstormtaylor/slate --json name,state,conclusion,detailsUrl
Use sync --numbers for exact row hydration before a duplicate, stale, or
closure decision that depends on comments, PR detail, or fresh state. Use
search issues ... --sync-if-stale <duration> for ad-hoc candidate discovery
where a bounded staleness window is enough.
Thread references can be bare numbers, #123, issues/123, pull/123,
owner/repo#123, or full GitHub issue/PR URLs. Prefer full URLs when moving
evidence between repos or docs because they carry their own scope.
gitcrawl gh pr status is the default PR triage first read. Exit 0 means
clean, 1 means action needed, 2 means cache/command error, and 3 means
checks pending. Use --live before final merge/comment decisions when liveness
matters; use --cached when measuring local cache coverage.
Local governance commands (close-thread, close-cluster,
exclude-cluster-member, include-cluster-member, set-cluster-canonical) are
allowed only for local gitcrawl maintainer state. They never close, label, or
comment on GitHub. Do not use them to hide unresolved Slate issue work unless
the ledger decision already has concrete proof.
If gitcrawl is missing, stale, or lacks Slate data, fall back to the local
ledger, docs/slate-issues/**, and targeted gh reads/searches. Treat stale
data as blocking only when the decision depends on it. Note the fallback; do not
block normal triage.
Live GitHub is final truth for current state, comments, duplicate links, and
whether a thread is still open. Use the shim first when it is installed and
fresh enough; otherwise use real gh:
gitcrawl gh issue view <number-or-url> -R ianstormtaylor/slate --json number,title,state,body,comments,labels,url,closedAt
gitcrawl gh search issues "<key phrase>" -R ianstormtaylor/slate --match title,body --limit 50 --json number,title,state,url
gitcrawl-gh issue view <number> -R ianstormtaylor/slate --json number,title,state,body,comments,labels,url,closedAt
gitcrawl-gh search issues "<key phrase>" -R ianstormtaylor/slate --match title,body --limit 50 --json number,title,state,url
gh issue view <number> --repo ianstormtaylor/slate --comments --json number,title,state,body,comments,labels,url,closedAt
gh search issues --repo ianstormtaylor/slate --match title,body --limit 50 -- "<key phrase>"
gh search issues --repo ianstormtaylor/slate --match comments --limit 50 -- "<error or maintainer phrase>"
Search broadly before deciding. Do not stop at the first related thread when a claim depends on duplicate chains, stale closures, or already-landed fixes.
Do not assume gitcrawl has an API server. The current tool is a local CLI,
SQLite archive, TUI, and optional gh shim.
Do not call something duplicate because titles look similar.
Require at least two evidence categories:
Outcomes:
skip-duplicate: strong evidence that the row duplicates another issue or
cluster already accounted for.needs-repro: similar wording but root cause or behavior is unclear.cluster-synced: duplicate family maps to a v2 architecture owner.not-claimed: duplicate/product/support context stays outside v2.If a row appears to belong to two unrelated clusters, stop and record
needs-human. Do not force a prettier taxonomy.
Use this when the user gives issue refs or asks for processable issues.
For each issue:
.tmp/slate-v2 or legacy ../slate.Qualified candidates must pass every gate:
Skip instead of patching when:
Do not pad a batch with low-confidence fixes. If no issue qualifies, say so.
Adapt upstream queue_fix_pr discipline to Slate v2 issue sweeps. This is a
classification aid, not permission to mutate GitHub.
Use focused fix path only when all are true:
Use manual review / needs-human when the item may matter but needs an API
direction, product boundary, migration policy, security handling, or maintainer
judgment before implementation. Use none for stale/unclear reports, support
noise, ecosystem work, already-covered duplicates, or anything paired with an
open fix PR.
For automatic-looking bug fixes, keep the bar stricter: exact current repro, high confidence, no new feature/config option, no product decision, narrow code owner, and focused regression proof.
Prove the touched surface first:
For .tmp/slate-v2, prefer focused package tests, focused Playwright greps, and
package typecheck before broad gates. Use bun check:full only when the issue
claim needs release-quality browser coverage.
For browser, DOM selection, IME/composition, clipboard, mobile, or visual behavior, unit tests are supplemental only. Use real behavior proof when the claim is user-visible: Playwright/browser steps, screenshots or recordings that show the changed behavior, terminal output, copied live output, linked artifacts, or redacted logs. A plain screenshot is not enough for network, CSP, auth, security, or browser-runtime claims unless the diagnostic path is visible.
For performance buckets, establish baseline before changing code. Record wall time, hot path, DOM/heap/component/listener counts, or benchmark artifact as appropriate. No "seems faster" claims.
Use upstream implemented_on_main discipline as the model for already-accounted
and triage-closed classifications:
If you cannot point to concrete code/docs/history/related-item evidence, keep
the row open as needs-repro, issue-reviewed, or needs-human.
Use this mode when the user wants OpenClaw-style issue comments adapted for the Slate v2 fork. Do not comment on upstream GitHub issues in this mode.
OpenClaw writes curation state and lets GitHub comments derive from that state. For Slate v2, the derived projection is one committed markdown dossier:
docs/slate-v2/ledgers/fork-issue-dossier.md
That file is the public-facing accounting layer for the fork. Every issue section must be self-contained enough that a maintainer can audit the claim without opening five side files.
Default compiled output targets:
docs/slate-v2/references/pr-description.md gets summarized
counts and exact claim text only.docs/slate-v2/ledgers/fork-issue-dossier.md.docs/slate-issues/gitcrawl-live-open-ledger.md.docs/slate-issues/gitcrawl-v2-sync-ledger.md.docs/slate-issues/gitcrawl-clusters.md.For each issue, write this shape:
## #<issue> <title>
Status: fixes-claimed | improves-claimed | cluster-synced | issue-reviewed | not-claimed | triage-closed | needs-repro | needs-human
Bucket: <action-bucket>
Confidence: high | medium | low
Issue summary:
<one tight paragraph>
Evidence:
- ledger row: <cluster/status/source>
- related issues: <refs or none found>
- duplicate/stale/invalid proof: <if applicable>
- live GitHub checked: yes | no, live-gitcrawl-only
- current v2 proof: <tests/files/plan refs or none>
Decision:
<why this status is correct>
PR-description text:
<exact short text to include, or "none; detailed ledger only">
Rules for compiled sections:
#6034 when auto-linking matters.Fixes #... unless the section status is fixes-claimed.cluster-synced, explain the architecture owner, not a fake closure.triage-closed, name the close class: duplicate, invalid, stale, or
maintainer-noise.needs-repro, state the missing proof plainly.not-claimed, state the boundary: docs/example, ecosystem, product,
support, release, or outside raw Slate.Use these exact claim levels in reports:
fixes-claimed: exact repro proved and fixed.improves-claimed: materially improved, no exact closure claim.cluster-synced: architecture owner covers the pressure.issue-reviewed: reviewed and routed, no fix claim.not-claimed: deliberate non-claim.triage-closed: invalid, duplicate, stale, or maintainer-noise closure path.needs-repro: no architecture/fix claim without current repro.needs-human: taxonomy, maintainer intent, or product boundary needs a human.For a single issue:
Decision: fixes-claimed | improves-claimed | cluster-synced | issue-reviewed | not-claimed | triage-closed | needs-repro | needs-human
Issue: #<n> <title>
Bucket: <action-bucket>
Confidence: high | medium | low
Evidence:
- ...
- ...
Action:
- v2 sync ledger: update needed | already synced | no change
- coverage matrix: update needed | no exact claim
- PR description: update needed | no change
- implementation: none | focused fix path
- verification: <command/proof or required repro>
For a batch:
Ledger:
- fixed-local: ...
- improves-claimed: ...
- cluster-synced: ...
- needs-repro: ...
- skipped: ...
- needs-human: ...
Next slice:
- ...
Only act on GitHub when the user explicitly asks. If asked to comment or prepare maintainer text:
\ngh issue/pr comment -b "..." for bodies with backticks or shell chars#123 in backticks when auto-linking mattersStop and ask or mark needs-human when:
Security-sensitive rows are item-scoped quarantines. Do not let one security-shaped related ref poison unrelated non-security bugs in the same cluster, but do not route the sensitive item through backlog cleanup or a normal fix claim.