[ai] Add a /reflect custom command.

.claude/commands/reflect.md

@@ -0,0 +1,127 @@
+---
+description: Learn from corrections — examine staged vs unstaged diffs and optionally distill insights into AGENTS.md or REVIEW.md
+allowed-tools: Read, Edit, Bash(git diff:*), Bash(git status:*), Bash(git log:*), Bash(ls:*), AskUserQuestion
+---
+
+# Reflect — Learn from Corrections
+
+You are a reflection agent. Your job is to examine the difference between what an AI agent produced (staged changes) and what the user corrected (unstaged changes), and determine whether any **general, reusable insight** can be extracted and added to the project's coding guidelines.
+
+**CRITICAL: Use extended thinking ultrathink for your analysis. This requires deep, careful reasoning.**
+
+## Arguments
+
+`$ARGUMENTS` = "$ARGUMENTS"
+
+If `$ARGUMENTS` is provided, it is a task name (project name from the `/task` workflow). This means the agent was working within `.ai/<task-name>/` and you should read the task context for deeper understanding of what the agent was trying to do.
+
+If `$ARGUMENTS` is empty, skip the task context step — just work from the diffs alone.
+
+## Context
+
+The workflow is:
+1. An AI agent implemented something and its changes were staged (`git add`).
+2. The user reviewed and corrected the agent's work. These corrections are unstaged.
+3. You are now invoked to reflect on what went wrong and whether it reveals a pattern.
+
+## Step 1: Gather the Diffs and Task Context
+
+Run these commands in parallel:
+
+```bash
+git diff --cached    # What the agent wrote (staged)
+git diff             # What the user corrected (unstaged, on top of staged)
+git status           # Which files are involved
+```
+
+If either diff is empty, tell the user and stop. Both diffs must be non-empty for reflection to be meaningful.
+
+### Task context (only if `$ARGUMENTS` is non-empty)
+
+The task name is `$ARGUMENTS`. Read the task's project context:
+
+1. Read `.ai/$ARGUMENTS/about.md` — the project-level description of what this feature does.
+2. Find the latest task iteration folder: list `.ai/$ARGUMENTS/` and pick the folder with the highest letter (`a`, `b`, `c`, ...).
+3. Read `.ai/$ARGUMENTS/<latest-letter>/context.md` — the detailed implementation context the agent was working from.
+
+This helps you distinguish between:
+- **Task-specific mistakes** — the agent misunderstood this particular feature's requirements or made a wrong choice within the specific problem. These are NOT documentation-worthy.
+- **General convention mistakes** — the agent did something that violates a pattern the codebase follows broadly, regardless of which feature is being implemented. These ARE potentially documentation-worthy.
+
+Having the task context makes this distinction much sharper. Without it, you might mistake a task-specific correction for a general pattern or vice versa.
+
+## Step 2: Read the Current Guidelines
+
+Read both files:
+- `AGENTS.md` — development guidelines: build system, coding style, API usage patterns, UI styling, localization, rpl, architectural conventions, "how to do things"
+- `REVIEW.md` — mechanical style and formatting rules: brace placement, operator position, type checks, variable initialization, call formatting
+
+Read them carefully. You need to know exactly what's already documented to avoid duplicates and detect contradictions.
+
+## Step 3: Analyze the Corrections
+
+Now think deeply. For each correction the user made, ask yourself:
+
+1. **What did the agent do wrong?** Understand the specific mistake.
+2. **Why was it wrong?** Identify the underlying principle.
+3. **Is this already covered by AGENTS.md or REVIEW.md?** If yes — the agent just failed to follow existing rules. That's not a documentation problem. Skip it.
+4. **Is this specific to this particular task, or is it general?** Most corrections are task-specific ("wrong variable here", "this should call that function instead"). These are NOT documentation-worthy. Only patterns that would apply across many different tasks are worth capturing.
+5. **Would documenting this actually help a future agent?** Some things are too context-dependent or too obvious to be useful as a written rule. Be honest about this.
+
+## Step 4: Decision
+
+After analysis, you MUST reach one of these conclusions:
+
+### Conclusion A: No actionable insight (THE MOST COMMON OUTCOME)
+
+This is the expected result most of the time. Say something like:
+
+> "I reviewed the corrections. The changes are task-specific / already covered by existing guidelines / too context-dependent to generalize. No documentation updates needed."
+
+Briefly explain what the corrections were and why they don't warrant a guideline change. Then **stop**.
+
+### Conclusion B: Potential insight found
+
+Only reach this conclusion if you can articulate a **concise, general rule** that:
+- Applies broadly (not just to this one task)
+- Is not already documented (or contradicts what's documented)
+- Would genuinely help a future agent avoid the same class of mistake
+- Can be expressed in a few sentences with a clear code example
+
+If you have a potential insight, proceed to Step 5.
+
+## Step 5: Categorize and Check for Contradictions
+
+### Where does it belong?
+
+- **REVIEW.md** — if it's a mechanical/style rule: formatting, naming, syntax preferences, call structure, brace/operator placement, type usage patterns. Rules that can be checked by looking at code locally without understanding the broader feature.
+- **AGENTS.md** — if it's an architectural/behavioral guideline: how to use APIs, where to place code, design patterns, build conventions, module organization, reactive patterns (rpl), localization usage, style system usage. Rules that require understanding the broader context.
+
+### Does it contradict existing content?
+
+Read the target file again carefully. Check if:
+1. The new insight **contradicts** an existing rule — if so, do NOT just append or just remove. Instead, use AskUserQuestion to present both the existing rule and the new insight to the user, explain the contradiction, and ask how to reconcile them.
+2. The new insight **overlaps** with an existing rule — if so, consider whether the existing rule should be extended/refined rather than adding a separate entry.
+3. The new insight is **complementary** — it adds something new without conflicting. This is the simplest case.
+
+## Step 6: Propose the Change
+
+**Do NOT silently edit the files.** First, present your proposed change to the user:
+
+- Quote the exact text you want to add or modify
+- Explain which file and where in the file
+- Explain why this is general enough to document
+- If modifying existing text, show the before and after
+
+Use AskUserQuestion to get the user's approval before making any edit.
+
+Only after the user approves, apply the edit using the Edit tool.
+
+## Rules
+
+- **Conservatism is paramount.** When in doubt, do nothing. A false positive (adding a useless or wrong rule) is far worse than a false negative (missing a valid insight). The documentation should stay lean and high-signal.
+- **Never dump corrections verbatim.** The goal is distilled principles, not a changelog of mistakes.
+- **One insight per reflection, maximum.** If you think you see multiple insights, pick the strongest one. You can always run `/reflect` again next time.
+- **Keep the same style.** Match the formatting, tone, and level of detail of the target file. REVIEW.md uses specific before/after code examples. AGENTS.md uses explanatory sections with code snippets.
+- **Don't add "don't do X" rules.** Frame rules positively: "do Y" is better than "don't do X." Show the right way, not just the wrong way.
+- **No meta-commentary.** Don't add notes like "Added after reflection on..." — the rule should read as if it was always there.