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:

# 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:

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

2. Seed the bug:

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:

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):

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:

# 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):

gh pr close <pr_number>

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

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):

# 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:

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):

./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:

• 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