Retro: Improve the Agent Environment

What it does

This retrospective examines the environment in which work happened rather than treating every mistake as a request for another rule. Repeated mechanical violations are candidates for deterministic checks; judgement calls may belong in coding standards. Missing navigation pointers, inaccessible information and poorly wired existing checks can explain wasted work. The source also encourages slimming steering documents and removing instructions that do nothing. Recommendations should follow primary session evidence and prioritize impact instead of generating a generic process checklist.

When to use it

• Investigate why an agent repeatedly missed an existing project check.
• Reduce large steering files after a slow implementation session.
• Turn a recurring mechanical error into a reliable automated guard.

Step-by-step workflow

1. Review the session before clearing its context, or supply its actual log.
2. Identify concrete detours, repeated errors and missing information.
3. Check existing automation and documentation before proposing additions.
4. Separate deterministic checks from judgement guidance and rank useful changes.
5. Present specific environment edits with evidence and a way to verify their effect.

Example request

Use retro on this completed importer session. Identify where navigation, missing context or absent checks caused rework. Cite the relevant session evidence. Prefer wiring an existing check over adding instructions, and remove redundant guidance when justified. Propose at most the changes supported by the record. Do not broaden permissions or edit project files until the recommendations are reviewed.

Worked example

If the agent repeatedly forgot to run an existing schema validator because the documented command was outdated, the useful change may be repairing one README pointer or connecting the validator to the normal check command. Adding three paragraphs saying to be careful would not remove that failure mode. If no recurring environment problem appears, a no-change result is appropriate. The retrospective should distinguish an isolated implementation error from a tool or instruction issue.

What you get

An evidence-ranked set of proposed environment changes, including deletions and reused checks where appropriate.

How to evaluate the result

• Trace each recommendation to a recorded incident.
• Check an existing tool or instruction does not already cover it.
• Prefer measurable fixes and remove unsupported process additions.

What you need

The relevant session context or log, project guidance and existing development commands. Sensitive logs need redaction before sharing.

Setup and activation

The publisher documents plugin setup for Claude Code, Codex and Copilot, and manual Agent Skills setup for Gemini CLI and other clients. Choose one distribution method per client to avoid duplicate skills. The engineering collection expects project-specific tracker, triage-label and document-location settings from setup-matt-pocock-skills. Keep referenced companion skills and files available. This catalogue review does not install or run them; scan the exact source before any later installation. Client tools, permissions and subagent support still need separate validation.

Limits and considerations

A retrospective does not automatically justify changing product behavior, security boundaries or permissions. Correlation in one session is not proof of a recurring pattern. The source’s companion writing guidance may be needed when rewriting agent instructions.

Related workflows

• Pair with code-review when judgement standards are missing.
• Use handoff to preserve evidence before changing sessions.

License and reuse

MIT at repository level (Copyright 2026 Matt Pocock). Preserve the copyright and permission notice when redistributing substantial source material; inspect any separately licensed dependencies or assets.

Further reading

• Reviewed SKILL.md (immutable commit)
• Publisher README: setup and compatibility
• Reviewed MIT license