| name | session-wrap-up |
| description | Review a completed, paused, or blocked coding-agent session to identify friction, mistakes, near misses, missing context, and opportunities to improve future work. Use when the user asks to wrap up, run a retrospective, explain what issues the agent faced, capture lessons learned, or recommend improvements to repository instructions, documentation, skills, tooling, tests, or workflows. Produce an evidence-based, propose-only report; do not apply follow-up changes unless the user asks. |
Session Wrap-Up
Run a candid, compact retrospective of the current session. Base it on the
conversation, commands, tool output, edits, verification, and unresolved work;
do not invent friction to make the report look substantial.
Interrogate The Session
Ask yourself:
- Where did I lose time, take a false start, or repeat work?
- What did I misunderstand or assume too early?
- What did the user's questions or corrections reveal about unclear scope,
location, status, or explanation?
- Which instructions were missing, hard to discover, ambiguous, or in tension?
- Which code, documentation, architecture, or terminology did I have to
rediscover?
- Which tool, dependency, environment, build, or test failure slowed the work?
- What nearly went wrong, even if the final result was correct?
- What remains incomplete, uncertain, or insufficiently verified?
- What worked especially well and is worth preserving or standardising?
- What single change would most improve a similar session next time?
Verify the factual premise behind user questions and corrections against the
available evidence. Treat a correction as strong evidence of an expectation or
communication gap even when its diagnosis is not confirmed.
Before reporting the outcome, perform only the cheap read-only checks needed to
confirm the current state. For repository work, normally inspect working-tree
status and the changed-file summary, then reconcile them with verification
already recorded in the session. Do not rerun expensive tests solely for the
wrap-up. State when relevant evidence is unavailable.
Distinguish observed facts from diagnosis and speculation. Say "No material
friction observed" when that is the honest conclusion.
Classify Findings
Assign each meaningful issue to the narrowest useful category:
- Agent practice: planning, assumptions, sequencing, communication, tool
choice, or verification discipline.
- Repository knowledge:
AGENTS.md, documentation, architecture inventory,
glossary, examples, or code discoverability.
- Reusable workflow: a missing or weak skill, script, task, template, check,
or automation.
- Environment or tooling: dependencies, permissions, local setup, external
services, or product limitations.
- Task definition: unclear scope, acceptance criteria, ownership, or product
boundary.
Keep Chatto, Authling, shared-framework, and repository-wide recommendations
separate. Place a proposed improvement with the product or infrastructure that
owns it.
Recommend Improvements
For each material finding, propose the smallest change likely to prevent the
same class of friction. Include:
- the evidence and impact;
- whether the root cause is known or inferred;
- the concrete improvement and likely owner or location;
- the expected payoff and any trade-off;
- a priority of now, soon, or only if repeated.
Prefer durable fixes over reminders. Examples include tightening a scoped
instruction, adding a focused test, exposing an existing task, improving an
error message, documenting a hidden invariant, or extending a relevant skill.
Do not recommend new process or documentation when a simpler code or tooling
fix would remove the problem.
Keep the wrap-up propose-only. Do not edit files, create issues, send feedback,
or start follow-up work unless the user explicitly asks.
Report Format
Return one concise report with these sections:
Outcome
State the session goal, result, and verification level. Call out incomplete or
unverified work without repeating the entire implementation handoff.
Friction And Near Misses
List only evidence-backed findings. For each, give the category, what happened,
and its practical impact. Separate agent mistakes from repository or tooling
problems. Treat direct user corrections as high-signal evidence of an
expectation or communication gap, not automatic proof of their diagnosis. Do
not infer dissatisfaction from tone alone.
What Worked
Capture practices, instructions, tools, or repository affordances that made the
session more reliable or efficient.
Improvements
Prioritise at most five concrete proposals. Name the likely owner or file when
known, and mark inferred diagnoses clearly.
Recommended Next Step
Choose the single highest-leverage action. If no follow-up is warranted, say
so. End with one short question only when the user's perspective would
materially change the recommendation.
Guardrails
- Be specific and candid without assigning blame or performing false humility.
- Do not exaggerate routine exploration into a systemic problem.
- Do not hide the agent's own errors behind tooling or instruction complaints.
- Do not expose secrets, personal data, or sensitive command output.
- Do not claim that a proposed improvement is validated when it has not been
tried.
