@anhth2/spec-driven-dev-plugin 0.8.0 → 0.9.1

package/commands/learn.md

@@ -0,0 +1,554 @@
+# /learn — Record a Project Lesson (Guardrail)
+
+Capture a mistake the AI keeps making so it is **not repeated**. The lesson is stored in this
+project's lessons file and loaded into context at the start of every command.
+
+Usage: `/learn {free-text}` — ideally phrased as "AI does X, should do Y".
+Example: `/learn AI keeps calling the repository directly from controllers — it must go through the service layer`
+
+> This is **project memory**, not model fine-tuning. The lesson becomes an active guardrail by
+> being injected into context on every run (see context-loader Step 6.7).
+
+## Gate
+# Gate — Universal Entry Procedure
+
+Every command must execute this gate before proceeding with its specific logic.
+
+## Step 0 — Sub-Agent Mode Check
+
+Before anything else, check if `$ARGUMENTS` is a JSON payload from an orchestrator:
+
+1. Attempt to parse `$ARGUMENTS` as JSON.
+2. If it parses successfully **and** contains `"_agent_mode": true`:
+   - **Skip Steps 1, 2, and 3 of this Gate entirely.**
+   - Set target file = `payload.target_file`
+   - Set loaded context = `payload.context` (do NOT run context-loader.md)
+   - Set UC scope = `payload.uc_id` (process only this UC)
+   - Set line range = `payload.uc_section` (read only that PRD section)
+   - Proceed directly to the command-specific logic.
+3. If `$ARGUMENTS` is not JSON or `_agent_mode` is absent → continue to Step 1 (normal mode).
+
+## Step 0-B — Model Check
+
+*Skip this step if `_agent_mode: true` (sub-agent — orchestrator already validated).*
+
+Complex generation and review commands require strong reasoning.
+Using a smaller model risks missed edge cases, incomplete spec analysis, and architecture violations.
+
+Display and wait for response:
+
+```
+⚙️  MODEL CHECK
+──────────────────────────────────────────────────────────────────
+  Recommended  : claude-opus-4 (or latest Opus model)
+  Why needed   : Spec analysis, architecture review, code generation
+                 require deep reasoning. Smaller models miss edge cases.
+
+  To switch in Claude Code:
+    • Settings → Model → select "claude-opus"
+    • or: /model → choose claude-opus
+
+  Running on claude-opus?
+    Y — yes, on claude-opus → proceed
+    S — skip check (I accept lower quality risk with current model)
+──────────────────────────────────────────────────────────────────
+```
+
+- "Y" → proceed to Step 1.
+- "S" → proceed to Step 1 (user accepts risk, add ⚠️ to final report).
+- "N" or anything else → **STOP.** Output: "Please switch to claude-opus, then re-run this command."
+
+## Step 1 — Resolve Target File
+
+1. If `$ARGUMENTS` is provided and points to an existing file → use it directly as the target.
+2. If `$ARGUMENTS` is a UC-ID, ticket ID, or partial name → search for matching files in the relevant directory.
+3. If `$ARGUMENTS` is empty or no match found:
+   - List files in the relevant directory for this command (e.g., `specs/prd/**/*.md` for PRD commands, `specs/bdd/**/*.feature` for BDD commands).
+   - Present the list to the user and ask: "Which file do you want to work with? (Enter number or filename)"
+   - Wait for user selection before continuing.
+
+## Step 2 — Execute Context Loader
+
+Load all project context by following the procedure in `steps/context-loader.md`.
+Store all loaded context in memory for use throughout this command session.
+
+## Step 3 — CHECKPOINT
+
+After completing Steps 1 and 2, display a summary and wait for confirmation:
+
+```
+CHECKPOINT
+-----------
+Target     : {resolved file path}
+Project    : {project.name from project-context.yaml}
+Tech stack : {language} / {framework}
+Module     : {module if set, else "not configured"}
+Domains    : {comma-separated domain list}
+
+Proceed? (Y/N)
+```
+
+Wait for explicit "Y" or "N" from the user before continuing.
+- "Y" → proceed to the command-specific steps below.
+- "N" → stop and ask what the user wants to change.
+
+
+*Note: For this command — skip Gate Step 1 (no target file). The "target" is the lesson text in `$ARGUMENTS`. Run the model check and context loading, then proceed.*
+
+## Context
+# Context Loader — Load All Project Context
+
+Execute these steps in order. Store everything in memory for the duration of the command session.
+
+**Priority guide (anti-lost-in-middle):**
+- Steps 1–2 are PROJECT-CONFIG — loaded first, resolve all paths and metadata.
+- Step 3 is CRITICAL — architecture + coding standards, the highest-priority facts for generation.
+- Step 4 is SAFETY — data protection rules, enforced silently for the entire session.
+- Steps 5–6 are DOMAIN KNOWLEDGE — terminology and entity definitions.
+- Step 7 is the WORKING MEMORY RECAP — locks critical facts into the top of working memory.
+
+---
+
+## Step 1 — [PROJECT-CONFIG] Load project-context.yaml
+
+Read `.agent/project-context.yaml`. Extract and store:
+
+**Tech Stack:**
+- `tech_stack.language` → active language (e.g., Java 17, TypeScript, C#, Go)
+- `tech_stack.framework` → active framework (e.g., Spring Boot 3.2, Angular 17, .NET 8)
+- `tech_stack.build_tool` → build tool (e.g., Maven, npm, dotnet, go)
+- `tech_stack.test_framework` → test framework (e.g., JUnit 5 + Mockito, Jest, xUnit)
+- `tech_stack.database` → database (e.g., PostgreSQL, MySQL, MongoDB)
+- `tech_stack.module` → active module profile (e.g., java-spring, angular, dotnet, golang, context-engineering)
+
+**Conventions:**
+- `conventions.build_command` → how to compile/build
+- `conventions.test_command` → how to run tests
+- `conventions.service_run` → how to start the service
+- `conventions.ticket_prefix` → ticket ID prefix (e.g., PROJ, FEAT, UC)
+
+**Domains:**
+- `domains` → list of active business domains
+
+**Paths (if present):**
+- `paths.specs_dir` → BDD specs root
+- `paths.prd_dir` → PRD documents root
+- `paths.refinement_dir` → findings/review output dir
+- `paths.product_definitions_dir` → product definitions root
+- `paths.domain_knowledge_dir` → domain knowledge root
+- `paths.business_dictionary` → path to business-dictionary.md
+- `paths.core_entities` → path to core-entities.md
+- `paths.tech_docs_dir` → technical documentation root
+- `paths.trace_dir` → trace state directory
+- `paths.design_spec_dir` → Design Spec documents root (FE/App only)
+
+If `paths` section is absent, use these defaults:
+- `specs_dir` = `specs/bdd`
+- `prd_dir` = `specs/prd`
+- `refinement_dir` = `.agent/review`
+- `product_definitions_dir` = `specs/product-definition`
+- `domain_knowledge_dir` = `specs/domain-knowledge`
+- `business_dictionary` = `specs/domain-knowledge/business-dictionary.md`
+- `core_entities` = `specs/domain-knowledge/core-entities.md`
+- `tech_docs_dir` = `specs/tech-docs`
+- `trace_dir` = `.trace`
+- `design_spec_dir` = `specs/design-spec`
+
+If `tech_stack.module` is set, also load `.agent/modules/{module}/stack-profile.yaml` if it exists.
+
+---
+
+## Step 1.5 — [SERVICE ROUTING] Resolve service paths (umbrella mode)
+
+*Skip this step entirely if `setup.mode` is not `"umbrella"` and `services` section is absent from project-context.yaml.*
+
+If `services` section is present:
+
+**1. Detect active domain** (in priority order):
+- Read `@trace.domain` from target file frontmatter (if Gate loaded a target file)
+- Extract from target file path: segment immediately after `prd_dir` base path  
+  *(e.g., `specs/prd/user/FEAT-01.md` → domain = `user`)*
+- If `$ARGUMENTS` contains a path, extract the segment after `prd_dir`
+
+**2. Route to service** — if active domain matches a key in `services`:
+- Override `paths.specs_dir` → `services.{domain}.specs_dir`
+- Override `paths.tech_docs_dir` → `services.{domain}.tech_docs_dir`
+- Store `active_service` = `services.{domain}.path`
+- Store `active_service_module` = `services.{domain}.module`
+- If service has its own `module` → use it as `active_module` (overrides `tech_stack.module`)
+
+**3. Fallback** — if domain not detected or no matching service key:
+- Keep default paths from Step 1
+- Set `active_service = unresolved`
+
+**4. Spec source auto-override** — if `setup.spec_source` is set AND the corresponding path was not already explicitly set in `paths:`:
+- Override `paths.prd_dir` → `{spec_source}/specs/prd`
+- Override `paths.design_spec_dir` → `{spec_source}/specs/design-spec`
+- Override `paths.domain_knowledge_dir` → `{spec_source}/specs/domain-knowledge`
+- Override `paths.business_dictionary` → `{spec_source}/specs/domain-knowledge/business-dictionary.md`
+- Override `paths.core_entities` → `{spec_source}/specs/domain-knowledge/core-entities.md`
+- Override `paths.bug_reports_dir` → `{spec_source}/feedback/bug-reports`
+- Override `paths.bdd_proposals_dir` → `{spec_source}/feedback/bdd-proposals`
+
+> **Why under `spec_source`:** tester feedback (`/report-bug`, `/propose-scenario`) must land in the **shared spec repo** so PO/Dev see it when they `/sync`. In single-service mode (no `spec_source`), these default to `feedback/bug-reports` and `feedback/bdd-proposals` at repo root — still shared, same repo.
+
+---
+
+## Step 1.6 — [SERVICE CONVENTIONS] Load service-specific conventions (umbrella mode)
+
+*Skip this step entirely if `active_service` is `"unresolved"` or context is single-service mode.*
+
+When `active_service` has been resolved to a real path in Step 1.5 (e.g., `user-service/`):
+
+**1. Locate service config** — try in priority order:
+- `{active_service}/.agent/project-context.yaml`
+- `{active_service}/project-context.yaml`
+
+**2. If found, override with service-specific values:**
+
+| Variable | Source |
+|----------|--------|
+| `conventions.test_command` | service's `conventions.test_command` |
+| `conventions.build_command` | service's `conventions.build_command` |
+| `paths.trace_dir` | `{active_service}/{service paths.trace_dir}` — default: `{active_service}/.trace` |
+| `paths.specs_dir` | `{active_service}/{service paths.specs_dir}` (if set in service config, else keep Step 1.5 override) |
+
+**3. Store** `service_root = {active_service}` as the working directory anchor for all downstream commands:
+- Shell commands (`/run-tests`, `/generate-tests`) run **from within** `service_root`
+- File write operations (test files, trace TSVs) use paths **relative to** `service_root`
+
+**4. If service config not found** — keep umbrella defaults, still set `service_root = {active_service}` (path anchor is always needed even without a config override).
+
+---
+
+## Step 2 — [PROJECT-CONFIG] Load module stack profile (conditional)
+
+If `tech_stack.module` is set, read `.agent/modules/{module}/stack-profile.yaml`.
+Merge framework-specific conventions (layer patterns, test patterns, naming rules) into the loaded context.
+If the file does not exist → skip silently.
+
+---
+
+## Step 3 — [CRITICAL] Load CLAUDE.md
+
+*This is the highest-priority context — it defines HOW to write code and documents for this project.*
+
+Read `CLAUDE.md`. Extract and store:
+
+- **§1 Project Overview** → project name, language, framework, build/test commands, domains
+- **§2 Architecture** → layer order (e.g., Controller → Facade → Service → Repository), architectural rules
+- **§3 Coding Standards** → naming conventions (classes, methods), response wrapper type, forbidden patterns
+- **§5 Error Handling** → exception types, HTTP status code mapping, not-found exception class name
+- **§7 Git Conventions** → branch naming pattern, commit message format
+
+If `CLAUDE.md` does not exist → note it as missing and continue with project-context.yaml data only.
+
+---
+
+## Step 4 — [SAFETY] Load Data Protection Rules
+
+Read `.agent/rules/data-protection.md` (or `rules/data-protection.md` from the framework installation).
+
+Store the sensitive file patterns — you must **never** read, write, display, or reference content from files matching those patterns for the entire session.
+
+If neither file exists → apply built-in defaults: never access `.env*`, `*.key`, `*.pem`, `*secret*`, `*password*`, `*credential*`.
+
+---
+
+## Step 5 — [DOMAIN] Load Business Dictionary (conditional)
+
+Check if the business dictionary file exists (use `paths.business_dictionary` resolved in Step 1).
+
+If it exists, read it and extract:
+- **Canonical Terms** → complete list of approved terms and their definitions
+- **Banned Terms** → complete list of banned terms and their canonical replacements
+- **Status / Enum Registry** → allowed enum values per entity
+
+Store the banned terms list for **active enforcement** throughout the command session:
+- When generating any text (PRD, BDD, code comments, tech docs), verify no banned terms appear
+- Replace banned terms with their canonical equivalents automatically
+
+If the file does not exist → skip silently. Do not warn or block.
+
+---
+
+## Step 6 — [DOMAIN] Load Core Entities (conditional)
+
+Check if the core entities file exists at `paths.core_entities` (resolved in Step 1).
+Default path: `specs/domain-knowledge/core-entities.md`.
+
+If it exists, read it and store:
+- **Entity catalog** → for each entity: its name, purpose, owner service, key fields (name + type), business invariants, and relationships
+- **Field name registry** → canonical field names to use in generated code and documents
+- **Relationship map** → how entities relate to each other (1:N, N:N, embedded, etc.)
+
+**How to use this catalog:**
+- When generating code: use the field names, types, and relationships defined here — do NOT infer from existing code
+- When generating PRD/BDD: reference entity names from this catalog for consistency
+- When generating tech-docs: use this catalog as the source-of-truth for entity definitions
+
+If the file does not exist → skip silently.
+
+---
+
+## Step 6.5 — [PLATFORM] Derive active_module and platform_type
+
+Using `tech_stack.module` loaded in Step 1, derive and store two variables for use by all downstream commands:
+
+```
+active_module = tech_stack.module   (e.g. "java-spring", "react", "flutter")
+```
+
+| `platform_type` | Modules |
+|---|---|
+| `backend` | `java-spring`, `golang`, `dotnet`, `php-laravel`, `context-engineering` |
+| `web-frontend` | `react`, `nextjs`, `vue`, `nuxt`, `angular` |
+| `mobile` | `flutter`, `react-native`, `ios-swiftui`, `android-compose` |
+
+If `tech_stack.module` is blank or not recognized → set `platform_type = "unknown"` and flag as ⚠️ in the Step 7 recap.
+
+These two variables (`active_module`, `platform_type`) are the canonical source for all branching logic in commands that need platform-specific behavior (generate-tests, debug, fix-bug, smoke-test).
+
+---
+
+## Step 6.7 — [GUARDRAILS] Load Project Lessons (conditional)
+
+*Accumulated mistakes the AI must not repeat in this project. These are added over time via `/learn`
+or accepted during `/review-code`, `/fix-bug`, `/debug`.*
+
+Resolve the lessons file path:
+- Use `paths.lessons_file` if set (may be service-overridden in umbrella mode, Step 1.6)
+- Else default `specs/domain-knowledge/lessons-learned.md`
+- In umbrella/service mode (when `service_root` is set), if `paths.lessons_file` is unset, default to `{service_root}/.agent/project-lessons.md`
+
+If the file exists, read it and store ALL lessons as **ACTIVE GUARDRAILS** for the session:
+- Treat each lesson's **Rule** as a hard constraint — same priority as CLAUDE.md coding standards (Step 3).
+- Before generating or modifying any artifact (PRD, BDD, tech-doc, code, test), check the output against every lesson whose `category` matches the current command AND whose `scope` matches the target (domain / file).
+- If a generated output would violate a lesson → correct it **before** presenting, and note which lesson (`L-NNN`) was applied.
+
+If the file does not exist → skip silently (no lessons captured yet).
+
+---
+
+## Step 7 — [RECAP] Working Memory Recap (anti-lost-in-middle)
+
+After loading all context, synthesize and output a compact summary block.
+This recap ensures the most critical facts are stated at the END of context loading
+(recency effect — freshest in working memory when the task begins).
+
+Output exactly this block:
+```
+[CTX LOADED]
+Stack     : {language} / {framework} / {database}
+Platform  : {active_module} ({platform_type})
+Layers    : {layer order from CLAUDE.md §2, e.g., Controller → Facade → Service → Repository}
+Ticket    : {ticket_prefix}-
+Dict      : {loaded — N canonical terms, M banned terms | missing}
+Entities  : {loaded — EntityA, EntityB, EntityC | missing}
+Lessons   : {loaded — N guardrails | none yet}
+Service   : {active_service} ({active_service_module}) | single-service
+Svc Root  : {service_root} — conventions + trace_dir loaded from service config | —
+Status    : {FULL | PARTIAL — missing: CLAUDE.md / business-dict / core-entities | MINIMAL}
+```
+
+If any CRITICAL file is missing (CLAUDE.md), flag it clearly so the user can decide whether to proceed.
+
+---
+
+## Context Load Complete
+
+After completing all steps, you have loaded:
+- Project identity, tech stack, module conventions
+- Architecture rules and layer order  ← **[CRITICAL — hold in working memory]**
+- Coding standards and naming conventions  ← **[CRITICAL — hold in working memory]**
+- Data protection rules (sensitive file patterns to never access)
+- Terminology rules with banned-term list  ← **[DOMAIN — apply to every generated word]**
+- Entity catalog (field names, types, invariants)  ← **[DOMAIN — use for code generation]**
+- All configured paths
+
+Proceed to the next step of the calling command.
+
+
+---
+
+## Step 1 — Parse the Lesson
+
+Read `$ARGUMENTS` as a free-text description.
+
+Split it into a **mistake** (what the AI did wrong) and a **rule** (the imperative correction).
+- If `$ARGUMENTS` is empty or too vague to split, ask the user briefly:
+  ```
+  Record a project lesson. Answer 2 things:
+    1. What did the AI get wrong?  (the mistake)
+    2. What is the correct rule?   (imperative — "Always…/Never…")
+  ```
+- Infer `category` (code-gen | bdd | tech-docs | tests | prd | general) and `scope` (domain / file glob / all)
+  from the description. If ambiguous, confirm with the user in one line.
+
+Show the parsed lesson and ask `Save this lesson? (Y/N)` before writing.
+
+## Step 2 — Capture
+
+# Capture Lesson — Record a Recurring Mistake as a Guardrail
+
+Reusable procedure to persist a "lesson" so the AI does not repeat a mistake in this project.
+Used by `/learn` (manual) and offered by `/review-code`, `/fix-bug`, `/debug` (auto).
+
+> **Project memory, not model training.** A lesson is plain text injected into context at the
+> start of every command (context-loader Step 6.7). Functionally this stops the repeat — the AI
+> sees the guardrail before it generates. No model weights change.
+
+## L1 — Resolve the lessons file
+
+Resolve `lessons_path` in this order:
+1. `paths.lessons_file` from loaded context (may be service-overridden in umbrella mode, Step 1.6)
+2. Default `specs/domain-knowledge/lessons-learned.md` (single-service)
+3. In umbrella/service mode (when `service_root` is set) default `{service_root}/.agent/project-lessons.md`
+
+## L2 — Build the lesson
+
+Gather these fields — from `$ARGUMENTS` (for `/learn`) or from the calling command's findings
+(for `/review-code`, `/fix-bug`, `/debug`):
+
+| Field | Meaning |
+|-------|---------|
+| `category` | one of: `code-gen` \| `bdd` \| `tech-docs` \| `tests` \| `prd` \| `general` |
+| `title` | short phrase naming the mistake |
+| `mistake` | concretely, what the AI did wrong |
+| `rule` | imperative correction — "Always …" / "Never …" — testable, not vague |
+| `scope` | where it applies: a domain, a file glob (e.g. `*Controller.*`), or `all` |
+| `source` | how captured: `/learn` \| `/review-code {UC-ID}` \| `/fix-bug {TICKET}` \| `/debug` |
+
+If `rule` is vague (e.g. "be careful"), rewrite it into a concrete, checkable instruction before saving.
+
+## L3 — De-duplicate
+
+Read existing lessons in `lessons_path`. If one already covers the same mistake:
+- **Refine** that entry (tighten the Rule, widen/narrow Scope, bump Date, append the new Source) — do NOT add a duplicate.
+
+Otherwise assign the next id `L-{NNN}` = (highest existing number + 1), zero-padded to 3 digits.
+
+## L4 — Write
+
+If `lessons_path` does not exist, create it with this header first:
+
+```markdown
+# Project Lessons — Learned Guardrails
+
+> Mistakes the AI must NOT repeat in this project. Loaded by context-loader at the start of
+> every command and treated as hard constraints (same priority as CLAUDE.md coding standards).
+> Add with /learn, or accept the prompt during /review-code, /fix-bug, /debug.
+> Commit this file so the whole team shares the guardrails.
+
+| Category | Applies to |
+|----------|-----------|
+| code-gen | /generate-code output |
+| bdd | /generate-bdd output |
+| tech-docs | /generate-tech-docs output |
+| tests | /generate-tests output |
+| prd | /generate-prd, /refine-prd output |
+| general | every command |
+
+---
+```
+
+Insert the new lesson directly under the `---` separator (**newest first**), in this exact shape:
+
+```markdown
+### L-{NNN} — [{category}] {title}
+- **Date**: {today YYYY-MM-DD}
+- **Scope**: {scope}
+- **Mistake**: {mistake}
+- **Rule**: {rule}
+- **Source**: {source}
+
+```
+
+## L5 — Confirm
+
+Print: `📝 Lesson {id} recorded → {lessons_path}  ([{category}] {title})`
+Then remind: `Commit {lessons_path} so the team shares this guardrail.`
+
+
+---
+
+## Output
+
+# Report Footer — Standard Command Output Format
+
+Every command report must end with this standard footer section.
+
+## Status Badge
+
+Choose one based on outcome:
+- `✅ Complete` — all steps succeeded, no issues found
+- `❌ Failed` — command could not complete due to a blocking error
+- `⚠️ Warnings` — completed with non-blocking issues that should be reviewed
+
+## Output Artifacts
+
+List every file created or modified by this command:
+```
+Output Artifacts:
+  {created|updated} {file-path} ({brief description})
+  {created|updated} {file-path} ({brief description})
+```
+
+If no files were written (e.g., review or analysis commands) → write `Output Artifacts: none (read-only)`.
+
+## Next Command Suggestion
+
+Suggest the logical next command based on workflow phase:
+
+| Current command         | Suggest next                                  |
+|-------------------------|-----------------------------------------------|
+| /setup-ai-first         | `/define-product` to start your first feature |
+| /define-product         | `/generate-prd {product-definition-file}`     |
+| /generate-prd           | `/refine-prd {prd-file}` then `/review-context {prd-file}` |
+| /refine-prd             | Open Review Board → update PRD → `/review-context {prd-file}` |
+| /review-context (PRD)   | FE/App: `/generate-design-spec {prd-file}` (then BDD after sign-off); BE: `/generate-bdd {prd-file}` directly; fix PRD if NEEDS_FIX |
+| /generate-design-spec   | Designer review → Figma links confirmed → PO + Designer sign-off → `/generate-bdd {prd-file}` |
+| /generate-bdd           | `/review-context {feature-file}` to verify coverage |
+| /review-context (BDD)   | `/generate-tech-docs {UC-ID}` if APPROVED; regenerate if NEEDS_FIX |
+| /generate-tech-docs     | `/review-tech-docs {tech-design-file}`        |
+| /review-tech-docs       | `/generate-code {feature-file}` if APPROVED; fix doc if NEEDS_FIX |
+| /generate-code          | First gen → `/review-code {UC-ID}`; re-gen → `/generate-tests {UC-ID}` |
+| /generate-tests         | `/run-tests {UC-ID}`                          |
+| /run-tests (passing)    | `/review-code {UC-ID}`                        |
+| /run-tests (failing)    | `/fix-bug {ticket-id}` or `/debug {error}`    |
+| /review-code            | `/smoke-test {UC-ID}` or create PR            |
+| /smoke-test             | Create PR and link to ticket                  |
+| /validate-traces        | DRIFT/UNTRACKED → `/generate-code {UC-ID}`; GAP → `/generate-tests {UC-ID}`; all OK → create PR |
+| /fix-bug                | Create PR and link to ticket                  |
+| /debug                  | `/fix-bug {ticket-id}` if fix needed          |
+| /report-bug             | Send to dev (`/fix-bug {BUG-ID}`); if coverage gap → `/propose-scenario {UC-ID}` |
+| /propose-scenario       | Notify PO/Dev to review the proposal in `feedback/bdd-proposals/` |
+| /learn                  | Continue working — lesson applies on next command |
+| /sync                   | `/validate-traces` for full coverage; act on any `📥 tester feedback` surfaced |
+| /update-framework       | Review `git diff .agent/`, commit; `/sync` for project content |
+
+Format the footer as:
+```
+---
+Status : {badge}
+{Output Artifacts block}
+Next   : {suggested command with example arguments}
+```
+
+
+```
+/learn — lesson recorded
+
+📝 {id} — [{category}] {title}
+   Rule  : {rule}
+   Scope : {scope}
+   File  : {lessons_path}
+
+This guardrail is now loaded at the start of every command.
+Commit {lessons_path} so your team shares it.
+
+---
+Status : ✅ Complete
+Output Artifacts: updated {lessons_path}
+Next   : continue working — the AI will respect this lesson from now on
+```

package/commands/learn.tmpl

@@ -0,0 +1,63 @@
+# /learn — Record a Project Lesson (Guardrail)
+
+Capture a mistake the AI keeps making so it is **not repeated**. The lesson is stored in this
+project's lessons file and loaded into context at the start of every command.
+
+Usage: `/learn {free-text}` — ideally phrased as "AI does X, should do Y".
+Example: `/learn AI keeps calling the repository directly from controllers — it must go through the service layer`
+
+> This is **project memory**, not model fine-tuning. The lesson becomes an active guardrail by
+> being injected into context on every run (see context-loader Step 6.7).
+
+## Gate
+{{include:steps/gate.md}}
+
+*Note: For this command — skip Gate Step 1 (no target file). The "target" is the lesson text in `$ARGUMENTS`. Run the model check and context loading, then proceed.*
+
+## Context
+{{include:steps/context-loader.md}}
+
+---
+
+## Step 1 — Parse the Lesson
+
+Read `$ARGUMENTS` as a free-text description.
+
+Split it into a **mistake** (what the AI did wrong) and a **rule** (the imperative correction).
+- If `$ARGUMENTS` is empty or too vague to split, ask the user briefly:
+  ```
+  Record a project lesson. Answer 2 things:
+    1. What did the AI get wrong?  (the mistake)
+    2. What is the correct rule?   (imperative — "Always…/Never…")
+  ```
+- Infer `category` (code-gen | bdd | tech-docs | tests | prd | general) and `scope` (domain / file glob / all)
+  from the description. If ambiguous, confirm with the user in one line.
+
+Show the parsed lesson and ask `Save this lesson? (Y/N)` before writing.
+
+## Step 2 — Capture
+
+{{include:steps/capture-lesson.md}}
+
+---
+
+## Output
+
+{{include:steps/report-footer.md}}
+
+```
+/learn — lesson recorded
+
+📝 {id} — [{category}] {title}
+   Rule  : {rule}
+   Scope : {scope}
+   File  : {lessons_path}
+
+This guardrail is now loaded at the start of every command.
+Commit {lessons_path} so your team shares it.
+
+---
+Status : ✅ Complete
+Output Artifacts: updated {lessons_path}
+Next   : continue working — the AI will respect this lesson from now on
+```