agents-templated 2.2.6 → 2.2.7

package/README.md

@@ -28,12 +28,14 @@ Agents Templated scaffolds your project with:
 - Deterministic slash-command standard in `AGENTS.MD` and modular contracts in `agents/commands/`
 - Implicit natural-language routing support (`slash-command-auto`) for non-technical prompts
 - New workflow/routing/hardening rule set:
-  - `.github/instructions/rules/intent-routing.mdc`
-  - `.github/instructions/rules/system-workflow.mdc`
-  - `.github/instructions/rules/hardening.mdc`
+  - `.claude/rules/intent-routing.md`
+  - `.claude/rules/system-workflow.md`
+  - `.claude/rules/hardening.md`
+  - `.claude/rules/lessons-learned.md`
 - New baseline skills:
   - `.github/skills/feature-delivery/`
   - `.github/skills/bug-triage/`
+  - `.github/skills/error-patterns/`
   - `.github/skills/app-hardening/`
 - Release and audit contracts now require hardening evidence when risk profile requires it
 
@@ -143,29 +145,33 @@ your-project/
 │   └── README.md                   # Human-readable setup guide
 │
 ├── .github/
-│   ├── instructions/                # Generated compatibility wrappers + rules
-│   │   ├── AGENTS.md
-│   │   └── rules/
-│   │   ├── core.mdc               # Core development principles
-│   │   ├── security.mdc           # Security patterns (CRITICAL)
-│   │   ├── testing.mdc            # Testing strategy
-│   │   ├── frontend.mdc           # Frontend patterns
-│   │   ├── database.mdc           # Database patterns
-│   │   ├── style.mdc              # Code style guidelines
-│   │   ├── workflows.mdc          # Workflow and quality gates
-│   │   ├── intent-routing.mdc     # Intent-to-command routing policy
-│   │   ├── system-workflow.mdc    # End-to-end delivery lifecycle gates
-│   │   └── hardening.mdc          # Hardening and obfuscation guidance
+│   ├── instructions/                # Compatibility pointer directory
 │   ├── skills/
 │   │   ├── find-skills/           # Skill discovery helper
 │   │   ├── feature-delivery/      # Scoped feature delivery workflow
 │   │   ├── bug-triage/            # Reproduction-first defect workflow
+│   │   ├── error-patterns/         # Persistent error-debugging memory workflow
 │   │   ├── app-hardening/         # Hardening and release-evidence workflow
 │   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
 │   │   ├── README.md              # Guide for creating custom skills
 │   │   └── [your-custom-skills]/  # Your project-specific skills
 │   └── copilot-instructions.md    # Compatibility shim for Copilot
 │
+├── .claude/
+│   ├── rules/                      # Canonical rules source
+│   │   ├── core.md
+│   │   ├── security.md
+│   │   ├── testing.md
+│   │   ├── frontend.md
+│   │   ├── database.md
+│   │   ├── style.md
+│   │   ├── workflows.md
+│   │   ├── intent-routing.md
+│   │   ├── system-workflow.md
+│   │   ├── hardening.md
+│   │   └── lessons-learned.md
+│   └── agents/                     # Optional subagents
+│
 ├── agents/                          # 🤖 Deterministic command contracts
 │   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
@@ -299,8 +305,8 @@ Skills define *how to execute specific tasks*, complementing rules that define *
 - **[AGENTS.MD](AGENTS.MD)** – AI assistant guide
 - **[agent-docs/ARCHITECTURE.md](agent-docs/ARCHITECTURE.md)** – Project architecture & tech stack guidance
 - **[.github/skills/README.md](.github/skills/README.md)** – Custom skills guide
-- **[.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)** – Security patterns (CRITICAL)
-- **[.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)** – Testing strategy
+- **[.claude/rules/security.md](.claude/rules/security.md)** – Security patterns (CRITICAL)
+- **[.claude/rules/testing.md](.claude/rules/testing.md)** – Testing strategy
 
 ### 5. Start Building
 
@@ -326,7 +332,7 @@ Your AI will follow the enterprise patterns automatically!
 ✅ Sanitize outputs to prevent injection attacks  
 ✅ Never expose sensitive data in error messages or logs
 
-**Reference**: [.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)
+**Reference**: [.claude/rules/security.md](.claude/rules/security.md)
 
 ### Testing Strategy
 
@@ -334,7 +340,7 @@ Your AI will follow the enterprise patterns automatically!
 - **15% Integration Tests** – API endpoints, database operations
 - **5% E2E Tests** – Critical user journeys
 
-**Reference**: [.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)
+**Reference**: [.claude/rules/testing.md](.claude/rules/testing.md)
 
 ### Agent-Based Architecture
 
@@ -421,7 +427,7 @@ await agentsTemplated.install('./my-project', {
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
-2. Update relevant rule files in `.github/instructions/rules/`
+2. Update relevant rule files in `.claude/rules/`
 3. Keep documentation synchronized with code changes
 4. Follow security and testing patterns
 5. Ensure AI assistant configurations remain compatible

package/bin/cli.js

@@ -455,7 +455,7 @@ program
       }
 
       // Check agent rules
-      const ruleFiles = ['core.md', 'security.md', 'testing.md', 'frontend.md', 'database.md', 'style.md'];
+      const ruleFiles = ['core.md', 'security.md', 'testing.md', 'lessons-learned.md', 'frontend.md', 'database.md', 'style.md'];
       const canonicalRulesDir = path.join(targetDir, LAYOUT.canonical.rulesDir);
       const legacyRulesDir = path.join(targetDir, LAYOUT.legacy.rulesDirs[0]);
       const rulesDir = path.join(targetDir, resolveRulesDir(targetDir));
@@ -831,9 +831,11 @@ program
         { targetFile: 'agent-docs/ARCHITECTURE.md', templateFile: 'agent-docs/ARCHITECTURE.md', component: 'docs' },
         { targetFile: `${LAYOUT.canonical.rulesDir}/security.md`, templateFile: 'agents/rules/security.md', component: 'rules' },
         { targetFile: `${LAYOUT.canonical.rulesDir}/testing.md`, templateFile: 'agents/rules/testing.md', component: 'rules' },
+        { targetFile: `${LAYOUT.canonical.rulesDir}/lessons-learned.md`, templateFile: 'agents/rules/lessons-learned.md', component: 'rules' },
         { targetFile: `${LAYOUT.canonical.rulesDir}/core.md`, templateFile: 'agents/rules/core.md', component: 'rules' },
         { targetFile: `${LAYOUT.canonical.skillsDir}/README.md`, templateFile: 'agents/skills/README.md', component: 'skills' },
         { targetFile: `${LAYOUT.canonical.skillsDir}/find-skills/SKILL.md`, templateFile: 'agents/skills/find-skills/SKILL.md', component: 'skills' },
+        { targetFile: `${LAYOUT.canonical.skillsDir}/error-patterns/SKILL.md`, templateFile: 'agents/skills/error-patterns/SKILL.md', component: 'skills' },
         { targetFile: `${LAYOUT.canonical.skillsDir}/ui-ux-pro-max/SKILL.md`, templateFile: 'agents/skills/ui-ux-pro-max/SKILL.md', component: 'skills' }
       ];
 

package/lib/layout.js

@@ -9,11 +9,11 @@ const LAYOUT = {
     subagentsDir: '.claude/agents'
   },
   legacy: {
-    rulesDirs: ['agents/rules', '.github/instructions/rules'],
+    rulesDirs: ['agents/rules'],
     skillsDirs: ['agents/skills']
   },
   compatible: {
-    rulesDirs: ['.github/instructions'],
+    rulesDirs: [],
     skillsDirs: ['.claude/skills', '.agents/skills']
   }
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agents-templated",
-  "version": "2.2.6",
+  "version": "2.2.7",
   "description": "Technology-agnostic development template with multi-AI agent support (Cursor, Copilot, VSCode, Gemini), security-first patterns, and comprehensive testing guidelines",
   "main": "index.js",
   "bin": {

package/templates/.claude/rules/lessons-learned.md

@@ -0,0 +1,44 @@
+---
+alwaysApply: true
+title: "Lessons Learned"
+description: "Apply before debugging: check known error patterns first, then record every new resolved fix"
+version: "1.0.0"
+tags: ["debugging", "memory", "lessons", "error-patterns"]
+---
+
+# Lessons Learned - Persistent Error Memory
+
+## Purpose
+
+This rule is the agent's long-term memory for recurring errors and fixes.
+Always check this rule before debugging. If a matching error exists, apply that known fix first.
+
+## Required Workflow
+
+1. Before debugging, check this file for matching symptoms.
+2. If a match is found, apply the known fix immediately.
+3. If no match is found, debug using the `error-patterns` skill checklist.
+4. After every successful fix, append a new lesson entry.
+
+## Lesson Entry Format
+
+```markdown
+### [CATEGORY] Short title of the error
+- **Symptom**: What the error looked like (message, behavior)
+- **Root Cause**: Why it happened
+- **Fix**: Exact steps or code that resolved it
+- **Avoid**: What NOT to do next time
+- **Date**: YYYY-MM-DD
+```
+
+Allowed categories: `[BUILD]` `[DB]` `[API/AUTH]` `[UI]` `[TYPE]` `[CONFIG]` `[OTHER]`
+
+## Enforcement
+
+- This rule is non-overrideable.
+- Lesson recording is mandatory after each resolved error.
+- Do not remove existing lessons unless explicitly requested.
+
+## Known Lessons
+
+<!-- New lessons are appended below this line. Do not remove this comment. -->

package/templates/CLAUDE.md

@@ -13,6 +13,7 @@ All policy, routing, and skill governance lives here — edit this file directly
 |--------|------|---------------|
 | Security | `.claude/rules/security.md` | Implementing authentication, validating inputs, protecting against injection attacks |
 | Testing | `.claude/rules/testing.md` | Adding tests, verifying coverage, validating quality before deployment |
+| Lessons Learned | `.claude/rules/lessons-learned.md` | Debugging recurring errors and applying previously resolved fixes first |
 | Core | `.claude/rules/core.md` | Designing architecture, setting up projects, defining type systems |
 | Database | `.claude/rules/database.md` | Designing schema, building data access layers, optimizing queries |
 | Frontend | `.claude/rules/frontend.md` | Building UI components, designing pages, creating forms, implementing accessibility |
@@ -31,6 +32,7 @@ All policy, routing, and skill governance lives here — edit this file directly
 |-------|------|------------------|
 | app-hardening | `.github/skills/app-hardening/SKILL.md` | Hardening, anti-tamper, integrity controls |
 | bug-triage | `.github/skills/bug-triage/SKILL.md` | Something is broken, failing, or crashing |
+| error-patterns | `.github/skills/error-patterns/SKILL.md` | Debugging with persistent lessons memory and automatic fix recording |
 | feature-delivery | `.github/skills/feature-delivery/SKILL.md` | Build/add/implement feature work |
 | find-skills | `.github/skills/find-skills/SKILL.md` | User asks to discover a skill |
 | ui-ux-pro-max | `.github/skills/ui-ux-pro-max/SKILL.md` | UI, layout, design, visual work |
@@ -70,29 +72,34 @@ Subagents are bounded agents with limited tool access. They inherit all policy f
    - Business logic must have tests; critical flows need integration coverage.
    - Never disable/remove tests to pass builds.
 
-3. **Type safety and runtime boundaries** — `.claude/rules/core.md`
+3. **Lessons Learned (non-overrideable)** — `.claude/rules/lessons-learned.md`
+   - On any error, read lessons first; if matched, apply the known fix immediately.
+   - If new, debug via the `error-patterns` skill checklist and record the resolved fix.
+   - Keep lessons structured and persistent so future sessions reuse known solutions.
+
+4. **Type safety and runtime boundaries** — `.claude/rules/core.md`
    - Strong internal typing, runtime validation at boundaries, explicit error models.
 
-4. **Database integrity** — `.claude/rules/database.md`
+5. **Database integrity** — `.claude/rules/database.md`
    - Prefer ORM/ODM, justify raw queries, enforce DB constraints, prevent N+1, reversible migrations.
 
-5. **Frontend standards** — `.claude/rules/frontend.md`
+6. **Frontend standards** — `.claude/rules/frontend.md`
    - WCAG 2.1 AA, responsive defaults, clear loading/error states, no unsafe client trust.
 
-6. **Style and consistency** — `.claude/rules/style.md`
+7. **Style and consistency** — `.claude/rules/style.md`
    - Consistent naming, small composable modules, explicit contracts, no magic values.
 
-7. **Workflow discipline** — `.claude/rules/system-workflow.md`, `.claude/rules/workflows.md`
+8. **Workflow discipline** — `.claude/rules/system-workflow.md`, `.claude/rules/workflows.md`
    - Feature branches only, no direct main edits, deterministic PR structure, review gates.
 
-8. **Hardening mode** — `.claude/rules/hardening.md`
+9. **Hardening mode** — `.claude/rules/hardening.md`
    - In hardening/audit contexts: assume hostile input, threat-model, validate config safety, strict rate limits, dependency audit.
 
-9. **Planning discipline** — `.claude/rules/planning.md`
+10. **Planning discipline** — `.claude/rules/planning.md`
    - Every feature discussion or implementation produces a `.github/prompts/` plan file.
    - Plans are updated as work progresses, not discarded.
 
-10. **Guardrails (non-overrideable)** — `.claude/rules/guardrails.md`
+11. **Guardrails (non-overrideable)** — `.claude/rules/guardrails.md`
    - Require `CONFIRM-DESTRUCTIVE:<target>` token before any destructive/irreversible action.
    - Work only within the defined task scope; no silent expansion.
    - Classify every action by reversibility before executing.
@@ -115,6 +122,7 @@ Use `.claude/rules/intent-routing.md` and route each task to one primary module:
 - Refactor/Cleanup → Style
 - Audit/Production readiness → Hardening
 - Feature planning → Planning
+- Debugging / recurring failures → Lessons Learned + error-patterns skill
 - LLM/AI work → AI Integration
 - Scope creep / dangerous action / agent behavioral safety → Guardrails
 - Multi-step orchestration / planning / code review → Subagents

package/templates/README.md

@@ -124,22 +124,25 @@ your-project/
 │   └── README.md                   # Human-readable setup guide
 │
 ├── .github/
-│   ├── instructions/                # Generated compatibility wrappers + rules
-│   │   ├── AGENTS.md
-│   │   └── rules/
-│   │   ├── core.mdc               # Core development principles
-│   │   ├── security.mdc           # Security patterns (CRITICAL)
-│   │   ├── testing.mdc            # Testing strategy
-│   │   ├── frontend.mdc           # Frontend patterns
-│   │   ├── database.mdc           # Database patterns
-│   │   └── style.mdc              # Code style guidelines
+│   ├── instructions/                # Compatibility pointer directory
 │   ├── skills/
 │   │   ├── find-skills/           # Skill discovery helper
+│   │   ├── error-patterns/         # Persistent error-debugging memory workflow
 │   │   ├── ui-ux-pro-max/         # Advanced UI/UX design implementation skill
 │   │   ├── README.md              # Guide for creating custom skills
 │   │   └── [your-custom-skills]/  # Your project-specific skills
 │   └── copilot-instructions.md    # Compatibility shim for Copilot
 │
+├── .claude/
+│   ├── rules/                      # Canonical rules source
+│   │   ├── core.md
+│   │   ├── security.md
+│   │   ├── testing.md
+│   │   ├── frontend.md
+│   │   ├── database.md
+│   │   ├── style.md
+│   │   └── lessons-learned.md
+│
 ├── agents/                          # 🤖 Deterministic command contracts
 │   └── commands/
 │   │   ├── SCHEMA.md              # Global slash-command response schema
@@ -273,8 +276,8 @@ Skills define *how to execute specific tasks*, complementing rules that define *
 - **[AGENTS.MD](AGENTS.MD)** – AI assistant guide
 - **[agent-docs/ARCHITECTURE.md](agent-docs/ARCHITECTURE.md)** – Project architecture & tech stack guidance
 - **[.github/skills/README.md](.github/skills/README.md)** – Custom skills guide
-- **[.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)** – Security patterns (CRITICAL)
-- **[.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)** – Testing strategy
+- **[.claude/rules/security.md](.claude/rules/security.md)** – Security patterns (CRITICAL)
+- **[.claude/rules/testing.md](.claude/rules/testing.md)** – Testing strategy
 
 ### 5. Start Building
 
@@ -300,7 +303,7 @@ Your AI will follow the enterprise patterns automatically!
 ✅ Sanitize outputs to prevent injection attacks  
 ✅ Never expose sensitive data in error messages or logs
 
-**Reference**: [.github/instructions/rules/security.mdc](.github/instructions/rules/security.mdc)
+**Reference**: [.claude/rules/security.md](.claude/rules/security.md)
 
 ### Testing Strategy
 
@@ -308,7 +311,7 @@ Your AI will follow the enterprise patterns automatically!
 - **15% Integration Tests** – API endpoints, database operations
 - **5% E2E Tests** – Critical user journeys
 
-**Reference**: [.github/instructions/rules/testing.mdc](.github/instructions/rules/testing.mdc)
+**Reference**: [.claude/rules/testing.md](.claude/rules/testing.md)
 
 ### Agent-Based Architecture
 
@@ -395,7 +398,7 @@ await agentsTemplated.install('./my-project', {
 
 When contributing to this template:
 1. Maintain technology-agnostic patterns
-2. Update relevant rule files in `.github/instructions/rules/`
+2. Update relevant rule files in `.claude/rules/`
 3. Keep documentation synchronized with code changes
 4. Follow security and testing patterns
 5. Ensure AI assistant configurations remain compatible

package/templates/agent-docs/ARCHITECTURE.md

@@ -5,7 +5,7 @@ These guidelines are for both humans and AI assistants working with any technolo
 
 - Canonical AI policy source lives in `CLAUDE.md`.
 - **Agent responsibilities** and MCP integration are documented in `AGENTS.MD`.
-- **Detailed implementation rules** live in `.github/instructions/rules/*.mdc` files.
+- **Detailed implementation rules** live in `.claude/rules/*.md` files.
 - **Custom skills** for domain-specific tasks are organized in `.github/skills/` (see [Skills Guide](../.github/skills/README.md)).
 
 Read this file first to understand the architecture, then consult `AGENTS.MD` for agent delegation.
@@ -223,7 +223,7 @@ Review the options above and select technologies that fit your:
 - **Timeline** and development velocity requirements
 
 ### 2. Adapt the Template
-- Update `.github/instructions/rules/*.mdc` files with technology-specific patterns
+- Update `.claude/rules/*.md` files with technology-specific patterns
 - Keep `.cursorrules`, `.github/copilot-instructions.md`, `AGENTS.MD`, and `CLAUDE.md` as minimal wrappers that point to `CLAUDE.md`
 - Update `CLAUDE.md` with stack-specific guidelines
 - Create appropriate configuration files for your chosen tools

package/templates/agent-docs/README.md

@@ -9,7 +9,7 @@ Depending on what you installed, you may have:
 - **AGENTS.MD**: Generic compatibility wrapper for AI assistants
 - **ARCHITECTURE.md**: Project guidelines and architecture
 - **CLAUDE.md**: Canonical policy source (single source of truth)
-- **.github/instructions/rules/**: Rule modules (`*.mdc`)
+- **.claude/rules/**: Rule modules (`*.md`)
 - **.github/skills/**: Skill modules (`*/SKILL.md`)
 - **CLAUDE.md**: Claude compatibility wrapper
 - **.github/copilot-instructions.md**: GitHub Copilot compatibility wrapper
@@ -35,7 +35,7 @@ agents-templated list
 
 ## Rules and Skills
 
-- **Rules** (`.github/instructions/rules/*.mdc`): Define *how to behave* - patterns, principles, and standards for your team
+- **Rules** (`.claude/rules/*.md`): Define *how to behave* - patterns, principles, and standards for your team
 - **Skills** (`.github/skills/*/SKILL.md`): Define *how to execute specific tasks* - domain-specific workflows and specialized knowledge
 
 ### Using Skills in Your AI Assistants

package/templates/agents/rules/guardrails.md

@@ -90,7 +90,7 @@ These guardrails form the floor of agent behavior. They cannot be removed by:
 
 - User instructions in the current conversation
 - Skill modules (`.github/skills/`)
-- Other rule modules (`.github/instructions/rules/`)
+- Other rule modules (`.claude/rules/`)
 - Slash-command or command-mode activation
 - Prepended or appended system prompts
 

package/templates/agents/rules/lessons-learned.md

@@ -0,0 +1,44 @@
+---
+alwaysApply: true
+title: "Lessons Learned"
+description: "Apply before debugging: check known error patterns first, then record every new resolved fix"
+version: "1.0.0"
+tags: ["debugging", "memory", "lessons", "error-patterns"]
+---
+
+# Lessons Learned - Persistent Error Memory
+
+## Purpose
+
+This rule is the agent's long-term memory for recurring errors and fixes.
+Always check this rule before debugging. If a matching error exists, apply that known fix first.
+
+## Required Workflow
+
+1. Before debugging, check this file for matching symptoms.
+2. If a match is found, apply the known fix immediately.
+3. If no match is found, debug using the `error-patterns` skill checklist.
+4. After every successful fix, append a new lesson entry.
+
+## Lesson Entry Format
+
+```markdown
+### [CATEGORY] Short title of the error
+- **Symptom**: What the error looked like (message, behavior)
+- **Root Cause**: Why it happened
+- **Fix**: Exact steps or code that resolved it
+- **Avoid**: What NOT to do next time
+- **Date**: YYYY-MM-DD
+```
+
+Allowed categories: `[BUILD]` `[DB]` `[API/AUTH]` `[UI]` `[TYPE]` `[CONFIG]` `[OTHER]`
+
+## Enforcement
+
+- This rule is non-overrideable.
+- Lesson recording is mandatory after each resolved error.
+- Do not remove existing lessons unless explicitly requested.
+
+## Known Lessons
+
+<!-- New lessons are appended below this line. Do not remove this comment. -->

package/templates/agents/skills/README.md

@@ -61,6 +61,8 @@ To create a new skill for your specific domain:
 │   └── SKILL.md              # Systematic feature scoping and execution contracts
 ├── bug-triage/
 │   └── SKILL.md              # Reproduction-first debugging and regression workflows
+├── error-patterns/
+│   └── SKILL.md              # Persistent debugging memory and known-fix application
 ├── app-hardening/
 │   └── SKILL.md              # Risk-based hardening and obfuscation guidance
 ├── ui-ux-pro-max/
@@ -96,6 +98,7 @@ Consider creating skills for:
 
 - `feature-delivery`: Use when user asks are broad and you need objective, scope, acceptance criteria, and validation plan.
 - `bug-triage`: Use for defects and regressions requiring reproducible evidence, root-cause isolation, and minimal safe patches.
+- `error-patterns`: Use when errors repeat to apply known fixes from lessons-learned and automatically record new resolutions.
 - `app-hardening`: Use for high-risk/distributed runtimes to enforce hardening profile, obfuscation decisions, and release evidence.
 
 ## Using Skills in Your Project

package/templates/agents/skills/error-patterns/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: error-patterns
+description: >
+  Activate this skill whenever something is broken, failing, erroring, or crashing, especially
+  for build errors, type errors, database/migration failures, API/auth issues, and UI bugs.
+  Also activate when the user says "fix this", "it's broken", "I'm getting an error", or
+  "this keeps happening".
+---
+
+# Error Patterns
+
+You are debugging with persistent memory. Every fix should be recorded so it does not need to be solved twice.
+
+## Step 1 - Check Lessons First (Always)
+
+Before writing any fix, read `.claude/rules/lessons-learned.md`.
+
+- Search for symptoms that match the current error.
+- If a match is found, apply the known fix directly and state that the known fix was used.
+- If no match is found, continue to Step 2.
+
+## Step 2 - Diagnose by Category
+
+### [BUILD] Build / Type Errors
+- Read the full error trace, not just the first line.
+- Check for version mismatches, missing imports, circular dependencies, and config issues.
+- Verify lock file and dependency sync.
+
+### [DB] Database / Migration Errors
+- Check whether the migration already ran.
+- Verify DB URL and environment target.
+- Check for schema drift between model and database.
+- Avoid destructive migrations without a backup.
+
+### [API/AUTH] API / Auth Errors
+- Check token expiry, missing headers, and wrong scopes.
+- Verify environment variables for keys/secrets.
+- Check CORS and middleware order.
+- Log request/response safely (no secrets).
+
+### [UI] Frontend / UI Bugs
+- Check hydration mismatches.
+- Verify null/undefined guards and prop contracts.
+- Check list keys and class conflicts.
+- Confirm loading and error states are handled.
+
+## Step 3 - Apply the Fix
+
+- Make the minimum safe change needed.
+- Do not expand scope beyond the reported error.
+
+## Step 4 - Record the Lesson (Mandatory)
+
+After every successful fix, append to `.claude/rules/lessons-learned.md` using:
+
+```markdown
+### [CATEGORY] Short title of the error
+- **Symptom**: What the error looked like (message, behavior)
+- **Root Cause**: Why it happened
+- **Fix**: Exact steps or code that resolved it
+- **Avoid**: What NOT to do next time
+- **Date**: YYYY-MM-DD
+```
+
+## Step 5 - User Confirmation Message
+
+After fixing and recording, respond with one of:
+
+- `Fixed. I've saved this to lessons-learned so we won't have to solve it again.`
+- `Found this in lessons-learned and applied the known fix.`