coach-improve

name	coach.improve
description	Run one improvement iteration. Chooses between PCO and IntelligentDesign based on recent effectiveness, runs the chosen approach, falls back to the other if it fails. Use when asked to "improve the agent", "run a coaching session", or "coach improve".

Improvement Iteration

Orchestrates improvement by choosing between /coach.improve.pco and /coach.improve.design based on effectiveness.

Assumes .coach/state.json and the current session directory already exist (via /coach.start-session). Reads IMPROVE.md for domain context.

Step 1: Choose Approach

Read .coach/state.json (check approach_stats) and .coach/todos.md. Pick the approach most likely to succeed this session.

Approach Stats (tracked in state.json)

{
  "approach_stats": {
    "pco": {"attempts": 5, "improvements": 2, "last_used": "20260330-..."},
    "design": {"attempts": 8, "improvements": 5, "last_used": "20260331-..."}
  }
}

Decision Rules

1. If one approach has a clearly better hit rate, prefer it (but still use the other ~30% of the time to keep exploring)
2. If PCO hasn't been run in 3+ sessions, run PCO (fresh experience reveals new signals)
3. If there's a specific bug/TODO in todos.md, prefer IntelligentDesign (targeted fixes)
4. If the alpha.0 reference in IMPROVE.md has an unaddressed gap, prefer IntelligentDesign
5. If both are similar, alternate
6. If no stats yet, start with IntelligentDesign (the coach can see obvious wins first)

Log the chosen approach in the session's plan.md.

Step 2: Run Chosen Approach

Run /coach.improve.pco or /coach.improve.design.

Step 3: Handle Failure

If the chosen approach didn't produce an improvement (no accepted patch, or scores regressed):

1. Log the failure
2. If time/context permits, try the other approach as a fallback
3. If both fail, log it and move on — not every session produces a win

Step 4: Update Approach Stats

After the session, update approach_stats in .coach/state.json:

stats = state["approach_stats"][approach]
stats["attempts"] += 1
if improved:
    stats["improvements"] += 1
stats["last_used"] = session_timestamp

Also update .coach/todos.md with the approach tag:

- [x] (ID) Fixed chain-aware scoring in helpers/targeting.py — +41% avg
- [x] (PCO) Learner patched should_retreat with extra HP caution
- [x] (ID) Improved LLM prompt to return role suggestions

Principles

• One change per session. Don't stack changes from both approaches.
• Track what works. The stats drive future decisions.
• Alternate when tied. Don't get stuck in one mode.
• Fallback on failure. If PCO produces nothing, try design (and vice versa).