mother-brain 0.1.0 → 0.3.0

package/dist/cli.js

@@ -653,7 +653,7 @@ async function uninstall(options) {
 // src/cli.ts
 import { exec as exec3 } from "child_process";
 var program = new Command();
-var VERSION = "0.1.0";
+var VERSION = "0.3.0";
 program.name("mother-brain").description("AI-powered project management framework for GitHub Copilot CLI").version(VERSION);
 program.command("init").description("Initialize Mother Brain in the current project").option("-f, --force", "Overwrite existing skills").action(init);
 program.command("update").description("Update Mother Brain skills to the latest version").action(update);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mother-brain",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "AI-powered project management framework for GitHub Copilot CLI",
   "type": "module",
   "main": "dist/index.js",

package/skills/child-brain/SKILL.md

@@ -34,16 +34,23 @@ allowed-tools: powershell view grep glob web_search ask_user create edit skill
 - ALWAYS present proposed changes with: Accept / Revise / Reject
 - NEVER apply changes without explicit user acceptance
 
-### RULE 4: PAIRED LEARNING
-- Every feedback MUST propose BOTH a Project Brain entry AND a Mother Brain entry
-- Even if one is "no change needed" - show both levels were considered
+### RULE 4: FOUR-LAYER CONSIDERATION
+- Every feedback MUST be analyzed across ALL FOUR layers:
+  1. **Elder Brain**: Is this domain/tech knowledge?
+  2. **Project Brain**: Is this project-specific?
+  3. **Mother Brain**: Is this about thinking process?
+  4. **Skills**: Is execution capability missing?
+- Even if some are "no change needed" - show all layers were considered
+- Display which layers received updates
 
 ### RULE 5: VISIBLE CONFIRMATION
-- After learning is recorded, ALWAYS display:
+- After learning is recorded, ALWAYS display which layers were updated:
+  - `🧙 Elder Brain will remember this` (for domain/tech gotchas)
   - `📘 Project Brain will remember this` (for project learnings)
-  - `🧠 Mother Brain will remember this` (for process learnings)
-- If user selects from menu options that reveal preferences, STILL note it:
-  - `📘 Noted: [preference summary]`
+  - `🧠 Mother Brain will remember this` (for thinking process)
+  - `🛠️ [skill-name] created/updated` (for execution capability)
+- Show "No changes" for layers that weren't updated
+- If user selects from menu options that reveal preferences, STILL note it
 
 ---
 
@@ -51,18 +58,30 @@ Child Brain is the EXPERT at analyzing ALL user feedback - not just errors. It r
 
 ## Purpose
 
-Child Brain ensures learnings go to the right place:
-- **Project-specific learnings** → Project Brain (`.mother-brain/project-brain.md`)
-  - Course corrections for this project's trajectory
-  - Style/tone preferences discovered
-  - Skill adjustments needed
-  - Vision document updates
-- **Behavioral/process learnings** → Mother Brain (`.github/skills/mother-brain/SKILL.md`)
-  - How to better facilitate user vision
-  - Process improvements for ALL projects
-  - NEVER domain knowledge or project specifics
-- **Domain knowledge gaps** → Skills (via skill-creator)
-  - When expertise is missing, create a skill
+Child Brain ensures learnings go to the right place across FOUR layers:
+
+1. **Elder Brain** (`experience-vault/`) → **Domain Knowledge**
+   - Technology-specific gotchas (Firebase, React, Vercel)
+   - Platform patterns (Windows paths, auth flows)
+   - Cross-project wisdom that applies to ALL projects of a type
+   - Example: "Firebase Auth needs Console click-through"
+
+2. **Project Brain** (`.mother-brain/project-brain.md`) → **Project-Specific**
+   - Style/tone/design preferences for THIS project
+   - Vision refinements discovered during execution
+   - Validation checks for this project's domain
+   - Example: "This game uses warm cozy Stardew Valley aesthetic"
+
+3. **Mother Brain** (`.github/skills/mother-brain/SKILL.md`) → **Meta-Behavioral**
+   - HOW to think, WHEN to research, WHAT to consider
+   - Process improvements for facilitating ALL projects
+   - Cognition and adaptation patterns
+   - Example: "When learning about outcome, research failure modes"
+
+4. **Skills** (via skill-creator) → **Execution Capability**
+   - Domain-specific execution knowledge
+   - Created when expertise gaps are detected
+   - Example: pixel-art-renderer skill with game art knowledge
 
 Child Brain NEVER stores knowledge itself. It analyzes, routes, and creates.
 
@@ -104,26 +123,42 @@ Child Brain is invoked by Mother Brain for ALL of these (not just errors):
   This ensures both levels are always considered and visible to user.
 - **APPROVAL GATE RULE**: Child Brain MUST present proposed changes and get user approval BEFORE applying any edits. Use three options: Accept / Revise / Reject. NEVER apply changes without explicit user acceptance.
 
-## The Three Questions for Every Learning
-
-When analyzing feedback, Child Brain asks:
-
-1. **Is this about THIS PROJECT specifically?**
-   - Style preferences, design choices, domain conventions
-   - → Route to Project Brain for course correction
-   - → May trigger skill updates for this project
-
-2. **Is this about HOW MOTHER BRAIN FACILITATED?**
-   - Did it consider enough at vision phase?
-   - Did it anticipate what would be needed later?
-   - Did it make the right choices based on user's stated needs?
-   - → Route to Mother Brain as behavioral improvement
-   - → Must be completely project-agnostic
-
-3. **Is this about MISSING EXPERTISE?**
-   - Agent didn't know how to do something well
-   - → Create or update a skill via skill-creator
-   - → Skills hold the domain knowledge
+## The Four Questions for Every Learning
+
+When analyzing feedback, Child Brain asks (IN THIS ORDER):
+
+1. **Is this DOMAIN KNOWLEDGE (technology/platform-specific)?**
+   - Mentions specific technology name? (Firebase, React, Vercel, Windows)
+   - Platform-specific gotcha or pattern?
+   - Cross-project wisdom for this tech stack?
+   - → Route to **Elder Brain** (experience-vault/)
+   - Example: "Firebase Auth needs Console click-through before use"
+
+2. **Is this about THIS PROJECT specifically?**
+   - Style preferences, aesthetic choices, design direction
+   - Vision refinements or missed requirements
+   - Project-specific validation needs
+   - → Route to **Project Brain** for course correction
+   - Example: "This game uses warm cozy Stardew Valley aesthetic"
+
+3. **Is this about HOW MOTHER BRAIN THINKS?**
+   - WHEN to research? WHAT to consider? HOW to anticipate?
+   - Information processing and adaptation patterns
+   - NOT about what to think, but how to approach thinking
+   - → Route to **Mother Brain** as cognitive improvement
+   - Example: "When user mentions outcome, research failure modes first"
+
+4. **Is this about MISSING EXECUTION CAPABILITY?**
+   - Agent didn't know how to execute something well
+   - Need specialized domain knowledge for execution
+   - → Create or update a **Skill** via skill-creator
+   - Example: Need pixel-art-renderer skill with game art knowledge
+
+**The Test (CRITICAL):**
+- Does it mention a technology name? → Elder Brain
+- Is it about this project's style/preferences? → Project Brain  
+- Is it about WHEN/HOW to think? → Mother Brain
+- Is it about execution capability? → Skill
 
 ## Friction Analysis Flow
 
@@ -172,38 +207,110 @@ Determine the **layer** where the issue originated:
 - **Missing Validation**: No check was in place to catch this before user saw it
 - **Process Gap**: Mother Brain's workflow skipped a necessary step
 
-### Step 4: Split the Learning
+### Step 4: Split the Learning (Four-Way Analysis)
 
 Based on root cause, determine what goes where:
 
-**PROJECT-LEVEL Learning (→ Project Brain) - Course Correction:**
-- "This project uses [specific style/tone/approach]"
-- "For this project, always [specific check or validation]"
-- "This project's vision includes [specific requirement]"
-- References, examples, style guides specific to this project
-- Validation checks specific to this project's domain
-- **Course corrections for future tasks:**
-  - "User prefers X over Y - update design skills accordingly"
-  - "Vision document needs to reflect [preference]"
-  - "Flag for Task [N] - incorporate this preference"
-
-**META-LEVEL Learning (→ Mother Brain) - Behavioral Only:**
-- Process improvements that help ALL projects
-- Did Mother Brain consider enough during vision discovery?
-- Did Mother Brain anticipate what would be needed later?
-- Did Mother Brain make the right choices based on user's stated needs?
-- When to create skills (patterns that warrant skill creation)
-- When to ask discovery questions (before implementing creative work)
-- When to research (domains that need external knowledge)
-- Validation gates (when to pause and check with user)
-- **NEVER domain specifics** - those go to skills
-
-**Skill Creation/Update Decision:**
-If root cause is "Missing Skill" or "Insufficient Skill":
-- Invoke skill-creator to create/enhance the skill
-- Skill gets the domain knowledge, NOT Mother Brain
+**ELDER BRAIN (experience-vault/) - Technology/Platform Gotchas:**
+- Check: Does this mention a specific technology or platform name?
+- "Firebase Auth requires Console click-through"
+- "Vercel needs .env.production for build-time vars"
+- "Windows PowerShell needs -Force flag for directories"
+- "React refs don't work with functional components"
+- Cross-project patterns for specific tech stacks
+- Platform-specific workarounds and requirements
+
+**PROJECT BRAIN (.mother-brain/project-brain.md) - This Project's Identity:**
+- "This project uses warm cozy Stardew Valley aesthetic"
+- "This game has horses as central character, not just background"
+- "User prefers Tailwind over CSS modules"
+- Style/tone/design preferences specific to this project
+- Vision refinements discovered during execution
+- Validation checks for this project's domain
+- **Course corrections for future tasks**
+
+**MOTHER BRAIN (.github/skills/mother-brain/SKILL.md) - Thinking Process:**
+- Check: Is this about WHEN/HOW/WHAT to consider? (not about specific content)
+- "When user mentions outcome, research failure modes first"
+- "Before creative work, ask user about style preferences"
+- "When outcome involves data, consider exposure risks"
+- Information processing patterns
+- Research triggers and anticipation
+- **NOT hardcoded rules for domains** - those go to Elder Brain
+
+**SKILL CREATION/UPDATE:**
+- If execution capability is missing
+- If domain knowledge needs to be embedded in tooling
+- Route research findings + user preferences to skill-creator
 - Log skill creation in Project Brain
 
+**The Critical Test:**
+1. Does it mention Firebase/React/Vercel/Windows/etc.? → **Elder Brain**
+2. Is it about this project's aesthetic/style/preferences? → **Project Brain**
+3. Is it about WHEN to research or HOW to think? → **Mother Brain**
+4. Is it about execution tooling? → **Skill**
+
+### Step 4.5: Apply Elder Brain Learning (Domain Gotchas)
+
+**When learning is domain/technology-specific:**
+
+**Step 4.5.1: Identify Domain Category**
+- Security (auth, data exposure, vulnerabilities)
+- Deployment (platform-specific requirements, config)
+- APIs (integration patterns, rate limiting)
+- Databases (schema, ORMs, query patterns)
+- UI (accessibility, responsive, design systems)
+- Platforms (Windows, macOS, Linux, mobile, web)
+
+**Step 4.5.2: Check if Knowledge Already Exists**
+- Search `experience-vault/[category]/` for related files
+- Use grep to check for technology mentions
+- If exists → update existing file
+- If new → create new file
+
+**Step 4.5.3: Document the Gotcha**
+
+Create/update `experience-vault/[category]/[tech-name].md`:
+
+```markdown
+# [Technology Name] - [Brief Title]
+
+## Problem
+[What goes wrong - the error/failure user experiences]
+
+## Gotcha
+[The non-obvious thing - why it happens, what's unexpected]
+
+## Solution
+[How to fix/prevent - code examples, config, steps]
+
+**When to Consult**: [Which Mother Brain steps should reference this]
+
+## Related Gotchas
+See also:
+- [Link to related experience-vault files]
+
+## Sources
+- [Link to official docs]
+- [Link to community resources]
+```
+
+**Step 4.5.4: Display Simple Confirmation**
+
+Display to user:
+```
+🧙 Elder Brain will remember this
+```
+
+**Step 4.5.5: Update Mother Brain Reference (If Needed)**
+
+If this is a common gotcha that Mother Brain should ALWAYS check for:
+- Add reference to appropriate Mother Brain step
+- Example: "Before deploying, consult experience-vault/deployment/"
+- Mother Brain doesn't store the gotcha - just knows WHERE to look
+
+**Key Principle**: Elder Brain stores domain facts. Mother Brain learns to consult Elder Brain at the right times.
+
 ### Step 5: Apply Project-Level Learning (Course Correction) - ACTIVE
 
 **Project Brain is ACTIVE, not passive.** It doesn't just store learnings - it TAKES ACTION:

package/skills/mother-brain/SKILL.md

@@ -607,6 +607,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - Question: "What would you like to do?"
      - Choices (MUST be provided as array):
        - "Continue where I left off"
+       - "💡 I have a new idea"
        - "Review/update roadmap"
        - "Realign with vision"
        - "🧠 Improve Mother Brain"
@@ -614,6 +615,8 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
        - "Eject project (reset to framework + learnings)"
    - **CRITICAL**: Do NOT ask what to do as freeform text. ALWAYS use the `ask_user` tool.
    - Freeform automatically available for custom actions
+   - **If "I have a new idea"**: Jump to **Step 2F: Idea Capture & Prioritization**
+   - **If "Continue where I left off"**: Jump to **Step 2G: Task Resume Preview**
    - **If "Improve Mother Brain"**: Jump to **Step 2A: Improve Mother Brain Menu**
    - **If "Send improvement"**: Jump to **Step 2A: Send Improvement to Mother Brain**
 
@@ -668,9 +671,11 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - "Improve documentation"
      - "Refactor or clean up code"
      - "📥 Review community improvements"
+     - "💭 Brainstorm (thinking partner mode)"
      - "Continue previous meta-work"
    
    - **If "Review community improvements"**: Jump to **Step 2A.2: Review Community Improvements**
+   - **If "Brainstorm"**: Jump to **Step 2E: Brainstorm Mode** (framework-focused version)
    
    **Step 2.3.2: Track Meta-Work**
    - Update `.mother-brain/meta-mode.json` with focus:
@@ -1591,6 +1596,235 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    - If "Not yet": Continue brainstorm conversation
    - If "Exit": Return to main menu (Step 2)
 
+### 2F. **Idea Capture & Prioritization** (Quick Idea Logging)
+   - When user selects "💡 I have a new idea" from ANY menu:
+   
+   **Purpose**: Let users quickly capture ideas mid-project without derailing current work. Ideas are analyzed against the vision, prioritized, and inserted into the roadmap at the right position. The user never loses an idea, and the current plan stays intact unless the idea is truly urgent.
+   
+   **Step 2F.1: Capture the Idea**
+   
+   - Display:
+     ```
+     💡 New Idea Capture
+     
+     Tell me your idea — what is it and what would it achieve?
+     Don't worry about where it fits yet, just get it down.
+     ```
+   
+   - Use `ask_user` with `allow_freeform: true` (no predefined choices — pure capture mode)
+   
+   **Step 2F.2: Analyze & Score the Idea**
+   
+   - Load `.mother-brain/docs/vision.md` (for alignment check)
+   - Load `.mother-brain/docs/roadmap.md` (for context on existing tasks)
+   - Load `.mother-brain/project-brain.md` (for project preferences, if exists)
+   
+   - Analyze the idea across four dimensions:
+     1. **Vision Alignment**: How well does this idea serve the project's stated WHY and success criteria?
+     2. **User Impact**: How much does this benefit the target users defined in the vision?
+     3. **Effort Estimate**: Relative complexity — is this a single task or a multi-task effort?
+     4. **Dependency Check**: Does this idea depend on existing tasks, or do existing tasks depend on it?
+   
+   - Determine priority level:
+     - **🔴 Critical (insert into current phase)**: Directly blocks or significantly enhances the MVP. Aligns strongly with vision AND has high user impact.
+     - **🟡 Important (next phase priority)**: Aligns well with vision but isn't needed for MVP. Should be tackled soon after current phase.
+     - **🟢 Backlog (future enhancement)**: Nice-to-have that aligns with vision but can wait. Added to Future Enhancements.
+   
+   **Step 2F.3: Present Analysis to User**
+   
+   - Display:
+     ```
+     💡 Idea Analysis
+     
+     Your Idea: [1-2 sentence summary of what they described]
+     
+     📊 Assessment:
+     - Vision Alignment: [High/Medium/Low] — [brief reason]
+     - User Impact: [High/Medium/Low] — [brief reason]
+     - Effort: [Small (1 task) / Medium (2-3 tasks) / Large (new phase)]
+     - Dependencies: [None / Depends on Task X / Blocks Task Y]
+     
+     🎯 Recommended Priority: [🔴 Critical / 🟡 Important / 🟢 Backlog]
+     
+     Reasoning: [2-3 sentences explaining why this priority level was chosen,
+     referencing vision alignment and current roadmap state]
+     ```
+   
+   - Use `ask_user` with choices:
+     - "Accept this priority — add to roadmap"
+     - "I think it's more urgent than that"
+     - "I think it's less urgent — backlog is fine"
+     - "Let me refine the idea first"
+     - "Discard — I changed my mind"
+   
+   **Step 2F.4: Handle Priority Override**
+   
+   - **If "Accept this priority"**: Proceed to Step 2F.5
+   
+   - **If "I think it's more urgent"**:
+     - Bump priority one level up (🟢→🟡 or 🟡→🔴)
+     - If already 🔴: Acknowledge and proceed
+     - Display: `📘 Project Brain will remember this — you prioritize [idea type] higher than expected`
+     - Invoke Child Brain with preference context (user values this type of feature highly)
+     - Proceed to Step 2F.5
+   
+   - **If "I think it's less urgent"**:
+     - Bump priority one level down (🔴→🟡 or 🟡→🟢)
+     - If already 🟢: Keep at backlog
+     - Display: `📘 Project Brain will remember this — you prefer to defer [idea type]`
+     - Proceed to Step 2F.5
+   
+   - **If "Let me refine the idea"**:
+     - Return to Step 2F.1 with previous input as context
+   
+   - **If "Discard"**:
+     - Display: "💭 No problem — idea discarded. Nothing was changed."
+     - Return to the menu the user came from (Step 2 or Step 11)
+   
+   **Step 2F.5: Insert into Roadmap**
+   
+   - Based on final priority level:
+   
+   - **🔴 Critical (current phase insertion)**:
+     1. Load roadmap and identify current phase tasks
+     2. Determine optimal insertion point:
+        - After dependencies are met
+        - Before tasks that would benefit from this idea
+        - If no dependencies: insert as next uncompleted task
+     3. Create task number (next sequential number)
+     4. Create task document in `.mother-brain/docs/tasks/[number]-[name].md`
+     5. Insert task into `roadmap.md` at determined position
+     6. **Renumber subsequent tasks if needed** to maintain order
+     7. Display:
+        ```
+        ✅ Idea Added to Current Phase!
+        
+        📋 Task [Number]: [Task Name]
+        - Priority: 🔴 Critical
+        - Inserted: Phase [X], position [Y] of [Z]
+        - Status: 🟡 Ready
+        
+        ⚠️ Current plan adjusted:
+        - [Brief description of what moved to accommodate this]
+        
+        Your current task is still: [Current task name]
+        This will be picked up [when in sequence].
+        ```
+   
+   - **🟡 Important (next phase priority)**:
+     1. Identify the next phase in roadmap (or create Phase N+1 if needed)
+     2. Create task number
+     3. Create task document
+     4. Insert at the TOP of the next phase (high priority within that phase)
+     5. Display:
+        ```
+        ✅ Idea Added to Next Phase!
+        
+        📋 Task [Number]: [Task Name]
+        - Priority: 🟡 Important
+        - Placed: Phase [X], position 1 (top priority)
+        - Status: ⬜ Planned
+        
+        Current plan unchanged — this is queued for after [current phase name].
+        ```
+   
+   - **🟢 Backlog (future enhancement)**:
+     1. Add to "Future Enhancements" section of roadmap
+     2. Create a lightweight task entry (no full task doc yet — created when promoted)
+     3. Display:
+        ```
+        ✅ Idea Added to Backlog!
+        
+        📋 [Idea Name]
+        - Priority: 🟢 Backlog
+        - Section: Future Enhancements
+        - Status: 💭 Captured
+        
+        Current plan unchanged. This will be reviewed during phase transitions.
+        ```
+   
+   **Step 2F.6: Update Session State & Return**
+   
+   - Update `session-state.json` to reflect roadmap changes (new task count, etc.)
+   - If task was added to current phase: Update `totalTasks` count
+   
+   - Display:
+     ```
+     💡 Idea captured! Back to where you were.
+     ```
+   
+   - **Return to the menu the user came from**:
+     - If came from Step 2 (main menu): Return to Step 2
+     - If came from Step 11 (post-task menu): Return to Step 11
+     - If came from mid-task: Resume task execution
+   
+   **Key Principles**:
+   - **Speed over ceremony**: Get the idea down fast, analyze quickly, don't interrupt flow
+   - **Vision is the compass**: Priority is always relative to the stated vision
+   - **Current work is protected**: Only 🔴 Critical ideas touch the current phase
+   - **Nothing is lost**: Even discarded ideas could be re-suggested if patterns emerge
+   - **User has final say**: Mother Brain recommends priority, user can override
+
+### 2G. **Task Resume Preview** (Continue Where You Left Off)
+   - When user selects "Continue where I left off" from the main project menu:
+   
+   **Purpose**: Show the user exactly what task they're about to resume, where it sits in the plan, and give them the option to proceed, switch tasks, or review context before diving in. Never jump straight into execution.
+   
+   **Step 2G.1: Load Current Task Context**
+   
+   - Load `session-state.json` to get `lastTask` and `lastTaskStatus`
+   - Load `roadmap.md` to get phase context and task position
+   - Load the current task document from `.mother-brain/docs/tasks/[task].md`
+   - Determine:
+     - Is the last task complete or in-progress?
+     - If complete: the "current task" is the NEXT uncompleted task in the roadmap
+     - If in-progress: the "current task" is the last task
+   
+   **Step 2G.2: Display Task Preview**
+   
+   - Display:
+     ```
+     🎯 Current Task
+     
+     📋 Task [Number]: [Task Name]
+     - Phase: [Phase Name] ([X] of [Y] tasks completed in this phase)
+     - Status: [🟡 In Progress / ⬜ Ready to Start]
+     - Type: [Logic / UI / Animation / Integration / etc.]
+     
+     📝 Objective:
+     [Task objective from task document]
+     
+     ✅ Success Criteria:
+     - [Criterion 1]
+     - [Criterion 2]
+     
+     🛠️ Skills Available:
+     - [Relevant skills for this task]
+     
+     📍 Roadmap Context:
+     - Previous: Task [N-1] - [Name] (✅ Complete)
+     - **Current: Task [N] - [Name]** ← You are here
+     - Next: Task [N+1] - [Name] (⬜ Planned)
+     ```
+   
+   **Step 2G.3: Ask User How to Proceed**
+   
+   - Use `ask_user` with choices:
+     - "Start this task now"
+     - "Skip to a different task"
+     - "Review the full roadmap first"
+     - "💡 I have a new idea"
+     - "Back to main menu"
+   
+   - **If "Start this task now"**: Proceed to Step 9 (Task Execution) with this task
+   - **If "Skip to a different task"**:
+     - Load roadmap and list all uncompleted tasks in current phase
+     - Use `ask_user` with task names as choices
+     - Load selected task and proceed to Step 9
+   - **If "Review the full roadmap"**: Display roadmap, then return to Step 2G.3
+   - **If "I have a new idea"**: Jump to Step 2F
+   - **If "Back to main menu"**: Return to Step 2
+
 ### 2C. **Archive Project** (Save & Reset)
    - When user selects "Archive project (save & reset for new project)":
    
@@ -2189,19 +2423,33 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      
      **Step 5.4.1: Technology Pitfalls & Gotchas Research (MANDATORY)**
      - For EACH technology/platform/tool identified in vision or research:
+       
+       **First, check Elder Brain (experience-vault/) for existing knowledge:**
+       - Use grep to search: `grep -r "[technology]" experience-vault/`
+       - If gotchas exist in Elder Brain:
+         - Load the relevant .md files
+         - Use this knowledge to inform skill creation
+         - No need to re-research what's already known
+       
+       **If NOT in Elder Brain, research and contribute:**
        - Use `web_search` to research:
-         1. "common [technology] mistakes and pitfalls"
+         1. "common [technology] mistakes and pitfalls [current year]"
          2. "[technology] gotchas first-time users encounter"
          3. "[technology] troubleshooting guide"
          4. "[technology] deployment issues and solutions" (if applicable)
-       - Save findings to `.mother-brain/docs/research/[technology]-gotchas.md`
+       - Save findings to BOTH:
+         1. `.mother-brain/docs/research/[technology]-gotchas.md` (project-specific)
+         2. `experience-vault/[category]/[technology].md` (for all future projects)
        - Document:
          - **Common Mistakes**: What do beginners get wrong?
          - **Setup Traps**: First-time setup issues (permissions, configuration, prerequisites)
          - **Known Failures**: Transient errors vs real failures
          - **Workarounds**: Standard solutions to known problems
+       
+       **Result:**
        - This research gets embedded in skills created for this technology
        - Skills become defensive, anticipating known issues instead of only happy-path
+       - Future projects benefit immediately from Elder Brain knowledge
      
      **Step 5.5: Extract Technical Insights from Research**
      - Parse research results to identify:
@@ -2417,13 +2665,46 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - **Create Initial 3 Skills** (Upfront - minimum viable skill set):
        - Display: "🔨 Creating initial 3 skills for project..."
        - Select 3 most critical skills from essential list (based on immediate MVP needs)
+       
+       - **CHECKPOINT: Consult Elder Brain for Each Skill**
+         - Before invoking skill-creator for each skill:
+           1. Identify domains/technologies this skill will work with
+              - Example: "firebase-deployer" → Firebase, deployment
+           2. Check Elder Brain for related knowledge:
+              ```powershell
+              grep -r "Firebase" experience-vault/
+              grep -r "deployment" experience-vault/
+              ```
+           3. If gotcha files found:
+              - Load content from experience-vault/
+              - Prepare Elder Brain context for skill-creator
+           4. If no gotchas found:
+              - Note this for later research during task execution
+       
        - For each of the 3 initial skills:
          - Show progress: "Creating [skill-name]..."
-         - Invoke skill-creator with context from research findings:
-           - Role/pattern/need from Step 5 analysis
-           - Relevant gotchas research from Step 5.4.1 (if skill involves specific technology)
-           - Example: "firebase-deployer skill should include gotchas about permission propagation, environment config, console prerequisites"
-         - Let skill-creator run its wizard with gotchas knowledge
+         - Invoke skill-creator with THREE knowledge sources:
+           1. **Research findings** from Step 5 analysis (role/pattern/need)
+           2. **Gotchas research** from Step 5.4.1 (project-specific research)
+           3. **Elder Brain knowledge** (cross-project domain wisdom)
+         - Example context for skill-creator:
+           ```
+           Skill: firebase-deployer
+           
+           From Research (Step 5):
+           - Role: DevOps automation
+           - Pattern: Deployment with retry logic
+           
+           From Gotchas Research (Step 5.4.1):
+           - Firebase CLI auth expires after 7 days
+           - Large deployments may timeout
+           
+           From Elder Brain (experience-vault/):
+           - Firebase Auth needs Console click-through first
+           - Environment variables need both dashboard + .env.production
+           - Authorized domains must be configured for production
+           ```
+         - Let skill-creator run its wizard with all three knowledge sources
          - **Store created skills in `.github/skills/`** (CLI-discoverable location)
          - **Track in session-state.json**: Add skill name to `skillsCreated` array
          - **VALIDATE SKILL** (CRITICAL - prevents task execution failures):
@@ -2633,6 +2914,52 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      **Estimated Timeline**: [From vision document]
      ```
    
+   **Step 7.3.5: CHECKPOINT - Review Roadmap Against Elder Brain**
+   - **Purpose**: Surface known pitfalls for the tech stack BEFORE task execution begins
+   
+   - For EACH technology/platform identified in roadmap tasks:
+     1. Extract tech mentions from task descriptions
+        - Example: "Set up Firebase Auth" → Firebase, Authentication
+        - Example: "Deploy to Vercel" → Vercel, Deployment
+        - Example: "Create React components" → React, UI
+     
+     2. Check Elder Brain for relevant gotchas:
+        ```powershell
+        grep -ri "Firebase" experience-vault/
+        grep -ri "Vercel" experience-vault/
+        grep -ri "React" experience-vault/
+        ```
+     
+     3. For EACH gotcha file found:
+        - Load content from experience-vault/
+        - Identify which roadmap tasks are affected
+        - Add defensive note to those task descriptions
+     
+     4. Example transformation:
+        ```markdown
+        # BEFORE Elder Brain check:
+        - [ ] Task 003: Set up Firebase Authentication
+        
+        # AFTER Elder Brain check:
+        - [ ] Task 003: Set up Firebase Authentication
+             ⚠️ Prerequisites: Enable Auth in Firebase Console first
+             📚 See: experience-vault/platforms/firebase-auth.md
+        ```
+     
+     5. If NO Elder Brain knowledge exists for a technology:
+        - Note this in Project Brain for future contribution
+        - Expect to research during task execution
+   
+   - Display:
+     ```
+     🧙 Elder Brain consulted
+     - [X] technologies checked
+     - [Y] known gotchas surfaced in roadmap
+     ```
+   
+   - Update roadmap.md with Elder Brain references
+   - This makes pitfalls visible BEFORE tasks start, not during failures
+   
    **Step 7.4: Display Roadmap Summary** (No Approval Required)
      - Show roadmap structure to user (for transparency, not approval)
      - Display:
@@ -2856,6 +3183,43 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
       - What creative/visual/narrative elements does this task involve?
       - What domain knowledge is required?
       - What style/tone preferences apply?
+      - **What technologies/platforms does this task use?** (for Elder Brain check)
+   
+   2.5. **CHECKPOINT: Consult Elder Brain for This Task**
+      - Extract technology/platform mentions from task:
+        - Task title: "Set up Firebase Auth" → Firebase, Authentication
+        - Task description: "Deploy React app to Vercel" → React, Vercel, Deployment
+        - Task deliverables: "PostgreSQL schema" → PostgreSQL, Database
+      
+      - For EACH technology identified:
+        ```powershell
+        grep -ri "[technology]" experience-vault/
+        ```
+      
+      - If gotcha files found:
+        1. Load content from experience-vault/
+        2. Display relevant gotchas to Mother Brain (for awareness)
+        3. Apply defensive patterns automatically during execution
+        
+        Example:
+        ```
+        🧙 Elder Brain: Firebase Auth
+        
+        Known gotchas for this task:
+        - Firebase Auth requires Console click-through before API works
+        - Environment variables need both dashboard + .env.production
+        - Authorized domains required for production
+        
+        Applying defensive patterns:
+        ✓ Will verify Console setup before implementing
+        ✓ Will check for .env.production file
+        ✓ Will add domain authorization to task checklist
+        ```
+      
+      - If NO gotchas found:
+        - Note: "No Elder Brain knowledge for [technology]"
+        - Expect to research during execution if issues arise
+        - Plan to contribute back to Elder Brain after task
    
    3. **Skill Sufficiency Check** (CRITICAL):
       - List existing skills in `.github/skills/`
@@ -3010,7 +3374,40 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
 ### 9A. **Error Detection & Self-Healing**
    - When errors occur during task execution:
    
-   - **Document the Issue**:
+   - **FIRST: Check Elder Brain for Known Solution**:
+     1. Extract technology/error context from error message:
+        - "Firebase permission denied" → Firebase, permissions
+        - "Vercel build failed: env var undefined" → Vercel, environment variables
+        - "PowerShell directory exists error" → PowerShell, Windows
+     
+     2. Search Elder Brain for this pattern:
+        ```powershell
+        grep -ri "[technology]" experience-vault/
+        grep -ri "[error keyword]" experience-vault/
+        ```
+     
+     3. If matching gotcha found:
+        ```
+        🧙 Elder Brain: Known Issue Found
+        
+        Pattern: [gotcha title]
+        Location: experience-vault/[category]/[file].md
+        
+        Known Solution:
+        [Solution from Elder Brain]
+        
+        Applying fix...
+        ```
+        - Apply the documented solution immediately
+        - Skip root cause analysis (already known)
+        - Resume task execution
+        - DONE - no further steps needed
+     
+     4. If NO Elder Brain knowledge:
+        - Continue to root cause analysis below
+        - Plan to contribute solution to Elder Brain after fixing
+   
+   - **Document the Issue** (if NOT in Elder Brain):
      - What broke (error message, unexpected behavior)
      - What was being attempted
      - What the expected outcome was
@@ -3020,6 +3417,7 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
      - Was it a task definition issue? (unclear instructions)
      - Was it a Mother Brain issue? (missing step, wrong assumption)
      - Was it an environment issue? (dependencies, configuration)
+     - **Was it a known domain gotcha?** (technology-specific pattern)
    
    - **Log & Learn**:
      - Add entry to `docs/learning-log.md`:
@@ -3030,15 +3428,22 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
        **Root Cause**: [Why it happened]
        **Fix Applied**: [How it was resolved]
        **Prevention**: [What to update to prevent recurrence]
+       **Elder Brain Contribution**: [If domain gotcha, note for contribution]
        ```
    
    - **Self-Correction**:
      - Use `ask_user` with choices:
+       - "Contribute to Elder Brain (domain gotcha)"
        - "Update [affected skill] to prevent this"
        - "Update Mother Brain process"
        - "Update task definition"
        - "Just fix it this time (one-off issue)"
      
+     - If "Contribute to Elder Brain":
+       - Invoke Child Brain to route the learning
+       - Child Brain will create Elder Brain entry
+       - Display: `🧙 Elder Brain will remember this`
+     
      - If updating skill/Mother Brain:
        - Jump to **Step 2A: Update Mother Brain** (if Mother Brain issue)
        - Or invoke skill-creator with "heal" mode (if skill issue)
@@ -3395,10 +3800,12 @@ This pattern ensures NO workflow ever traps the user—there's always an escape
    - After task completion, use `ask_user` with choices:
    - After task completion, use `ask_user` with choices:
      - "Start next task automatically"
+     - "💡 I have a new idea"
      - "Review roadmap and choose task"
      - "Take a break (save progress)"
      - "Update/refine the roadmap"
    - Freeform available for custom actions
+   - **If "I have a new idea"**: Jump to **Step 2F: Idea Capture & Prioritization**
    
    - Save session state to `docs/session-state.json`:
      ```json