nhouseholder/response-recap

Response Recap — Summary Only When It Matters

Provide a clear recap after complex work. Skip it for simple stuff.

When to Fire

INCLUDE recap when:

• Multi-file changes (3+ files edited)
• Debugging session that found a non-obvious root cause
• Architecture decisions with tradeoffs
• Multi-step implementations (planning → coding → testing)
• Configuration changes that affect how the project runs
• Any work where the "what changed and why" isn't immediately obvious

SKIP recap when:

• Single-file edit (the diff tells the story)
• Simple Q&A or factual answer
• Quick 1-3 line fix
• Running a command and reporting output
• The response is already short enough to understand at a glance
• User is clearly moving fast and doesn't need a debrief

The Decision Rule

If the user would need to scroll up to remember what just happened → add a recap. If the response fits on one screen and is self-explanatory → skip it.

The Recap Format

Keep it tight — 2-5 lines, not a full report:

---
**What happened:** [1-2 sentences — plain English]
**What changed:** [file list with one-line descriptions]
**Current state:** [where things stand]

For debugging sessions, add the insight:

---
**What happened:** [what was wrong and what fixed it]
**Root cause:** [the "aha" — why it was broken]
**What changed:** [files]
**Current state:** [fixed/deployed/needs testing]

Formatting Rules

1. Lead with "what" not "how" — say what the change means, not line numbers
2. Plain English first — "Boosted science score weight" not "changed 0.4 to 0.6 on line 47"
3. Max 5 bullets in "What changed" — group related changes
4. No filler — no "I've gone ahead and...", "As requested..."
5. Connect to user impact — "This means quiz results will now..." not just "modified recommend.js"

Mid-Task Progress (Long-Running Work)

For tasks taking 5+ tool calls, give a brief status at natural milestones:

Step 3/7 done — [what just completed]. Moving to [next step].

• One line, inline with the work — not a separate message
• Only at logical boundaries (file completed, phase changed, agent returned)
• Never interrupt flow to give status — attach it to an action you're already taking
• Skip if the task is nearly done (80%+) — just finish

Adaptive Detail

• Quick fix → skip recap entirely
• Multi-step task → 3-4 line recap + mid-task progress
• Complex debugging → include root cause insight
• Architecture decisions → include the tradeoff considered