feat: Improve Claude Code commands and document learnings lifecycle

- Add /learnings command to process and incorporate learnings files
- Guide /review into plan mode before analyzing changes
- Rewrite /tests for clearer parallel execution and plan mode on failure
- Document the full learnings capture-integrate-cleanup lifecycle

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: cadamsdotcom

.claude/commands/learnings.md

@@ -0,0 +1 @@
+Enter plan mode. Examine all the files in .claude/learnings (besides the README). Are there any learnings in the files that should be incorporated into documentation, or improvements to scripts, checks, or tooling? Anything you would simply relearn on the job is not a candidate for inclusion. However if you believe it's possible to reduce the surprises you face working in the repo (eg. variable, class, route, component etc. naming can be improved to avoid future confusion, or duplication could be removed, or architecture could be simplified) include those changes in your plan. Create a plan that incorporates all learnings then deletes the learnings files.

.claude/commands/review.md

@@ -1,4 +1,4 @@
-Review the changes on the current branch compared to main. Do not use subagents. Run `git diff main...HEAD` to see all changes.
+Enter plan mode. Review the changes on the current branch compared to main. Do not use subagents. Run `git diff main...HEAD` to see all changes.
 
 Check for these classes of issues:
 

.claude/commands/tests.md

@@ -1 +1 @@
-Let's confirm that pre-commit and all component, python, and e2e tests pass. Prefer running them all in parallel. The e2e tests will give you paths to see the full pytest and server output. If tests fail, don't rerun them without examining the logs and don't rerun them without changing the code, unless you absolutely need to check something.
+Run pre-commit and all component, python, and e2e tests. Prefer running them all in parallel and all at once as they do not conflict. The e2e tests will give you paths to see the full pytest and server output. If tests fail, enter plan mode and examine the failures. Don't rerun tests without first examining the logs and formulating your plan. Don't rerun tests without changing code unless you absolutely need to check something.

docs-site/docs/agent-optimizations.md

@@ -146,6 +146,19 @@ TDD log for inappropriate overrides or skip-red usage.
 
 Both hooks encourage the agent to reflect on its session, producing structured notes that benefit future sessions.
 
+### The Learnings Lifecycle
+
+Learnings files accumulate in `.claude/learnings/` over time. They carry forward across sessions via context injection, but they're meant to be **temporary** --- each one represents a surprise or insight that should eventually be absorbed into the codebase itself.
+
+The `/learnings` command completes the cycle. It examines all learnings files, identifies which ones warrant permanent changes (better naming, documentation updates, new checks, script improvements, simplified architecture), plans those changes, and then **deletes the learnings files**. Anything the agent would simply relearn on the job is discarded rather than turned into permanent changes.
+
+The full flow:
+
+1. **Capture**: Stop/PreCompact hooks prompt the main session, and SubagentStart injects `additionalContext` prompting subagents, to write `.claude/learnings/{date}-{slug}.md`
+2. **Carry forward**: Learnings files are re-injected into future sessions so the agent doesn't repeat mistakes
+3. **Integrate**: The user runs `/learnings`, which incorporates worthwhile insights into code, docs, scripts, or tooling
+4. **Clean up**: Learnings files are deleted once their value has been absorbed into the repo
+
 ## Dot Silencing
 
 Test progress dots (`.....F..`) are suppressed in pytest output via the `pytest_report_teststatus` hook in [`tests/conftest.py`](https://github.com/cadamsdotcom/CodeLeash/blob/main/tests/conftest.py):