AI Simplify Sweep

Simplify Sweep

Sweeps stale code complexity on demand via an /ai-simplify wrapper, gates the diff, and opens a draft PR for human review. Use it for an operator-triggered simplification pass — never auto-merges, never runs unattended.

Purpose

Codebases accumulate entropy: dead branches, redundant guards, copy-pasted helpers, layers of indirection. /ai-simplify fights that but needs manual invocation. This skill is a manual wrapper that runs simplify, gates the diff, and opens a draft PR so a human reviews the proposed reductions before merge. No scheduler — an operator triggers it.

Workflow

Principles applied: §10.1 KISS (conservative reductions only — the sweep trades surface area for safety).

Step 1 — Invoke /ai-simplify non-interactively

Read .claude/skills/ai-simplify/SKILL.md (when present) to confirm whether an --auto flag exists. Otherwise invoke with conservative defaults:

/ai-simplify --conservative

Capture the diff. If empty, emit framework_operation operation=simplify_sweep_no_op and exit 0.

Step 2 — Gate the diff

Non-empty diff: run the pre-commit gate locally.

ai-eng gate run --cache-aware --json --mode=local

If the gate fails, emit operation=simplify_sweep_gate_failed with the failure summary and exit 1 — never open a PR with broken code.

Step 3 — Commit + open draft PR

/ai-commit "chore(simplify-sweep): conservative simplification sweep"
/ai-pr --draft --title "chore(simplify-sweep): simplification" --body "Manual entropy sweep. Review the diff before merge."

The title/body mark this as an entropy GC pass so reviewers apply lighter scrutiny than a feature PR while still verifying behaviour is preserved.

Hard Rules

• Never auto-merge — the PR is always --draft.
• Conservative defaults only — guard clauses, early returns, dead-code removal, single-call-site inlines. No aggressive refactors.
• Empty simplify diff: exit cleanly with a status event; do NOT open an empty PR.

Telemetry

Each run emits one framework_operation:

• operation=simplify_sweep_started — at invocation.
• operation=simplify_sweep_no_op — empty diff, no PR.
• operation=simplify_sweep_gate_failed — diff produced but gate refused.
• operation=simplify_sweep_pr_opened — happy path, includes pr_url.

Common Mistakes

• Running more often than weekly — sub-weekly runs flood reviewers with noisy PRs (auto-merge and aggressive modes are already barred by Hard Rules).

Examples

Example — dry-run preview

User: "preview what the simplify sweep would touch"

/ai-simplify-sweep --dry-run

Runs the simplify pass and prints the diff without staging a commit or PR — useful for reviewing scope before a full run.

Integration

Called by: operator manually. Calls: /ai-simplify (conservative mode), /ai-commit, /ai-pr --draft. See also: /ai-branch-cleanup (lifecycle sweep), /ai-skill-improve (skill-level improvement).

• Telemetry: framework_operation events aggregated from framework-events.ndjson.

References

• Related: .claude/skills/ai-simplify/SKILL.md
• Manifest entry: .ai-engineering/manifest.yml skills.registry.ai-simplify-sweep