session-review

Session Review

Runs a structured end-of-session review to ensure every change made during the session is properly covered by tests, documented, specified, intentional, and as clean as possible. Also extracts and persists any newly identified practices.

Prerequisites

• A git repository with changes from the current session
• AGENTS.md present in the repository root (or a known location)
• Spec files accessible (if the project uses specifications)

Steps

1. Collect the Intent Behind the Change

Review git diff HEAD~..HEAD (or all commits since the session started) and ask the user:

"What was the goal of this session? What problem were you solving, and what approach did you take?"

Record the stated intent. If the user does not respond, infer the intent from commit messages and changed code.

2. Simplicity Review

Before writing any tests or docs, review the changed code and ask:

"Could this be implemented more simply, cleanly, succinctly, or elegantly? Are there any abstractions that can be removed, renamed, or consolidated? Is there anything here that is over-engineered for what is actually needed?"

Apply any improvements the review surfaces. Tests, docs, and specs are written against this final, clean implementation.

3. Add Tests to Cover the Change

Identify all changed or added functions, classes, and modules. For each:

• Check whether a test already exists that exercises the new or modified behavior.
• If no test covers it, write one (or ask the user to confirm before writing).
• Focus on "green path" tests that cover the main functionality.
• Run the test suite to confirm all tests pass:

  # Python
  uv run pytest
  
  # JavaScript / TypeScript
  npm test
  
  # Go
  go test ./...
  

• Report any failing tests and fix them before proceeding.

4. Update Documentation

For each changed public interface, module, or behavior:

• Update inline docstrings or comments if the behavior changed.
• Update any relevant README.md, docs/, or wiki pages.
• If the project uses a changelog (CHANGELOG.md), add an entry under ## Unreleased.
• If the project uses the Divio documentation system (tutorials, how-tos, reference, explanation), identify which document type needs updating and make the edit.