Evolve
Convert repeated mistakes into rules or automation. Requires 2+ occurrences with evidence.
Inputs
Ask the user for:
- What happened (describe the failure)
- How many times (must be 2+ across sessions or PRs)
- Evidence (PR/issue links or excerpts)
- Where it should have been caught (tooling, docs, invariant)
Decision hierarchy (smallest effective change)
- Automate — Can tooling enforce it (lint rule, CI check, pre-commit hook)? If yes, propose automation first.
- Tier 1 constraint — Applies to all code, critical to enforce? Add to AGENTS.md invariants.
- Tier 2 guidance — System-specific, helpful but not critical? Add to the relevant doc in
docs/. - Reference only — Best practice but not enforceable? Add as a comment or reference doc.
Output format
## System Evolution Proposal
### Failure Pattern
What: <description>
Frequency: <X> times across <Y> PRs/sessions
Evidence: <links or excerpts>
### Decision: AUTOMATION | TIER 1 | TIER 2 | REFERENCE
Rationale: <1-2 sentences>
### Proposed Change
Location: <exact file path + section>
Proposed addition:
<exact text to add — use positive constraints>
### Implementation Steps
1. <what to modify>
2. <validation needed>
3. <PR creation>Notes
- Use positive language ("Do X", not "Don't do Y").
- Do not modify files until the user approves the proposal.
- Prefer automation when possible — enforced beats documented.