clawsweeper-issue-triage

What this skill does

```markdown
---
name: clawsweeper-issue-triage
description: ClawSweeper is a conservative GitHub maintainer bot that scans all open issues and PRs, writes per-item markdown review records, and closes only when evidence meets strict criteria.
triggers:
  - set up clawsweeper for my repo
  - automate issue triage with clawsweeper
  - how do I run clawsweeper locally
  - configure clawsweeper to close stale issues
  - apply clawsweeper closures to my repository
  - review open PRs with clawsweeper
  - clawsweeper dashboard not updating
  - how does clawsweeper decide what to close
---

# ClawSweeper Issue Triage Bot

> Skill by [ara.so](https://ara.so) — Daily 2026 Skills collection.

ClawSweeper is a conservative AI-powered GitHub maintainer bot that reviews every open issue and PR in a target repository, writes a regenerated markdown record per item, and closes only when evidence is strong. It runs on a weekly cadence per item and uses Codex (`gpt-5.5`) to evaluate each item against a strict set of allowed close reasons.

## What ClawSweeper Does

- Scans all open issues and PRs in a target repo (e.g. `openclaw/openclaw`)
- Writes one markdown file per item under `items/<number>.md`
- Proposes closes only for items that match allowed reasons
- Actually closes items only when `apply_closures=true` is explicitly set
- Archives closed item records to `closed/<number>.md`
- Updates a live dashboard in the README after each run
- Never auto-closes items authored by `OWNER`, `MEMBER`, or `COLLABORATOR`

### Allowed Close Reasons

1. Already implemented on `main`
2. Cannot reproduce on current `main`
3. Belongs on a plugin/skill hub, not in core
4. Too incoherent to be actionable
5. Stale issue older than 60 days with insufficient data to verify the bug

## Installation

Requires **Node 24**.

```bash
git clone https://github.com/openclaw/clawsweeper.git
cd clawsweeper
npm install
npm run build
```

Set required environment variables:

```bash
export GITHUB_TOKEN=$GITHUB_TOKEN          # read access to target repo
export OPENAI_API_KEY=$OPENAI_API_KEY      # Codex access
export CLAWSWEEPER_REPO="owner/repo"       # target repo to scan
```

## Key CLI Commands

### Plan a sweep

Scans open items and produces shard batches for review jobs.

```bash
npm run plan -- \
  --batch-size 5 \
  --shard-count 40 \
  --max-pages 250 \
  --codex-model gpt-5.5 \
  --codex-reasoning-effort medium \
  --codex-service-tier fast
```

### Review items

Runs Codex on each planned item inside a local checkout of the target repo.

```bash
npm run review -- \
  --openclaw-dir ../openclaw \
  --batch-size 5 \
  --max-pages 250 \
  --artifact-dir artifacts/reviews \
  --codex-model gpt-5.5 \
  --codex-reasoning-effort medium \
  --codex-service-tier fast \
  --codex-timeout-ms 600000
```

### Apply review artifacts to the repo

Merges shard artifacts and updates dashboard. Does **not** close anything yet.

```bash
npm run apply-artifacts -- --artifact-dir artifacts/reviews
```

### Apply existing proposals (close issues/PRs)

Re-fetches issue context, recomputes snapshot hash, and closes if nothing changed since the proposal.

```bash
npm run apply-decisions -- --limit 20
```

Options:

| Flag | Default | Description |
|---|---|---|
| `--limit` | unlimited | Max fresh closes in this run |
| `--apply-kind` | `issue` | `issue`, `pr`, or `all` |
| `--apply-min-age-days` | `0` | Minimum age of proposal before applying |
| `--close-delay-ms` | `5000` | Delay between close API calls |

### Reconcile items folder

Moves externally closed items from `items/` to `closed/` and reopened items back to `items/` as stale.

```bash
npm run reconcile -- --dry-run   # preview only
npm run reconcile               # apply changes
```

## GitHub Actions Workflow

ClawSweeper is designed to run as a scheduled GitHub Actions workflow on the clawsweeper repo itself. Key workflow inputs:

```yaml
# Trigger a manual run with apply enabled
workflow_dispatch:
  inputs:
    apply_closures:
      description: "Set to true to actually close issues/PRs"
      default: "false"
    apply_existing:
      description: "Apply existing proposals without re-running Codex"
      default: "false"
    apply_kind:
      description: "issue | pr | all"
      default: "issue"
    apply_min_age_days:
      description: "Min age in days for a proposal to be applied"
      default: "0"
```

The normal scheduled run is **proposal-only** — it never comments or closes without explicit `apply_closures=true`.

## Item Record Format

Each item is stored as `items/<number>.md`. Example structure:

```markdown
# Issue #58150

**Title:** [Bug]: RISC-V64: OpenClaw fails with LLM request failed

**Outcome:** keep_open

**Reason:** Bug is reproducible and not fixed on main. Insufficient evidence
to close as cannot-reproduce.

**Snapshot hash:** abc123def456

**Reviewed:** Apr 25, 2026, 16:55 UTC

**Proposed close comment:** N/A
```

When outcome is `proposed_close`, the record includes the exact comment that will be posted before closing.

## Review Cadence

| Item type | Cadence |
|---|---|
| All PRs | Daily |
| Issues < 30 days old | Daily |
| Issues ≥ 30 days old with no recent activity | Weekly |
| Items with new activity since last snapshot | Daily (promoted) |

The planner prioritizes: **active items → PRs → new issues → older weekly issues** when more items are due than fit in a run.

## Configuration Reference

ClawSweeper reads configuration from environment variables and CLI flags. There is no separate config file — all settings are passed at invocation time.

| Env Var | Purpose |
|---|---|
| `GITHUB_TOKEN` | GitHub API access (read for review, write for apply) |
| `OPENAI_API_KEY` | Codex API key |
| `CLAWSWEEPER_REPO` | Target repo in `owner/repo` format |

| CLI Flag | Command | Description |
|---|---|---|
| `--batch-size` | plan, review | Items per shard batch |
| `--shard-count` | plan | Number of parallel review shards |
| `--max-pages` | plan, review | Max GitHub API pages to scan |
| `--codex-model` | plan, review | Model to use (default: `gpt-5.5`) |
| `--codex-reasoning-effort` | plan, review | `low`, `medium`, `high` |
| `--codex-service-tier` | plan, review | `default`, `fast` |
| `--codex-timeout-ms` | review | Per-item timeout (default: 600000) |
| `--artifact-dir` | review, apply-artifacts | Directory for shard output |
| `--dry-run` | reconcile | Preview without writing |
| `--apply-closures` | review | Actually close items (use carefully) |

## Code Examples

### Reading an item record programmatically

```javascript
import { readFileSync } from 'fs';
import { join } from 'path';

function loadItemRecord(itemNumber) {
  const filePath = join('items', `${itemNumber}.md`);
  const content = readFileSync(filePath, 'utf-8');
  
  const outcomeMatch = content.match(/\*\*Outcome:\*\*\s+(\S+)/);
  const snapshotMatch = content.match(/\*\*Snapshot hash:\*\*\s+(\S+)/);
  
  return {
    number: itemNumber,
    outcome: outcomeMatch?.[1] ?? 'unknown',
    snapshotHash: snapshotMatch?.[1] ?? null,
    raw: content,
  };
}

const record = loadItemRecord(58150);
console.log(record.outcome); // "keep_open" or "proposed_close"
```

### Listing all proposed closes

```javascript
import { readdirSync, readFileSync } from 'fs';
import { join } from 'path';

function getProposedCloses(itemsDir = 'items') {
  const files = readdirSync(itemsDir).filter(f => f.endsWith('.md'));
  
  return files
    .map(file => {
      const content = readFileSync(join(itemsDir, file), 'utf-8');
      const number = parseInt(file.replace('.md', ''), 10);
      const outcomeMatch = content.match(/\*\*Outcome:\*\*\s+(\S+)/);
      return { number, outcome: outcomeMatch?.[1] };
    })
    .filter(item => item.outcome === 'proposed_close')
    .map(item => item.number);
}

const toClose = getProposedCloses();
console.log(`Proposed closes: ${toClose.length}`);
console.log(toClose);
```

### Checking dashboard metrics from the README

```javascript
impor