@ai-support-agent/cli 0.1.32 → 0.1.33-beta.1

package/dist/plugin/commands/fix-defect.md

@@ -0,0 +1,393 @@
+---
+description: Fix a bug through a gated pipeline that's reproduction-test-first, proving the fix with a red-to-green transition
+argument-hint: "[bug description / repro steps / issue number]"
+resumable: true
+---
+
+# Fix-defect pipeline
+
+Fix a reported bug through a disciplined, gated pipeline. Three things are non-negotiable:
+
+1. **Not one line of fix code gets written until the root cause is identified.**
+2. **If the code under test doesn't have adequate coverage, build that up first before going test-first.**
+3. **Write a failing test that reproduces the bug before touching the fix (red), and prove the fix by
+   making that same test pass (green).**
+
+A bug that can't be reproduced can't be fixed, and a test that never went red proves nothing.
+A fix without a root cause is just a symptom hidden away — and that's a failure.
+
+Target bug: $ARGUMENTS
+
+## Scope
+
+- In scope: fixing "broken behavior" — something not working as expected.
+- Out of scope: spec changes or new features — use /add-feature for those.
+  If partway through the work it turns out this is actually a spec change rather than a bug fix,
+  report that to the user and switch commands.
+
+## Two gates
+
+This pipeline has two gates that must never be crossed early.
+
+1. Plan-approval gate: for standard-or-larger changes, don't write fix code until the user
+   has approved the plan.
+2. Commit gate: never commit without the user's confirmation, under any circumstances.
+
+Even when it's tempting to push forward autonomously, always stop at the gate and get confirmation.
+
+## Completion Marker Convention
+
+This command runs under `claude -p` (non-interactive), which restarts as a fresh process every turn — past turn 1, this command body is not guaranteed to be re-expanded, so gate discipline (the two gates above) can silently erode across turns. To compensate, a hooks-based mechanism re-injects a digest of this command's must-obey constraints on the next turn whenever the pipeline is left incomplete.
+
+If this command's flow is **not yet complete** (e.g. mid root-cause investigation, stopped at the plan-approval gate, awaiting the regression test's red confirmation, mid-fix, awaiting review fixes, or stopped at the commit gate), your response **MUST end** with a line that is an exact match of:
+
+`<!-- ai-support-agent:resume name="fix-defect" -->`
+
+If the flow **is complete** (fix finished, committed with user confirmation, and the post-commit options were handled), do **not** output this marker.
+
+Never output this marker inside a code block or as an illustrative example — only emit it as the actual last line of real output when the flow is genuinely incomplete.
+
+<!-- RESUME_DIGEST_START -->
+When resuming this command on turn 2+ without the full command body re-expanded, obey these constraints:
+
+- **Two gates, never crossed early**:
+  1. Plan-approval gate (standard-or-larger changes): no fix code until the user has approved the fix plan.
+  2. Commit gate: never commit without the user's explicit confirmation, under any circumstances.
+- **Root cause before any fix code**: never write fix code on a hunch of "probably here." State the hypothesis as "X is the cause, because Y," verify it with the smallest possible change, and don't layer a new fix on top of a failed hypothesis — start over.
+- **Regression test must go red before green**: write a test that reproduces the bug and confirm it fails (red) before touching fix code. If you accidentally wrote fix code first, discard it (`git restore`) and start over from the test. After fixing, confirm that same test goes green.
+- Never self-interpret "roughly agreed to," silence, or an unrelated follow-up as plan approval or as commit confirmation.
+- **Don't hide the symptom**: no swallowed exceptions, no special-casing around the failing scenario, no loosened test expectations just to go green.
+- **Step 8 verification requires evidence, not speculation**: never claim "tests pass" / "build passes" / "the bug is fixed" without having actually run the command in this conversation and read its output. A stale or previous run's result does not count as evidence.
+- **Review gate (Step 7)**: every CRITICAL / HIGH finding from the code-reviewer / silent-failure-hunter review must be resolved, followed by a re-run of Step 6's checks (regression test green, no regressions), before moving on.
+- Follow the Step 9 commit-gate flow exactly: present the diff + proposed commit message, wait for confirmation, commit only after confirmation, then present the four post-commit options and execute the chosen one in the correct order (never remove a worktree before merge/PR is settled).
+<!-- RESUME_DIGEST_END -->
+
+## Procedure
+
+### 1. Declare the size classification
+
+Before starting work, declare which of the following applies.
+
+- Trivial: a change of one file, a few lines, with an obvious cause.
+- Small: a change of one or two files, where identifying the cause takes a bit of investigation.
+- Standard or larger: a change spanning multiple files, or where the cause is unclear.
+
+Regardless of the size of the change, fixes touching authentication/authorization, input handling,
+databases, external service integrations, or anything money-related are always treated as
+"standard or larger."
+
+### 2. Create a worktree
+
+Create a dedicated branch and worktree for the work, and do everything from here on inside that worktree.
+
+First check the existing isolation state.
+
+```bash
+MAIN_ROOT=$(git rev-parse --show-toplevel)
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null)
+echo "MAIN_ROOT=$MAIN_ROOT"
+echo "GIT_DIR=$GIT_DIR"
+echo "GIT_COMMON=$GIT_COMMON"
+echo "SUPERPROJECT=${SUPERPROJECT:-(none)}"
+```
+
+Use the output above to determine which of three states applies.
+
+| Condition | State | Action |
+|---|---|---|
+| `SUPERPROJECT` has a value | Inside a submodule | Don't create a worktree — work directly |
+| `SUPERPROJECT` is empty and `GIT_DIR != GIT_COMMON` | Already inside a worktree | Don't create a new one — keep working in the existing worktree |
+| `SUPERPROJECT` is empty and `GIT_DIR == GIT_COMMON` | Regular repository | Create a worktree (steps below) |
+
+Create the worktree.
+
+```bash
+git worktree add -b <branch-name> <path>
+# e.g. git worktree add -b fix/login-error ../worktrees/fix-login-error
+```
+
+- Name the branch after the bug (a `fix/` prefix is recommended).
+- A sibling directory outside the repo is usually the most convenient path (e.g. `../worktrees/<name>`).
+- If placing it inside the project (`.worktrees/`), confirm it's in `.gitignore` before creating it (`git check-ignore -q .worktrees`). If it's not listed, add it and commit that first.
+- Working inside a worktree keeps the main working directory clean, and rolling back is as simple as deleting the whole directory.
+
+Once created, run the test suite to confirm a clean baseline. If there are pre-existing failures, report them to the user and confirm whether to proceed.
+
+### 3. Investigate the root cause (four phases)
+
+**Iron rule: not one line of fix code until the root cause is identified.**
+
+Don't start fixing on a hunch of "probably here." A guessed fix tends to create a different bug.
+
+#### Phase 1: Gather facts
+
+- **Read the error message carefully**: read the stack trace to the end.
+  Record line numbers, file paths, and error codes. Don't skim.
+- **Confirm the reproduction is consistent**: pin down the repro steps and check whether it
+  happens every time. If it's not reproducible, gather more data instead of guessing at a fix.
+- **Check recent changes**: review `git diff`, recent commits, dependency changes, and
+  any configuration or environment differences.
+- **In multi-layer systems, gather evidence at each boundary**: for architectures like
+  API → service → DB, measure and log "input, output, state" at each component boundary to
+  identify which layer is broken before digging into the cause. Don't make sweeping changes across every layer at once.
+- **Trace the data flow backward**: when the error surfaces deep in the call stack, walk the
+  callers back to where the bad value originated. Fix the source, not the symptom.
+
+#### Phase 2: Pattern analysis
+
+- Look for a working, similar implementation elsewhere in the same codebase.
+- List the differences between the broken code and the working code (don't overlook small ones).
+- When consulting an external library's docs or a spec, read it in full rather than skimming a section.
+
+#### Phase 3: Hypothesize and verify
+
+- State the hypothesis in one clear sentence: "X is the cause, because Y."
+- Make the **smallest possible change** to test the hypothesis (one variable at a time).
+- Don't apply multiple fixes at once — you'll lose the ability to isolate what worked.
+- If the hypothesis is wrong, **form a new hypothesis from scratch** rather than layering another fix on top of the failed one.
+
+#### Plan-approval gate (standard or larger)
+
+Once the Phase 1-3 investigation is complete, for standard-or-larger changes, draft a fix plan,
+present it to the user, and get approval. Don't write fix code before approval.
+Use the planner subagent or /plan.
+
+#### If you get stuck
+
+- **After 3 or more failed fix attempts**: stop trying individual fixes and question the
+  architecture itself. If "every fix creates a problem somewhere else" or "the fix would require
+  major refactoring," that's an architectural problem. Report the situation to the user and
+  propose a fundamental design review.
+
+#### Excuses to watch for (all of them are off-limits)
+
+| Excuse | Reality |
+|---|---|
+| "It's a simple bug, the process is overkill" | Even simple bugs have a root cause |
+| "We're in a hurry, let's just guess a fix" | Guessing causes rework — systematic investigation is actually faster |
+| "Probably here, let me try it" | Looking at the symptom isn't the same as understanding the root cause |
+| "Fix it now, investigate later" | Fixing first contaminates the investigation |
+| "One more fix attempt" (on the 3rd+ try) | Question the architecture instead |
+
+### 4. Check test coverage of the affected code
+
+Before starting the fix, check whether the affected code already has adequate test coverage.
+Going test-first against inadequate coverage risks "I thought I made it red, but I just tripped
+over a pre-existing defect." Proving the fix requires a test foundation that guarantees the
+pre-bug, correct behavior.
+
+What to check:
+
+| Layer | What to confirm |
+|---|---|
+| Unit tests | Do they cover the normal and error paths of the affected function/method/class? |
+| Integration tests | Is the affected code's interaction with external dependencies (DB, API, filesystem, etc.) verified? |
+| Regression tests | Do tests exist for past, similar bugs? |
+
+**If coverage is adequate**, move to the next step.
+
+**If coverage is inadequate**, do the following before moving to the next step.
+
+1. Implement the missing tests (don't write fix code yet).
+2. Run the new tests and confirm they all **pass (green)**.
+   If any don't pass, they may be tripping over a separate pre-existing bug, or encoding a buggy
+   spec as the expected value — report this to the user and get a decision.
+3. Get the added tests reviewed (see "Test review" below).
+4. Resolve every CRITICAL / HIGH finding before moving to the next step.
+
+#### Test review (only when coverage was inadequate)
+
+Run a review using the same parallel Workflow execution as `/code-review` (Mode A).
+
+1. Identify the added test files, and select reviewers per `/code-review`'s "Selecting reviewers" table (`code-reviewer` is always included).
+2. Invoke the Workflow script described in `/code-review` and run the selected reviewers in parallel.
+3. Resolve every CRITICAL / HIGH finding, and re-run the tests to confirm they're all green.
+
+### 5. Write a regression test and confirm it fails (red)
+
+**Iron rule: fix code must never be written before the test.**
+
+If you accidentally write fix code before the test, **discard it immediately** and start over from writing the test.
+
+```bash
+git restore <the file you accidentally fixed>
+```
+
+"It was just a small change," "I'll write the test right after" are not acceptable excuses. A fix without a test is an unproven claim.
+
+---
+
+- Write a regression test that reproduces the bug, at whichever layer best reproduces it
+  (a logic bug calls for a unit test; a bug involving DB reads/writes, queries, or transactions
+  calls for an integration test against a real database; a bug in a cross-screen flow may call
+  for an E2E test).
+- Run the test and **confirm it fails**.
+- Check that the failure (error message, expected vs. actual value) matches the reported bug.
+  If it doesn't match, your understanding of the root cause is likely wrong — go back to step 3.
+
+#### Test anti-patterns (avoid these)
+
+- **Testing that a mock was called**: a test that only confirms a mock exists proves nothing
+  about actual behavior. Test the implementation.
+- **Using a mock without understanding it**: understand the side effects of the method being
+  mocked before mocking it. Mocking "just in case" strips out the side effects it depends on and
+  makes the test meaningless.
+- **Incomplete mock objects**: include every field the real API actually returns. A mock missing
+  some fields lets code that depends on those fields slip through untested.
+- **Adding test-only methods to production code**: put test cleanup helpers and the like in test
+  utilities. Don't pollute production classes with them.
+
+### 6. Fix the root cause (green)
+
+- Fix the root cause identified in step 3.
+- **Don't hide the symptom**: don't swallow exceptions, special-case around the failing
+  scenario with a conditional, or loosen a test's expected value just to make it pass.
+- Confirm the regression test goes green.
+- Run the existing test suite and confirm there's no regression. Include E2E tests
+  (`playwright.config.*` etc., if present). If they can't run due to environment constraints,
+  report that to the user.
+- If the fix spans multiple repositories, run the test suite in every repository that was
+  changed and confirm there's no regression.
+- If the build breaks, restore it with /build-fix before continuing.
+
+#### Defense-in-depth validation
+
+If the bug was caused by invalid data flowing through the system, consider not just fixing the
+one spot but adding validation at every layer the data passes through, making the bug
+**structurally impossible** rather than merely patched.
+
+| Layer | What to add |
+|---|---|
+| Entry point | Reject invalid values early at the API/endpoint |
+| Business logic | Add a guard at the entry of the processing function too |
+| Environment guard | Block dangerous operations in specific contexts, like test runs |
+| Debug logging | Log the stack trace and input values to make future investigation easier |
+
+Each layer catches a different code path or a different mock-based bypass.
+Whether every layer is needed depends on the nature of the bug. Include which layers you applied and why in the change.
+
+#### Logging considerations (for projects that follow a logging convention)
+
+Alongside the fix, check the following.
+
+- If **ERROR/WARN logging was missing** at the point that caused the bug, add it now
+  (ask yourself: would this log have caught the bug earlier?).
+- Confirm ERROR logs include the exception, `request_id`, and the ID of the affected resource.
+- Confirm the correlation ID for requests passing through the fixed code is consistent end-to-end across the logs.
+- See your project's logging conventions doc for details.
+
+### 7. Get a review
+
+Run a review using the same parallel Workflow execution as `/code-review` (Mode A).
+
+1. Identify the changed files with `git diff HEAD --name-only`, and select reviewers per `/code-review`'s
+   "Selecting reviewers" table (`code-reviewer` and `silent-failure-hunter` are always included).
+2. Invoke the Workflow script described in `/code-review` and run the selected reviewers in parallel.
+3. Review the returned `findings` and resolve every CRITICAL / HIGH finding.
+   After making the fixes, re-run step 6's checks (regression test green, no regressions).
+
+### 8. Verify before declaring done (no claims without evidence)
+
+**Iron rule: run the verification commands and read the output before claiming completion.**
+
+"Should pass," "probably fine," "I don't think there's a problem" are guesses, not claims.
+Before crossing the commit gate, actually run the following **in this conversation** and confirm:
+
+| Claim | Required evidence |
+|---|---|
+| Tests pass | Ran the test command and saw zero failures in the output |
+| Regression test went red then green | Ran both the pre-fix red and the post-fix green and confirmed each |
+| Build passes | Ran the build command and saw exit code 0 |
+| The bug is fixed | Confirmed the operation/test that reproduces the original symptom now passes |
+| No regressions | Ran the existing test suite and confirmed no failures |
+
+All of the following are prohibited:
+
+- Claiming completion with phrases like "should pass," "probably," "I believe"
+- Claiming something "passes" based on a previous run (a stale result is not evidence)
+- Trusting a subagent's "done successfully" report without verifying it yourself
+- Reporting partial verification (only some tests) as complete verification
+- Skipping verification because you're tired or in a hurry
+
+### 9. Commit and clean up the worktree (commit gate)
+
+- Present a summary of the diff and a proposed commit message, and wait for the user's confirmation.
+- Commit only once confirmation is given.
+- Follow the project's existing conventions (commit log style, etc.) for message format and granularity.
+
+After committing, present the user with these four options.
+
+```
+The fix is complete. What would you like to do with this change?
+
+1. Merge it into <base branch> locally
+2. Push and open a Pull Request
+3. Keep this branch as-is (handle it later)
+4. Discard this work
+```
+
+Handle each choice as follows.
+
+**1. Local merge**
+
+```bash
+# Move out of the worktree (to the main repo root) before running this
+cd "$MAIN_ROOT"
+git checkout <base-branch>
+git pull
+git merge <fix-branch>
+# Run the test suite after merging to confirm no regression
+git worktree remove <worktree-path>
+git worktree prune
+git branch -d <fix-branch>
+```
+
+**2. Open a PR**
+
+```bash
+git push -u origin <fix-branch>
+gh pr create --base <base-branch> --head <fix-branch> \
+  --title "<fix title>" --body "<summary of the fix and root cause>"
+# Don't remove the worktree — it's needed for handling PR feedback
+```
+
+**3. Keep as-is**
+
+Leave both the worktree and the branch in place. Tell the user the path and stop.
+
+**4. Discard**
+
+Ask the user to type `discard` first, and only proceed once confirmed.
+
+```bash
+cd "$MAIN_ROOT"
+git worktree remove <worktree-path>
+git worktree prune
+git branch -D <fix-branch>
+```
+
+**Order and prohibitions to observe**
+
+- Never run `git worktree remove` from inside the worktree (always move to the main repo root first).
+- Run `git branch -d` **after** `git worktree remove` (the reverse order fails).
+- Don't remove the worktree before the merge (confirm the merge succeeded first).
+- Don't remove the worktree after creating a PR (option 2).
+
+## Verification checklist
+
+Before reporting completion, confirm all of the following.
+
+- [ ] Identified the root cause at the code level before fixing (not a guess).
+- [ ] Checked the affected code's test coverage. If it was inadequate, added tests first, got them reviewed, and only then moved to the next step.
+- [ ] Wrote the test before writing the fix code (if the fix was accidentally written first, it was discarded and redone).
+- [ ] Confirmed the regression test was red before the fix and green after.
+- [ ] No regressions in the existing test suite (including E2E tests, if present).
+- [ ] If the fix spans multiple repositories, ran the test suite in every changed repository and confirmed no regression.
+- [ ] Fixed the root cause rather than hiding the symptom.
+- [ ] Resolved every CRITICAL / HIGH review finding.
+- [ ] Ran verification commands and read the output before claiming completion (didn't guess "should pass").
+- [ ] Committed only after the user's confirmation (left uncommitted if not yet confirmed).
+- [ ] Presented the four-option worktree cleanup and executed it in the correct order (remove worktree → delete branch) for the chosen option.
+- [ ] If a logging convention applies: filled in logging that was missing at the point of the bug, and confirmed ERROR logs include the correlation ID and affected resource ID.

package/dist/plugin/commands/learn-eval.md

@@ -0,0 +1,94 @@
+---
+description: Evaluate a session's insights through a quality gate, keeping only records worth saving
+argument-hint: "[optional topic to focus the extraction on]"
+---
+
+# /learn-eval - Record insights through a quality gate
+
+The strict version of /learn. After extracting insights, it runs them through a quality gate to keep
+memory and CLAUDE.md from bloating with low-value records. If you just want a quick save, use /learn instead.
+
+## Procedure
+
+### 1. Extract insights
+
+Reflect on the session and surface candidate insights worth reusing: root causes and fixes for errors,
+non-obvious debugging techniques, library quirks or version-specific workarounds, and project-specific
+conventions or design decisions. Trivial fixes and one-off incidents don't count as candidates.
+If an argument is given, narrow this to insights related to that topic.
+
+### 2. Mandatory checks (run for every candidate)
+
+For each candidate, always confirm the following. None of these may be skipped.
+
+1. Search existing memory: search both global and project memory files for the same or a near-duplicate record.
+2. Cross-check the index: check MEMORY.md and each level's CLAUDE.md for duplicate content.
+3. Consider appending instead: decide whether appending to/updating an existing record would be better than creating a new one.
+4. Confirm reusability: confirm there's a concrete, plausible future scenario where this would actually get referenced.
+
+### 3. Quality evaluation
+
+Score each candidate on the following four dimensions, each as High/Medium/Low.
+
+- Concreteness: does it include ready-to-use code, commands, or steps? Or is it just an abstract lesson?
+- Focus: is it scoped to one record, one pattern? Or does it mix multiple topics?
+- Novelty: is this information not already in an existing record or in general official documentation?
+- Reuse likelihood: is it realistic that the same situation will recur?
+
+### 4. Verdict
+
+Based on the evaluation, assign each candidate one of the following four verdicts.
+
+| Verdict | Rough criteria |
+|------|-----------|
+| Save | Passes the mandatory checks, and all four dimensions score Medium or higher |
+| Improve then save | Has value, but concreteness or focus scores low. Re-evaluate once after improving. |
+| Merge into an existing record | Useful, but overlaps or nearly duplicates an existing record |
+| Discard | Novelty or reuse likelihood is low — not worth recording |
+
+Re-evaluation for "improve then save" happens once only. If it still doesn't meet the bar after that, discard it.
+
+### 5. Present the check results
+
+Present the results for each candidate in the following format.
+
+```
+Insight: [name]
+Verdict: [Save / Improve then save / Merge into an existing record / Discard]
+Scores: Concreteness=[High/Medium/Low] Focus=[High/Medium/Low] Novelty=[High/Medium/Low] Reuse likelihood=[High/Medium/Low]
+Duplicate check: [None / Yes (name of the existing record)]
+Rationale: [1-2 sentence basis for the verdict]
+```
+
+### 6. Confirmation flow per verdict
+
+- Save: present the draft record and destination to the user, and save after approval.
+- Improve then save: re-evaluate the improved draft, and proceed to the save flow once it passes.
+- Merge into an existing record: present the target record and the content to append, and update after approval.
+- Discard: just explain why. Don't write anything to a file.
+
+### 7. Saving
+
+Save to the memory feature (individual memory files plus the MEMORY.md index) if available; otherwise
+append to the appropriate section of the CLAUDE.md at the applicable level.
+Decide the level (global vs. project) by whether it would help in other projects too — when in doubt, go global.
+
+Record format:
+
+```markdown
+## [Insight name]
+
+- Applies when: which environment, version, or situation this holds for
+- Problem: what happened
+- Solution: concrete steps, code, or commands
+- When to use this: what future situation should trigger looking this up
+- Recorded: YYYY-MM-DD
+```
+
+## Notes
+
+- Don't save things "just in case." When in doubt, lean toward discarding, and state why.
+- Respect the user's objection to a verdict — if the user wants something saved, they can override the verdict.
+- Even if every candidate gets discarded, report that outcome and the reasons as a list.
+
+Note: the extraction criteria, storage-level rules, and record format are intentionally duplicated between learn.md and learn-eval.md, since each command needs to be self-contained. Keep both files in sync when changing either.

package/dist/plugin/commands/learn.md

@@ -0,0 +1,84 @@
+---
+description: Reflect on the session and record reusable insights for future sessions
+argument-hint: "[optional topic to focus the extraction on]"
+---
+
+# /learn - Record insights from a session
+
+Reflect on the current session and extract insights worth saving for reuse in future sessions.
+If an argument is given, narrow the extraction to insights related to that topic.
+
+## Procedure
+
+### 1. Reflect on the session and extract insights
+
+Look back over the whole session and surface anything that fits these categories.
+
+What to extract:
+- Root causes and fixes for errors (things you could act on immediately if this recurs)
+- Non-obvious debugging techniques (an investigation approach or way of narrowing down the cause that was distinctive)
+- Library quirks or version-specific workarounds
+- Project-specific conventions or design decisions (including context that isn't obvious just from reading the code)
+
+What to exclude:
+- Trivial fixes like typo corrections
+- One-off incidents (an outage at a specific time, a transient glitch in a specific environment)
+- General knowledge that's obvious from official documentation
+
+If nothing qualifies, report "No insights worth recording were found" and stop.
+
+### 2. Decide the storage level
+
+For each insight, judge it against "would this help in other projects too?"
+
+- Useful in other projects → global (user-level)
+- Only meaningful in this project → project-level
+- When in doubt → save it globally
+
+### 3. Decide where to save it
+
+Check whether a memory feature (individual memory files plus a MEMORY.md index) is available.
+
+- If available: create an individual memory file for each insight, and add a one-line entry to the MEMORY.md index.
+- If not available: append to the appropriate section of the CLAUDE.md at the level decided in step 2.
+  If no matching section exists, create a new "Lessons learned" section.
+
+### 4. Check for duplicates
+
+Before saving, search existing memory files, MEMORY.md, and CLAUDE.md for the same or similar content
+already on record. If a duplicate or near-duplicate is found, propose appending to/updating the existing
+record instead of creating a new one.
+
+### 5. Draft the record
+
+Draft using the following format.
+
+```markdown
+## [Insight name (concise and easy to search for)]
+
+- Applies when: which environment, version, or situation this holds for
+- Problem: what happened, what the symptoms were
+- Solution: concrete steps, code, or commands
+- When to use this: what future situation should trigger looking this up
+- Recorded: YYYY-MM-DD
+```
+
+Prefer including code or commands in the solution that can be copied and used as-is.
+
+### 6. Confirm with the user and save
+
+Present the draft and the intended location (level and file) to the user and get confirmation.
+
+- If approved: save it and report the path where it was saved.
+- If changes are requested: revise and re-present.
+- If deemed unnecessary: finish without saving.
+
+If there are multiple insights, present them as a list and let the user choose which to save.
+
+## Notes
+
+- One record, one pattern. Split multiple insights into separate records.
+- Don't record speculation — only facts actually confirmed during the session.
+- For a stricter quality gate, use /learn-eval instead.
+
+Note: the extraction criteria, storage-level rules, and record format are intentionally duplicated between learn.md and learn-eval.md, since each command needs to be self-contained. Keep both files in sync when changing either.