{"manifest":{"name":"Session Retrospective","version":"1.0.0","description":"A structured self-improvement protocol for AI agents: capture execution signals, analyze patterns, and write retrospective documents that improve future performance.","tags":["productivity","memory","improvement","retrospective","learning"],"standard":"agentskills.io","standard_version":"1.0","content_checksum":"e911cae65db0d7774935f079549fa2e98c936a98a0a44f7d0fc8154e6c695cd8","bundle_checksum":null,"metadata":{},"files":[]},"files":{"SKILL.md":"# Session Retrospective\n\nA structured self-improvement protocol for AI agents: capture execution signals during a session, analyze patterns, and write actionable retrospective documents that improve future performance.\n\n## Overview\n\nAI agents repeat the same mistakes across sessions because there is no mechanism to capture what went wrong and act on it. This skill defines a lightweight signal-capture protocol and a standardized retrospective format that creates institutional memory across sessions.\n\n**Inspired by the GEP (Governance Evolution Protocol) pattern from the AI agent capability evolution community.**\n\n## Signal Types\n\nDuring any agent session, six types of signals indicate improvement opportunities. Capture them as they occur, not after.\n\n### Signal: `log_error`\nExecution errors, exceptions, or tool failures during the session.\n\n```markdown\nSignal: log_error\nDescription: vitest run failed with \"Cannot find module '@/lib/stripe'\"\nContext: Ran tests before reading the mock setup in the test file\nRoot cause: Loaded the route file without checking for missing test prerequisites\n```\n\n### Signal: `protocol_drift`\nBehavior that deviated from stated guidelines, rules, or the user's stated workflow.\n\n```markdown\nSignal: protocol_drift\nDescription: Started implementation without writing a failing test first\nContext: Added tips_enabled to updateSkillSchema before writing the test\nRoot cause: Pressure to complete quickly overrode TDD protocol\n```\n\n### Signal: `user_feature_request`\nExplicit requests from the user for capabilities that don't exist yet.\n\n```markdown\nSignal: user_feature_request\nDescription: User asked to disable tips for community-inspired skills\nContext: tips_enabled existed in DB but not in the API or MCP tool\nImpact: Required a Chunk 0 to fix 3 separate gaps before main work\n```\n\n### Signal: `high_tool_usage`\nA tool called more times than necessary — indicates an inefficient approach.\n\n```markdown\nSignal: high_tool_usage\nDescription: Read() called 6 times on the same file during a single task\nContext: First read was full file; subsequent reads were targeted ranges\nRoot cause: Should have used Grep first to identify the relevant section\n```\n\n### Signal: `perf_bottleneck`\nOperations that were slower than expected — timeouts, long waits, or rate limiting.\n\n```markdown\nSignal: perf_bottleneck\nDescription: npx vitest run took 47s due to loading 3,847 test files in full\nContext: Run triggered during a quick sanity check\nRoot cause: Should have used vitest run --reporter=dot to reduce output overhead\n```\n\n### Signal: `capability_gap`\nMissing functionality the agent needed but didn't have.\n\n```markdown\nSignal: capability_gap\nDescription: No way to verify a skill on dev environment from within a task\nContext: Had to use curl to call /api/v1/skills/{id}/verify directly\nRoot cause: MCP verify_skill tool exists but requires knowing the Supabase URL\n```\n\n## Retrospective File Format\n\nWrite retrospectives to: `retrospectives/YYYY-MM-DD-description.md`\n\nName the description with 2–4 words describing the session's main work (e.g., `2026-03-15-tips-api-fix.md`).\n\n```markdown\n# Session Retrospective: {Description}\n\n**Date:** YYYY-MM-DD\n**Session scope:** {1-sentence description of what was accomplished}\n**Outcome:** success | partial | blocked\n\n---\n\n## Result\n\n{What was delivered. Be specific: which files changed, what tests pass, what deployed.}\n\n---\n\n## Signals\n\n### {Signal Type}: {Short title}\n\n**Observed:** {What happened}\n**Context:** {Where/when in the session}\n**Root cause:** {Why it happened — the real reason, not the symptom}\n**Proposed fix:** {Specific change to default behavior or process}\n\n---\n\n## Metrics\n\n- Files modified: N\n- Tests added: N\n- Context tokens consumed (estimate): N\n- Retries/corrections needed: N\n\n---\n\n## Parent Evolution ID\n\n{ID of a previous retrospective this builds on, if applicable. \"None\" if first in chain.}\n```\n\n## Writing a Retrospective\n\n### When to write one\n\nWrite a retrospective at the end of any session that:\n- Encountered at least one error or correction\n- Took more iterations than expected\n- Involved a process that should work differently next time\n- Produced a behavior the user had to redirect\n\nDo not write retrospectives for trivial sessions (simple edits, lookups, single-file changes with no corrections).\n\n### What makes a useful retrospective\n\n**Good root cause analysis:**\n> \"Root cause: I read the full 350-line route file instead of grepping for the specific function. This loaded 300 unnecessary lines.\"\n\nNot:\n> \"Root cause: I made a mistake.\"\n\n**Specific proposed fix:**\n> \"Proposed fix: For any file > 100 lines, always grep for the target symbol before reading. Default read limit: 60 lines.\"\n\nNot:\n> \"Proposed fix: Be more careful.\"\n\n**Honest metrics:**\nCount the actual number of retries, errors, and corrections. Underreporting defeats the purpose.\n\n### Reading retrospectives\n\nAt the start of any complex session:\n\n1. `Glob(pattern=\"retrospectives/*.md\")` to find all retrospective files\n2. Read the 3 most recent ones\n3. Note any `proposed fix` items that apply to today's task\n4. Apply them proactively before repeating past mistakes\n\n## Example Retrospective\n\n```markdown\n# Session Retrospective: Tips API Fix\n\n**Date:** 2026-03-15\n**Session scope:** Add tips_enabled to updateSkillSchema, /api/tips validation, and MCP update_skill\n**Outcome:** success\n\n---\n\n## Result\n\nModified 6 files, added 96 lines of tests. All 3 gaps closed:\n- PUT /api/skills/[id] now accepts tips_enabled\n- POST /api/tips returns 403 when tips_enabled=false\n- MCP update_skill tool exposes tips_enabled parameter\nCoverage held at 100% lines.\n\n---\n\n## Signals\n\n### capability_gap: tips_enabled existed in DB but not surfaced anywhere\n\n**Observed:** Column existed since DB migration but no API endpoint or MCP tool exposed it\n**Context:** User asked to set tips_enabled=false for community-inspired skills\n**Root cause:** Feature was added to DB schema without completing the API/MCP plumbing\n**Proposed fix:** When adding a DB column that represents a setting, always check (1) API PUT schema, (2) API validation guards, (3) MCP tool parameters as a checklist\n\n---\n\n## Metrics\n\n- Files modified: 6\n- Tests added: 96 lines\n- Context tokens consumed (estimate): ~8,000\n- Retries/corrections needed: 0\n\n---\n\n## Parent Evolution ID\n\nNone\n```\n\n## Integration with Memory\n\nRetrospective files complement but do not replace memory:\n- **Memory** stores facts and preferences that apply to all future sessions\n- **Retrospectives** store session-specific analysis for review before similar future sessions\n\nAfter writing a retrospective, update memory only if the proposed fix represents a durable change to default behavior — not if it's a one-time correction.\n"}}