# Self-Healing Improvement Loop — Operational Pattern

## Purpose
Continuous autonomous improvement cycle for the CMS-aiChemist platform. After every batch of tests or evaluations, this loop runs to surface findings, implement improvements, and validate them — narrowing the gap between current state and optimal with each iteration.

## The Loop

```
Surface Findings → Plan Design → Implement → Validate → Rerun Tests → Loop
```

### Step 1: Surface Highest-Value Findings
- Review test results (pass/fail, edge cases, performance)
- Review evaluation outputs (visual QA scores, accessibility audits, build metrics)
- Rank findings by impact: what improvement would deliver the most value?
- Categories: token fidelity, component coverage, surface parity, content lifecycle, pipeline reliability

### Step 2: Plan Design Improvements
- Query brain for priority guidance on findings
- Design minimal changes that address the top findings
- Prefer changes that improve multiple metrics simultaneously
- Examples: adding a missing token fixes both visual QA and cross-surface parity

### Step 3: Implement
- Make the changes: tokens, components, surfaces, pipeline scripts, content
- Follow existing patterns (DTCG format, CSS custom properties, shared UI components)
- Keep changes focused — one improvement per iteration when possible

### Step 4: Validate
- Build both surfaces (Next.js + Astro)
- Verify zero build errors, zero runtime errors
- Check that the improvement actually addresses the finding

### Step 5: Rerun Relevant Tests
- Re-execute the specific tests affected by the change
- Run the full test suite if the change touches shared infrastructure (tokens, build.py, packages/ui)
- Compare results against previous run — confirm improvement, check for regressions

### Step 6: Loop Back
- Surface new findings from the re-run results
- If new findings exist: continue the loop
- If all tests pass and no high-value findings remain: declare the iteration complete
- Push status to brain with findings, improvements made, and test results

## Stop Conditions
- All 5 end-to-end tests pass
- Visual QA score >= 90/100 on all surfaces
- No high-value findings remain (all remaining items are cosmetic or deferred)
- User explicitly intervenes with new priorities

## Integration with Existing Workflows
- This loop runs AFTER test execution, not during
- Each iteration produces a commit (if changes were made) and a brain push
- The brain accumulates test history, enabling trend analysis across sessions
- ADW can trigger the loop via issue labels (e.g., `self-heal`, `continuous-improvement`)

## Example Iteration
1. **Surface**: Test 2 (EmDash blog) passes but blog list has no pagination — works with 4 posts but won't scale
2. **Plan**: Add pagination component to shared UI, limit blog list to 10 per page
3. **Implement**: Create Pagination.tsx in packages/ui, update blog/index.astro
4. **Validate**: Both surfaces build, pagination renders correctly
5. **Rerun**: Test 2 passes, Test 3 (cascade) passes (new component uses tokens correctly)
6. **Loop**: Surface next finding — e.g., blog detail page lacks reading time estimate