--- name: session-review-db852b7eb25e description: | Review session captures and extract process improvements. Use when the user says "review session", "session review", or when session-capture recommends a review (typically every 5 captures). Identifies failure modes, positive patterns, and drafts local proposals or forward-to-meta lessons. --- # session-review ## Purpose Turn raw session history into structured improvement artifacts. This skill reads a session capture, identifies what went well and what failed, produces a review artifact, and optionally drafts a local proposal or a forward-to-meta lesson. ## Preconditions - A session capture exists at `.untracked/session-captures/-.md`. - The agent has the capture file path (provided by the user or by the session-capture skill). ## Required Reads 1. The session capture file (path provided as input). 2. `.agents/improvement/failure-modes.md` -- existing known failure patterns. 3. `.agents/policy/contract.md` -- to check for contract violations. 4. `.agents/docs/user/session-review-and-improvement.md` -- review process rules. 5. The workflow `dossier.md` for any workflow the session worked on (to compare intent vs. outcome). ## Procedure 1. **Parse the session capture.** Extract: session goal, files touched, commands run, tests run, blockers encountered, and unresolved follow-ups. 2. **Assess goal completion.** Was the stated session goal met? Partially met? Not met? Cite specific evidence from the capture. 3. **Identify failure modes.** Look for these categories: - Contract violations (acceptance criteria changed without approval). - Scope drift (work done outside the workflow's write scope). - Over-reading (excessive PM or file loading beyond what the task required). - Under-documentation (no handoff written, no run-log entry, no session capture). - Silent failure (errors encountered but not reported or escalated). - Defective verification instrument -- a test, gate, scan pattern, mutation check, or heuristic that produced a result indistinguishable from a correct one without having been exercised against the condition it exists to detect. Distinct from silent failure: that is an error not reported, this is a success that was not earned. An instrument that has not been exercised against the condition it detects has not been verified. Look for a check that passed before the work it checks was done, a control that was described but never run, and a clean result that is also what a broken instrument would print. 4. **Check against known patterns.** Compare findings to `.agents/improvement/failure-modes.md`. Note if a known pattern recurred or if a new pattern emerged. 5. **Identify positive patterns.** Note effective practices worth reinforcing (e.g., minimal PM loading, clean handoff, good test coverage). 6. **Draft local proposal (if warranted).** If a process change would prevent a failure mode found in this session, draft a proposal. Only draft if the improvement is concrete and actionable. 7. **Update failure-modes.md (if warranted).** If any process failure was identified during the session that is not already in `.agents/improvement/failure-modes.md`, append it as `FM-L` -- the next free number in this project's own `FM-L` sequence, counting from 1 -- with description, impact, and suggested mitigation, using the structured format in that file. A bare `FM-` belongs to the framework; see the namespace rule at the top of `failure-modes.md`. 8. **Draft forward-to-meta lesson (if warranted).** If the finding generalizes beyond this specific project, draft a forwarding artifact. See `lessons-forward` skill for criteria. ## Output ### Session Review (always produced) Write to `.agents/improvement/session-reviews/--review.md`: ```markdown # Session Review **Date:** YYYY-MM-DD **Capture:** **Workflow:** ## Goal Completion -- <1-sentence explanation> ## Failure Modes Found - : ## Known Pattern Recurrences - -- ## New Patterns - ## Positive Patterns - ## Recommendations - ``` ### Local Proposal (only if warranted) Write to `.agents/improvement/local-proposals/-.md`: ```markdown # Proposal: **Origin:** session review <date> **Problem:** <what went wrong> **Proposed Change:** <specific change to a specific file> **Expected Benefit:** <what improves> **Risk:** <what could go wrong> ``` ### Forward-to-Meta Lesson (only if warranted) Write to `.agents/improvement/forward-to-meta/<date>-<slug>.md` using the format defined in the `lessons-forward` skill. ## Batch Review Mode When reviewing multiple captures at once, use this streamlined procedure instead of the full per-capture review. Five is the *trigger* threshold — the point at which a review is recommended — not a cap on how many captures a review covers. A batch review always covers the entire unreviewed backlog, however large it has grown. 1. **Read every unreviewed session capture.** Find the most recent file in `.agents/improvement/session-reviews/` (excluding `README.md`); every capture in `.untracked/session-captures/` newer than it is unreviewed. If no review exists, every capture is unreviewed. Read all of them, oldest first, so the chronology is visible. If the backlog is large enough that reading it all at once would exhaust context, read in oldest-first batches and carry forward a running list of candidate patterns rather than truncating the set — dropping the oldest captures loses exactly the long-running patterns a batch review exists to find. Say in the review if this was necessary. 2. **Identify the top friction pattern** across all captures — the single most recurring source of wasted time, confusion, or rework. 3. **Identify one positive pattern** worth reinforcing. 4. **Check against `failure-modes.md`** — is the friction pattern already known? If not, add it as a new `FM-L<n>` entry. 5. **Write a single batch review file** to `.agents/improvement/session-reviews/<date>-batch-review.md`: ```markdown # Batch Session Review **Date:** YYYY-MM-DD **Captures reviewed:** <list of every capture filename covered, oldest first> ## Top Friction Pattern <1-2 sentences describing the pattern and specific evidence from captures> ## Positive Pattern <1 sentence on what worked well> ## Action Taken - [ ] Added to failure-modes.md as FM-<N> (if new) - [ ] Drafted local proposal (if actionable) — see local-proposals/<date>-<slug>.md - [ ] No action needed (pattern is known and already mitigated) ``` 6. **Draft a local proposal** only if the friction pattern is actionable and not already mitigated. Keep the proposal under 15 lines. ## Completion Criteria - A session review file has been written with all sections filled. - Every failure mode is categorized and described with specific evidence. - Local proposals (if any) reference a specific file and a specific change. - The approval boundary is respected: no process or policy files were modified. - For batch reviews: a single review file covers the entire unreviewed backlog — no capture older than the review is left uncovered — and the top friction pattern is specific and evidence-based. ## Error Handling - If the session capture file does not exist at the given path, stop: "Session capture not found at <path>. Run session-capture first." - If the capture is too sparse to review (fewer than 3 substantive lines), write a minimal review noting "Capture insufficient for meaningful review" and stop. - If the workflow dossier cannot be found, skip goal-completion assessment against acceptance criteria and note it was skipped. - When updating `failure-modes.md`, assign the next free `FM-L<n>` -- local to this repository, counting from 1 -- and use the structured format defined in that file. Never mint a bare `FM-<n>`: that namespace is the framework's, and a client that takes the next number in it collides with whatever the framework defines there later. --- Source attribution: AMDResearch Original project: https://github.com/AMDResearch/omniprobe/blob/913ae319f727f8014e4db442a80e84915c8cf3a0/.agents/skills/session-review/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice ------------------------------------------------------------------------------- MIT License Copyright (c) 2026 Advanced Micro Devices, Inc. All Rights Reserved. Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ------------------------------------------------------------------------------- # Mega AI Hub resource metadata Creator / publisher: AMDResearch Original project: https://github.com/AMDResearch/omniprobe/blob/913ae319f727f8014e4db442a80e84915c8cf3a0/.agents/skills/session-review/SKILL.md Attribution basis: Source repository record Fields of work: Operations, Project & Program Management Roles: Business Process Analyst, Operations Manager, Project Manager Specialties: Specialty not specified Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: b7e89e307d7c9070e0a5506d6bee6f04844f67fd403845cd543143859593413d