reflection

To capture reusable learnings from a work session, review completed tasks and apply a high-bar filtering process to identify non-obvious gotchas or corrections worth codifying. This ensures only durable, valuable insights are routed to project resources, preventing repeated debugging efforts.

The best way to route agent instructions is to categorize proposed learnings by target audience, directing repo-specific guidelines to AGENTS.md and human-facing insights to project docs. This targeted routing standardizes conventions and ensures documentation reaches the correct consumers.

Filtering trivial session details requires applying strict criteria to identify only non-obvious gotchas, unrepeated conventions, and reusable corrections. This high-bar process avoids polluting documentation with low-value noise, preserving only insights that genuinely improve future agent performance.

You should document session insights in cross-project skills when the learnings involve reusable workflows or configurations applicable beyond a single repository. Repository-specific files like AGENTS.md are better for isolated conventions, while cross-project skills capture broader, repeatable debugging solutions.

Yes, session reflection works for any software development or project workflow where insights can be captured. It structures the filtering process to route proposed learnings to the correct target documentation, reducing repeated effort regardless of the specific development context.

Agents repeat debugging mistakes because valuable session insights are often lost without intentional knowledge capture. Implementing a structured reflection process identifies and codifies these reusable learnings into durable project resources, preventing future agents from wasting time on known issues.