Chaos Agent

---
name: chaos-agent
description: "Seed non-breaking but detectable bugs (lint violations, dead links) to verify autonomous audit/lint loops catch and file issues. Scheduled to run weekly to test measurement machinery. Invoke with /chaos-agent or schedule via RemoteTrigger."
user-invocable: true
---

# Chaos Agent

Verifies the continuous improvement loop by seeding synthetic bugs and confirming that autonomous site-audit and lint processes catch them and file issues.

**Goal:** Bridge the gap between 'Measured' (L3) and 'Adaptive' (L4) by proving our feedback loops actually work.

## Pre-Flight Checks

Before seeding any bug, chaos-agent MUST verify:

1. **Not in a worktree:** Refuse to run if `pwd` contains `.claude/worktrees/` — chaos branches in active worktrees corrupt in-flight feature branches
2. **On main branch:** Refuse to run if `git branch --show-current` != `main` — chaos runs must start clean from main

Add these checks as the first step of the skill:

```bash
# Guard 1: Check if we're in a worktree
if echo "$PWD" | grep -q ".claude/worktrees/"; then
  echo "ERROR: chaos-agent refuses to run inside an active worktree (.claude/worktrees/)"
  echo "This prevents silent corruption of in-flight feature branches."
  exit 1
fi

# Guard 2: Check if we're on main branch
CURRENT_BRANCH=$(git branch --show-current)
if [ "$CURRENT_BRANCH" != "main" ]; then
  echo "ERROR: chaos-agent refuses to run on branch '$CURRENT_BRANCH'"
  echo "Chaos runs must start from the 'main' branch to avoid corrupting feature work."
  exit 1
fi
```

## Workflow

### Phase 1: Seed a Bug

Pick a non-breaking but auditable bug type:

1. **Lint violation** (fastest)
   - Add an unused variable or import in a non-critical file
   - File: `apps/marketing/src/utils/test-lint.ts` (new file)
   - Violation: ESLint will catch `no-unused-vars`

2. **Dead link** (auditable by Lighthouse)
   - Add a 404 link to a non-critical page
   - File: `apps/marketing/src/pages/chaos-test.mdx` (new file)
   - Content: Plain HTML with a dead link to trigger Playwright link check

3. **A11y issue** (auditable by Lighthouse)
   - Add an image without alt text
   - File: `apps/rialto-web/src/pages/chaos-test.tsx` (new file)
   - Content: Render an img tag without alt attribute

**For this session, choose LINT VIOLATION (fastest, most deterministic).**

### Phase 2: Create a PR

1. Create a new branch:

```bash
git checkout -b chaos/synthetic-bug-$(date +%s)
```

2. Seed the bug:

```bash
mkdir -p apps/marketing/src/utils
cat > apps/marketing/src/utils/test-lint.ts <<'INNER_EOF'
// Synthetic bug for audit loop testing
const unusedVariable = "this variable is never used";

export function testFunction(): void {
  console.log("Function that should trigger audit");
}
INNER_EOF
```

3. Commit and push:

```bash
git add apps/marketing/src/utils/test-lint.ts
git commit -m "test(chaos): seed synthetic lint violation for audit verification"
git push origin chaos/synthetic-bug-$(git rev-parse --short HEAD)
```

4. Create PR (mark as test):

```bash
gh pr create \
  --title "test(chaos): synthetic bug for audit loop verification" \
  --body "## Purpose

This PR seeds a non-breaking lint violation to verify that the autonomous audit loops correctly identify and file issues.

## Bug Details

- **Type:** ESLint \`no-unused-vars\` violation
- **File:** \`apps/marketing/src/utils/test-lint.ts\`
- **Expected Action:** Site-audit or lint-monitor should catch this and file an issue

## Cleanup

This PR should be closed immediately after verification. The synthetic bug is intentional and should NOT be merged.

---
*Auto-generated by chaos-agent (synthetic bug audit)*" \
  --draft
```

### Phase 3: Verify Audit Loop Catches It

Wait for the autonomous audit loop (site-audit or lint-monitor) to run. Expected behavior:

**Within ~5 minutes (if on smoke audit cycle):**

- ESLint job fails on the branch
- CI reports lint failure
- Audit loop creates an issue with label `audit` + `ci-fix`
- Issue title matches the violation: "ESLint: no-unused-vars in apps/marketing/src/utils/test-lint.ts"

**Check:**

```bash
# Query for recently created issues
gh issue list --label "audit" --state open --json number,title,createdAt --limit 5
gh issue list --label "ci-fix" --state open --json number,title,createdAt --limit 5
```

If an issue was filed referencing the lint violation, the audit loop is working! ✅

### Phase 4: Close and Document

1. **Close the draft PR** (don't merge):

```bash
gh pr close <pr_number>
```

2. **Close the audit-filed issue** (mark as verified):

```bash
gh issue close <issue_number>
gh issue comment <issue_number> --body "Verified: Synthetic bug was correctly detected and filed by audit loop. Closing as verification complete. (chaos-agent run: $(date -u +%Y-%m-%dT%H:%M:%SZ))"
```

3. **Clean up the branch** (CRITICAL — prevent accumulation):

```bash
# Delete the local branch
git branch -D chaos/synthetic-bug-*

# Delete the remote branch
git push origin --delete chaos/synthetic-bug-*
```

4. **Log result to state file:**

```bash
mkdir -p .claude/state
echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"bug_type\":\"lint_violation\",\"verified\":true,\"issue_number\":$ISSUE_NUM}" >> .claude/state/chaos-runs.jsonl
```

## Cleanup Script (Stale Branch Removal)

To prevent branch accumulation, run `scripts/cleanup-chaos-branches.sh` to delete all stale
`chaos/synthetic-bug-*` branches (local and remote):

```bash
./scripts/cleanup-chaos-branches.sh
```

## Scheduling

This skill is designed to run on a weekly schedule (e.g., Friday 9am PT) via RemoteTrigger to continuously verify measurement machinery.

Set up in [claude.ai/code/scheduled](https://claude.ai/code/scheduled):

- **Name:** `mbe-chaos-agent`
- **Schedule:** `0 17 * * 5` (Fri 9am PT = 5pm UTC)
- **Prompt:** `/chaos-agent` (with pre-flight guard checks)

## Success Criteria

A successful chaos-agent run achieves:

1. ✅ Pre-flight guards prevent running in worktrees or on non-main branches
2. ✅ Lint violation is seeded without breaking the build
3. ✅ Audit loop detects the violation within expected time
4. ✅ GitHub issue is filed with appropriate labels
5. ✅ Issue is closeable and documented
6. ✅ Branch cleanup succeeds (both local and remote)
7. ✅ Entry is logged to state file for trend analysis

## Troubleshooting

| Issue                       | Cause                                  | Fix                                                    |
| --------------------------- | -------------------------------------- | ------------------------------------------------------ |
| Pre-flight guard triggered  | Running in worktree or non-main branch | Return to shared checkout, check out main, retry       |
| Lint violation not detected | Audit loop didn't run                  | Check `/site-audit smoke` or `/ci-monitor` was invoked |
| No issue filed              | Audit loop ran but didn't create issue | Check progress-tracker for audit loop health           |
| PR won't close              | Issue still linked                     | Unlink issue from PR before closing                    |
| Branch cleanup fails        | Remote branch protected                | Use `git push --force-with-lease` or manual cleanup    |

## Integration with Learning Loop

The chaos-agent output (`.claude/state/chaos-runs.jsonl`) feeds into `/learning-loop`:

- Track weekly verification success rate
- If success rate drops below 95%, alert that measurement machinery is degraded
- Create meta-improvement issue to investigate audit loop failures