# Process: Framework Self-Improvement

**Primary agent:** `.claude/agents/scrum-master.md`

## When to run
At the end of every sprint retrospective (`process/05_sprint_retrospective.md`), as a final pass over the insights just generated. Also whenever an impediment (`logs/impediment_log.md`) or a piece of technical debt (`logs/technical_debt_log.md`) turns out to be caused by the process kit itself rather than the product.

## Why this is separate from the sprint retrospective
A sprint retrospective improves how *this team* works within a sprint — its actions go straight into the next sprint's plan. This process improves the *kit* — `AGENTS.md`, `process/*.md`, `templates/*.md`, `.claude/agents/*.md` — which is shared infrastructure that every future sprint and every future project built from this repo will inherit. Changes here should be rarer, more deliberate, and evidence-based, not made on a single sprint's say-so.

## Steps

1. **Sort insights.** For each retrospective insight (and any impediment or tech-debt item that smells like a process gap), ask: is this about how *our team* works, or about a gap/friction in the kit itself (a missing checklist item, an agent whose scope doesn't match reality, a template that doesn't fit how this project actually works, a process step that's missing or wrong)? Team-level insights stay in the normal retro flow. Kit-level insights move to step 2.

2. **Log it, don't act on it yet.** Add a row to `logs/process_improvement_log.md` describing the insight and which file(s) it likely affects. If the same underlying insight has appeared before, increment its recurrence count instead of adding a duplicate row.

3. **Only propose a change once a pattern is real.** Require at least one of the following before proposing an edit to the kit:
   - The same friction has now shown up 2+ times (recurrence in the log), or
   - A single occurrence was severe enough to visibly break a sprint (e.g., a process step was unusable, an agent's constraints caused it to do something wrong) — note this explicitly as the justification.
   
   A one-off minor annoyance is not enough; log it and wait to see if it recurs.

4. **Propose a concrete, minimal edit.** Draft the specific change to the specific file(s) — not a vague "improve X." Explain, in the proposal, what evidence (which sprints, which log rows) motivates it. Keep the diff as small as the insight warrants; do not use the opportunity to rewrite unrelated parts of the file.

5. **Confirm with the user before applying.** These files affect every future sprint and every future project run from this repo, not just the current one — treat editing them like editing shared configuration. Present the proposed diff and the evidence, and get explicit go-ahead before editing `AGENTS.md`, `process/*.md`, `templates/*.md`, or `.claude/agents/*.md`.

6. **Apply and close the loop.** Once approved, make the edit, mark the log row `Applied` with a one-line resolution note, and mention the change at the start of the next sprint planning or retrospective so the team knows the kit changed and why.

## Exit criteria
- Every retrospective has been checked for kit-level (not just team-level) insights.
- No insight sits at 2+ recurrences in `logs/process_improvement_log.md` without either a proposed change or an explicit, logged reason it was rejected.
- No edit was made to `AGENTS.md`, `process/`, `templates/`, or `.claude/agents/` without user confirmation and a logged evidence trail.

**On completion:** this runs inside the retrospective (phase 5) and does not add its own `state.md` phase. It gates the phase-5 → phase-1 transition: don't advance `state.md` past the retrospective until this pass has run.