---
name: revert-rca-loop
description: "Detect when an AI-authored PR is reverted and trigger a Reflection session for RCA. Monitors revert commits, matches to AI PRs, and initiates analysis. Scheduled to run hourly. Invoke with /revert-rca-loop."
user-invocable: true
---

# Revert RCA Loop

Detects and analyzes reversions of AI-authored PRs to identify patterns and prevent recurrence.

**Goal:** Close the learning loop when the autonomous system makes a mistake: capture the revert, trigger RCA, file follow-up tasks.

## Architecture

```
Periodic Check (hourly)
  → Query GitHub for recent reverts
  → Filter for AI-authored PRs (marked "Generated by @mbe/agent-core")
  → Match revert commit to original PR
  → Check if RCA issue already exists
  → If new revert: Create RCA issue + Trigger Reflection session
  → Track trend (reverts/day, patterns, root causes)
```

## Workflow

### Step 1: Detect Recent Reverts

Query the last 24 hours of commits on main for revert patterns:

```bash
# Find revert commits (last 24h)
git log --oneline --since="24 hours ago" --grep="^Revert" | head -20
```

Parse each revert commit:

- Extract original commit SHA or PR number from message: `Revert "feat: #1234 description"`
- Or: `Revert "title (#1234)"`
- Extract: `1234` (PR number)

For each potential revert:

```bash
# Get the reverted commit details
REVERT_COMMIT=$(git log -1 --format=%H --grep="^Revert" --since="24 hours ago")
ORIGINAL_COMMIT=$(git show $REVERT_COMMIT | grep -oP 'This reverts commit \K[0-9a-f]+' || echo "")

# Try to find the original PR from the commit message
PR_NUM=$(git log -1 --format=%B $REVERT_COMMIT | grep -oP '#\K[0-9]+' | head -1)
```

### Step 2: Verify PR is AI-Authored

For each potential revert:

```bash
# Check if the PR body contains "Generated by @mbe/agent-core"
gh pr view $PR_NUM --json body --jq '.body' | grep -q "Generated by @mbe/agent-core"
if [ $? -eq 0 ]; then
  echo "Revert detected: AI-authored PR #$PR_NUM was reverted"
else
  echo "Revert is not for an AI PR, skipping"
fi
```

### Step 3: Check for Existing RCA Issue

Before creating a new issue, check if an RCA was already filed:

```bash
# Query for RCA issue for this PR
EXISTING=$(gh issue list \
  --search "RCA for #$PR_NUM" \
  --state open \
  --label "revert-rca" \
  --json number \
  --jq ".[0].number")

if [ -n "$EXISTING" ]; then
  echo "RCA issue #$EXISTING already exists, skipping"
  exit 0
fi
```

### Step 4: Create RCA Issue

If no existing RCA issue, create one:

```bash
gh issue create \
  --title "RCA: PR #$PR_NUM was reverted" \
  --label "revert-rca,acmm" \
  --body "## Revert Details

| Field | Value |
|-------|-------|
| Reverted PR | #$PR_NUM |
| Revert Commit | $REVERT_COMMIT |
| Original Author | @mbe/agent-core |
| Reverted At | $(date -u +%Y-%m-%dT%H:%M:%SZ) |

## Original PR Summary

$(gh pr view $PR_NUM --json title,body --jq '"**Title:** \(.title)\n\n**Body:**\n\(.body)"')

## RCA Checklist

- [ ] Review the revert commit and reason
- [ ] Identify root cause category (logic error, incomplete testing, edge case, unsafe pattern)
- [ ] Check if this is a recurring pattern
- [ ] File follow-up task if needed (improve testing, add validation, update templates)
- [ ] Update agent-core or skill documentation if systemic issue

## Root Cause Categories

When analyzing, categorize the root cause:

- **Logic Error** — Agent misunderstood requirements or made an incorrect implementation choice
- **Incomplete Testing** — Test coverage missed an edge case or integration scenario
- **Missing Validation** — Input validation or constraint enforcement was insufficient
- **Unsafe Pattern** — Code violates security or reliability guidelines (SQL injection, race condition, etc.)
- **Environment-Specific** — Issue only manifests in production (timing, state, external service)
- **Transient** — Issue was environmental noise (flaky test, temporary API outage) and revert was unnecessary

---

*Auto-created by revert-rca-loop*"
```

Capture the issue number: `ISSUE_NUM=$(echo $OUTPUT | jq -r '.number')`

### Step 5: Trigger Reflection Session

Create a GitHub issue that will trigger a Reflection session via RemoteTrigger.

The reflection session should:

1. Fetch the RCA issue and revert commit details
2. Analyze the PR changes and the reason for revert
3. Identify the root cause category
4. Document findings in `.claude/reflections/rca-<issue_num>.md`
5. Close the RCA issue as documented

```bash
# Log a trigger event for reflection
mkdir -p .claude/state
echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"revert_pr\":$PR_NUM,\"rca_issue\":$ISSUE_NUM}" >> .claude/state/revert-rca-triggers.jsonl
```

### Step 6: Track Trends

Append to revert tracking log:

```bash
cat >> .claude/improvement-loop/revert-log.md <<'EOF'
## $(date -u +%Y-%m-%d)

- **PR #$PR_NUM** reverted
  - RCA Issue: #$ISSUE_NUM
  - Timestamp: $(date -u +%Y-%m-%dT%H:%M:%SZ)
  - Status: RCA pending

EOF
```

### Step 7: Alert if Threshold Exceeded

If reverts/day > 3, create a meta-improvement issue:

```bash
REVERT_COUNT=$(git log --since="7 days ago" --grep="^Revert" --oneline | wc -l)
if [ "$REVERT_COUNT" -gt 3 ]; then
  gh issue create \
    --title "[Meta] Revert rate elevated (${REVERT_COUNT}/day)" \
    --label "meta-improvement,acmm" \
    --body "The 7-day revert rate is ${REVERT_COUNT}/day (threshold: 3). This suggests the autonomous system is unstable. Investigate pattern from revert-rca-loop output and consider:

- Improving test coverage
- Tightening validation rules
- Reducing agent complexity/ambition
- Adding pre-commit gates"
fi
```

## Scheduling

Run hourly to catch reverts quickly:

- **Name:** `mbe-revert-rca-loop`
- **Schedule:** `7 * * * *` (every hour at :07 to avoid conflicts)
- **Prompt:** `/revert-rca-loop`

## Success Criteria

A successful revert-rca-loop run:

1. ✅ Detects all reverts in the last 24h
2. ✅ Correctly identifies AI-authored PRs
3. ✅ Creates RCA issue without duplicates
4. ✅ Logs revert event for trend analysis
5. ✅ Alerts when revert rate exceeds threshold

## Output Files

| File                                      | Purpose                                       |
| ----------------------------------------- | --------------------------------------------- |
| `.claude/state/revert-rca-triggers.jsonl` | Event log (timestamp, reverted PR, RCA issue) |
| `.claude/improvement-loop/revert-log.md`  | Human-readable revert history                 |
| `RCA Issue #N`                            | Investigation and findings                    |
| `.claude/reflections/rca-*.md`            | Detailed RCA analysis and learnings           |

## Integration with Progress Tracker

The revert-rca-loop feeds data into `/progress-tracker`:

- Tracks revert rate (target: < 1/day)
- Identifies recurring root causes
- Triggers escalation if rate climbs
- Suggests process improvements

## Integration with Learning Loop

Findings from RCA issues inform the learning loop:

- Patterns identified in RCA flow back to agent-core improvements
- Test coverage gaps found in RCA become new test requirements
- Systemic issues trigger updates to CLAUDE.md or gotchas.md

## Troubleshooting

| Issue                    | Cause                       | Fix                                             |
| ------------------------ | --------------------------- | ----------------------------------------------- |
| No reverts detected      | No revert commits on main   | Check git log manually                          |
| AI PR not detected       | Body doesn't contain marker | Check PR body format in pr-creator.ts           |
| Duplicate RCA issues     | Check logic failed          | Improve search query to match PR number exactly |
| Reflection not triggered | Event log not created       | Verify `.claude/state/` is writable             |

## Examples

### Example 1: Logic Error in Feature PR

Revert: `Revert "feat: add payment retry logic (#1234)"`

- Root cause: Agent didn't account for webhook race condition
- Fix: Add pessimistic locking to payment service
- Learning: Update PR examples in prompt-builder to show concurrency patterns

### Example 2: Missing Edge Case in Test PR

Revert: `Revert "test: expand coverage for auth flow (#1250)"`

- Root cause: New tests broke on parallel execution
- Fix: Add test isolation/setup/teardown
- Learning: Add vitest concurrency patterns to skill examples

### Example 3: Unsafe SQL Pattern

Revert: `Revert "feat: batch user deletion (#1267)"`

- Root cause: SQL query vulnerable to injection (missing parameterization)
- Fix: Use Prisma parameterized queries
- Learning: Add security review to quality gates

## Next Steps After RCA

Once RCA is complete (issue closed with findings documented):

1. **Follow-up issue** — If systemic: Create task to fix root cause
2. **Skill improvement** — Update relevant skill SKILL.md with pattern
3. **Test addition** — Add regression test to prevent recurrence
4. **Documentation** — Update CLAUDE.md or gotchas.md if pattern is widespread