Build automated root-cause cluster coordination for related issues and PRs

[brokemac79]

Summary

ClawSweeper should grow from reviewing one issue at a time into an automated root-cause coordinator for related OpenClaw issues and PRs.

The desired behavior is not just "mention a few related links". ClawSweeper should detect when several reports are symptoms of the same underlying bug, build a durable cluster, choose the safest canonical fix lane, keep the affected issues and PRs aligned, and prevent fragmented one-off fixes from racing each other.

The existing ClawSweeper architecture already points in this direction:

• docs/related-issue-discovery.md already gathers related issue/PR context, but only as advisory prompt evidence.
• docs/repair/README.md already describes the better operating model: one cluster, one job, one branch, one PR, deterministic writes, live-state checks, contributor credit, and gated close/merge actions.
• instructions/dedupe.md already has the right classification vocabulary: canonical, duplicate, related, superseded, fixed_by_candidate, independent, and needs_human.
• gitcrawl/gitcrawl-store already provide a stronger source of issue/PR cluster context than ad hoc title search alone.

This feature should connect those pieces into one automated cluster-coordination flow.

Example

Recent example: openclaw/openclaw#90891.

That issue reports that openclaw doctor does not surface official managed plugin version drift after a core upgrade. Around the same upgrade/plugin-diagnostics neighborhood, related items already existed:

• [Bug]: Upgrade leaves repeated shared SQLite plugin install metadata conflict warnings for codex/discord openclaw#90418: repeated shared SQLite plugin install metadata conflict warnings for codex / discord
• fix(state): retire superseded plugin install index openclaw#90474: PR fixing one state-migration shape for #90418
• fix(doctor): archive conflicting plugin install index openclaw#90267: earlier PR for a related plugin install index archival/conflict shape
• memory-lancedb 2026.6.1 fails to install: apache-arrow 21.1.0 conflicts with @lancedb/lancedb 0.30.0 peer range openclaw#90295: another upgrade/plugin install failure, adjacent but probably not the same exact root cause

Those items are not all exact duplicates. That is the point. Some are likely same-family or same-root-cause candidates; some are existing partial fixes; some are adjacent but distinct. A maintainer needs ClawSweeper to separate those buckets and coordinate the right fix lane.

The ideal outcome is that ClawSweeper says, effectively:

• these items are in the same root-cause family
• this PR is the best current fix lane, or no good fix lane exists yet
• broaden or replace that lane rather than creating another narrow PR
• do not queue duplicate automated repair work for the same cluster
• after the canonical fix lands and current main is verified, close or update the covered issues/PRs with precise evidence

Problem

Open source projects often receive several reports for one underlying defect. Reporters describe different symptoms, on different machines, at different times. Contributors may then open several narrow PRs before anyone notices the root cause is shared.

That creates avoidable project drag:

• multiple issue threads compete for the same underlying fix
• several PRs patch individual symptoms instead of one root cause
• maintainers must manually discover which item should become canonical
• ClawSweeper can queue or recommend work per issue even when a better shared fix lane exists
• narrower PRs can remain active after a broader fix has superseded them
• already-fixed issues may stay open because the merged fix did not explicitly close every related report

ClawSweeper is the right place to solve this because it already reads issue reports, PRs, linked refs, ClawSweeper reports, gitcrawl context, live GitHub state, and current main state.

Target behavior

ClawSweeper should maintain a root-cause cluster model for every reviewed issue or PR.

A cluster is a durable family of related GitHub items that may share a fix path. It should not be based on title similarity alone. It should be based on evidence from issue bodies, comments, labels, file paths, linked PRs, merged PRs, ClawSweeper reports, gitcrawl clusters, reproduction evidence, changed files, and current-main checks.

For each reviewed item, ClawSweeper should:

1. Discover candidate related issues and PRs from explicit links, GitHub Search, existing ClawSweeper reports, gitcrawl-store, recently merged PRs, and open PRs touching likely files.
2. Classify each candidate as canonical, duplicate, same_root_cause, partial_overlap, adjacent_distinct, superseded, fixed_by_candidate, independent, security_route, or needs_human.
3. Persist the cluster decision in durable report/frontmatter or state output so future reviews do not rediscover the same family from scratch.
4. Pick a canonical coordination path:
   • use the best existing open PR when it is clearly the right fix lane
   • update/repair a writable contributor PR when safe and credited
   • create or update one clawsweeper/<cluster-id> repair PR when no suitable PR exists
   • replace an uneditable/stale/unsafe source PR while preserving contributor credit
   • route to needs_human when the canonical lane is a real maintainer/product/security decision
5. Suppress duplicate repair queueing for non-canonical cluster members.
6. Update ClawSweeper review comments on affected items with the canonical cluster path and why it was chosen.
7. Re-check cluster members when the canonical PR changes, merges, closes, or becomes stale.
8. After a canonical fix lands, verify covered issues against current main and apply safe close/supersede/fixed-by-candidate actions through the existing deterministic applicator.

End-to-end flow

flowchart TD
    A["Issue or PR enters ClawSweeper review"] --> B["Collect related issue, PR, report, gitcrawl, and current-main context"]
    B --> C["Build or refresh durable root-cause cluster"]
    C --> D{"Cluster relationship is clear?"}
    D -->|"No"| E["Keep item independent or route to needs_human with evidence"]
    D -->|"Yes"| F["Choose canonical coordination path"]
    F --> G{"Best existing PR can own fix?"}
    G -->|"Yes, writable or repairable"| H["Adopt, update, or broaden existing PR with credit"]
    G -->|"No suitable PR"| I["Create or update one clawsweeper cluster repair PR"]
    G -->|"Unclear ownership or policy"| J["Route canonical choice to needs_human"]
    H --> K["Mark sibling issues and PRs as covered, duplicate, related, or superseded in durable state"]
    I --> K
    J --> K
    K --> L["Block duplicate repair jobs for non-canonical members"]
    L --> M["Watch canonical PR and current main"]
    M --> N{"Canonical fix landed and covered items verify on main?"}
    N -->|"Yes"| O["Apply safe close, supersede, or fixed-by-candidate outcomes"]
    N -->|"No"| P["Keep cluster open and update blockers"]

Loading

Canonical fix lane selection

ClawSweeper should choose exactly one active implementation lane per cluster unless the cluster is deliberately split.

Preferred order:

1. A maintainer-authored or maintainer-approved PR that already covers the root cause.
2. A contributor PR that is clearly closest to the root cause and can be safely updated or repaired.
3. A ClawSweeper replacement PR when the useful source PR is uneditable, stale, unsafe, draft-only, or too narrow but still deserves credit.
4. A new ClawSweeper cluster PR when no existing PR can carry the fix.
5. needs_human only when product direction, security handling, ownership, or canonical-choice evidence is genuinely ambiguous.

This should reuse the existing repair-lane principles:

• one cluster maps to one job file
• one implementation path maps to one branch
• one branch produces or updates one PR
• Codex does not get GitHub write credentials
• deterministic scripts own GitHub writes
• close and merge decisions re-fetch live state before mutation
• contributor credit is preserved when work is replaced or broadened

Public ClawSweeper comment shape

When a cluster exists, ClawSweeper should include a compact coordination section in the public review comment.

Example:

### Root-cause cluster

ClawSweeper found a likely shared root-cause family.

Canonical fix lane: #12402
Reason: #12402 touches the shared plugin install metadata path and already covers the failure mode reported in #12345 and #12380.

Cluster members:
- #12345: same root cause, covered by canonical lane
- #12380: same root cause, covered by canonical lane
- #12402: canonical fix PR
- #12440: adjacent upgrade/plugin issue, keep separate

Routing:
- do not queue a separate repair PR for #12345 or #12380
- broaden #12402 if additional coverage is needed
- after #12402 lands, re-check #12345 and #12380 on main before closing

The comment should be short. The durable report can contain lower-confidence candidates and detailed scoring.

Durable state

Each reviewed item should expose enough structured state for downstream automation and dashboards, for example:

root_cause_cluster:
  id: openclaw-openclaw-plugin-upgrade-drift-2026-06
  confidence: high
  canonical_ref: openclaw/openclaw#12402
  relationship: same_root_cause
  covered_by:
    - openclaw/openclaw#12402
  sibling_refs:
    - openclaw/openclaw#12345
    - openclaw/openclaw#12380
  adjacent_refs:
    - openclaw/openclaw#12440
  action: use_canonical_fix_lane
  duplicate_repair_blocked: true

The exact schema can differ, but the important part is that cluster decisions become machine-readable. Comments should explain; durable state should coordinate.

Automated actions

When confidence and gates allow, ClawSweeper should automatically:

• create or update the durable cluster record
• attach reviewed items to the cluster
• choose the canonical fix lane
• avoid creating duplicate repair jobs for non-canonical members
• create or update the one cluster repair job/branch/PR when no better PR exists
• broaden a ClawSweeper-owned PR to cover newly discovered sibling issues
• repair a writable adopted PR when safe and credited
• replace an uneditable source PR with a credited ClawSweeper PR when that is the safest canonical path
• update comments on sibling issues/PRs with the canonical path
• close duplicate/superseded/fixed-by-candidate issues only after live verification on current main
• close or supersede narrower PRs only when a broader replacement exists or a canonical fix has landed, with contributor credit preserved

Merge should still obey the existing ClawSweeper merge gates. This proposal is not asking to weaken merge safety. It is asking ClawSweeper to coordinate the repair lane automatically instead of treating each issue as a separate universe.

Safety rules

Automation must be strong, but it must not be sloppy.

Hard rules:

• Never close from title similarity alone.
• Never merge without the existing exact-head review, CI, mergeability, and merge-gate requirements.
• Never close security-sensitive reports as ordinary duplicates; route them through the security boundary.
• Never treat adjacent-but-distinct reports as duplicates just because labels or product area match.
• Never discard contributor work; carry credit into replacement PRs and explain the supersede path.
• Never let older stale cluster state override fresh live GitHub state.
• Never create a second ClawSweeper PR for a cluster that already has an active canonical ClawSweeper branch.
• Use needs_human for genuine product/security/canonical-choice ambiguity, not as a default escape hatch for ordinary evidence-based coordination.

Acceptance criteria

• Related issue discovery is upgraded from prompt-only context into a durable root-cause cluster coordinator.
• ClawSweeper can classify related items as canonical, same-root-cause, duplicate, partial-overlap, adjacent-distinct, superseded, fixed-by-candidate, independent, security-route, or needs-human.
• A reviewed issue with a high-confidence cluster gets one canonical coordination path rather than independent per-issue repair recommendations.
• Non-canonical cluster members do not queue duplicate ClawSweeper repair PRs.
• Existing suitable PRs are preferred over new ClawSweeper PRs when they can safely carry the fix.
• ClawSweeper can create or update one cluster PR when no suitable PR exists.
• Newly discovered sibling issues can broaden the canonical ClawSweeper PR instead of creating more PRs.
• Covered issues are rechecked against current main before any close/fixed-by-candidate action.
• Superseded PR handling preserves contributor credit and only happens after a safe canonical path exists.
• Durable state and public comments both show the canonical cluster path.
• Existing safety gates for write actions, merge, security handling, and live-state checks remain intact.

Why this is the right direction

The best maintainer behavior is not only "fix this issue". It is "notice this is one underlying problem, pick one good fix lane, keep everyone coordinated, and close the loop once the root cause is actually fixed".

ClawSweeper already has most of the building blocks: related discovery, gitcrawl context, cluster repair jobs, deterministic applicators, replacement PR credit, live-state checks, and post-merge closeout. This enhancement makes those pieces work together as a real maintainer coordinator.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 6, 2026, 9:32 AM ET / 13:32 UTC.

Summary
Keep this open: current main has useful building blocks, but it does not yet connect single-item reviews, durable cluster state, canonical fix-lane selection, duplicate repair suppression, sibling comment updates, and post-merge verified cleanup into the automated root-cause coordinator requested here.

Reproducibility: not applicable. this is a feature and coordination request, not a report of broken existing behavior. The relevant check is source/docs inspection of current related discovery and repair-cluster lanes.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
Maintainers should first decide the cluster schema, public comment threshold, and how single-item reviews hand off to the existing repair-cluster lane.

Review details

Best possible solution:

Define a maintainer-approved cluster schema and policy that lets single-item reviews promote clear related families into the existing repair-cluster lane while suppressing duplicate repair jobs and keeping close/merge gates deterministic.

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

Not applicable: this is a feature and coordination request, not a report of broken existing behavior. The relevant check is source/docs inspection of current related discovery and repair-cluster lanes.

Is this the best way to solve the issue?

Unclear until maintainers approve the product boundary. The narrowest maintainable path is to extend existing related discovery and repair-cluster state instead of creating a competing coordination lane.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• There is no VISION.md in the checkout, so roadmap fit cannot be confirmed from repository vision text.
• The exact durable schema, public-comment noise threshold, and canonical-lane policy need maintainer approval before automation should coordinate sibling issues and PRs broadly.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 413ef258a1ef.

Label changes

Label justifications:

• P2: This is meaningful maintainer automation work, but it is not an urgent regression or runtime outage.
• impact:other: The issue affects ClawSweeper coordination quality and maintainer workload rather than a specific owned impact class such as security, data loss, or message delivery.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was read fully; its conservative, proposal-only and automation-safe guidance supports keeping this broad product request open rather than treating partial cluster tooling as a closeable implementation. (AGENTS.md:1, 413ef258a1ef)
• Related discovery is advisory: The current related-item review docs say related issue/PR context is prompt evidence only and does not itself close issues, change labels, open PRs, or merge anything. (docs/related-issue-discovery.md:3, 413ef258a1ef)
• Single-item review collects related candidates: The review path builds relatedItems from explicit mentions, local title search, optional gitcrawl rows, and optional GitHub issue search, then adds only a count/context entry for the prompt. (src/clawsweeper.ts:3971, 413ef258a1ef)
• Durable work-lane state is narrower than requested: The work-lane report state stores work_cluster_refs, likely files, and validation for manual promotion, while advisory labels explicitly do not dispatch repair, merge, or close work. (docs/work-lane.md:7, 413ef258a1ef)
• Repair lane supports curated/imported clusters: The repair README describes one-cluster cleanup for clusters already grouped by a human, gitcrawl, or another dedupe tool, with guarded fix/apply actions and a sanitized ledger. (docs/repair/README.md:35, 413ef258a1ef)
• Scheduled cluster intake exists but is gated and limited: The cluster-intake workflow is feature-flagged for schedules and imports from gitcrawl-store into autonomous repair jobs, which is a separate lane rather than per-reviewed-item root-cause coordination. (.github/workflows/repair-cluster-intake.yml:63, 413ef258a1ef)

Likely related people:

• Tak Hoffman: Git blame and history show the related-item prompt context, related discovery docs, dedupe vocabulary, and gitcrawl import script were introduced in commit 1ff140f. (role: introduced related-discovery and dedupe surfaces; confidence: high; commits: 1ff140ff45c6; files: src/clawsweeper.ts, docs/related-issue-discovery.md, instructions/dedupe.md)
• Dallin Romney: Git history shows recent work on scheduled cluster intake and dispatch behavior, including the repair README and workflow that define the current imported-cluster lane. (role: recent cluster-repair intake contributor; confidence: high; commits: 9fc28bd49593, 87e6a26e1e0a; files: .github/workflows/repair-cluster-intake.yml, docs/repair/README.md)

How this review workflow works

• 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.

[brokemac79]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

• State: Complete
• Detail: The targeted re-review finished, the durable review comment was updated, and the synced verdict was routed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/27063598273
• Updated: 2026-06-06T13:33:16.201Z