@codeyam/codeyam-cli 0.1.0-staging.76566f9 → 0.1.0-staging.79ef713

package/codeyam-cli/templates/{debug-codeyam.md → codeyam:diagnose.md}

@@ -1,10 +1,10 @@
 # Debug Scenario or Analysis
 
-When a user asks to debug a scenario or analysis (e.g., `/debug-codeyam [ID]`), use this systematic process.
+When a user asks to debug a scenario or analysis (e.g., `/codeyam:diagnose [ID]`), use this systematic process.
 
 ## Goal
 
-Determine whether a capture failure can be fixed locally (via database changes) or requires a CodeYam engine fix. Either way, produce a detailed debug report.
+**Capture quality screenshots** by fixing all errors, then document what was wrong. Every issue can be fixed locally—the question is whether the fix is in the database (Categories 1-3) or in the tmp folder code (Category 4). Either way, you must capture screenshots before concluding.
 
 ## Definition of Done
 
@@ -14,6 +14,43 @@ Determine whether a capture failure can be fixed locally (via database changes)
 2. **SUCCESS (File Fix)**: Issue fixed via tmp folder edits, screenshots recaptured with `--capture-only`, ALL screenshot files verified AND visually inspected, changes documented for CodeYam team
 3. **UNFIXABLE**: Issue cannot be fixed locally (rare), documented in final report with full details
 
+**CRITICAL: NEVER stop debugging before capturing quality screenshots.** Even if you identify the root cause as a "Category 4 engine bug", you MUST:
+
+1. Fix the issue manually in the tmp folder (this is always possible)
+2. Run `codeyam recapture --capture-only` to capture screenshots with your fixes in place
+3. Verify the screenshots show the component rendering correctly
+4. ONLY THEN document the engine bug for the CodeYam team
+
+Stopping after identifying a bug category without capturing screenshots defeats the purpose of debugging.
+
+## Critical: Persistence and User Communication
+
+**DO NOT give up prematurely.** Every issue can be fixed by editing files in the tmp folder. If you find yourself thinking:
+
+- "This requires an engine-level fix"
+- "This is blocked by a code generation bug"
+- "The engine doesn't properly handle X"
+
+**STOP.** These statements are incorrect. You have full access to edit any file in `/tmp/codeyam/local-dev/{slug}/project/`. The "engine" just wrote those files—they're plain TypeScript/JavaScript that you can edit directly.
+
+### Before Stopping or Concluding
+
+1. **Try at least 3 different approaches** to fix the issue
+2. **Never unilaterally decide to stop.** If you've been debugging and aren't making progress, ASK THE USER:
+   > "I've tried X, Y, and Z but haven't resolved the issue yet. Would you like me to continue investigating other approaches, or should I document what I've found so far?"
+3. **Only stop when the user agrees** or when you've successfully captured quality screenshots
+
+### The "Engine Bug" Misconception
+
+When you identify a Category 4 issue (code generation bug), this does NOT mean you're blocked. It means:
+
+- The bug is in how CodeYam generates code (useful info for the CodeYam team)
+- You MUST still fix it manually by editing files in the tmp folder
+- You MUST still capture quality screenshots
+- You document what you fixed so the CodeYam team can improve the engine
+
+**"Engine bug" is a diagnosis category, not an excuse to stop.**
+
 ---
 
 ## Debug Flow Summary
@@ -25,11 +62,12 @@ Determine whether a capture failure can be fixed locally (via database changes)
 │          Retrieve the analysis id to use in the debug command       │
 │                    │                                                │
 │                    ▼                                                │
-│  Step 1: codeyam debug [ANALYSIS ID]  (generates files to inspect)  │
-│  Step 2: Identify error type from logs/output                       │
-│  Step 3: Diagnose root cause category (1-4)                         │
-│  Step 4: Attempt fix (database edit or universal mock)              │
-│  Step 5: Verify locally (curl returns 200)                          │
+│  Step 1: Copy the logs to a temporary location (see below).         |
+|  Step 2: codeyam debug [ANALYSIS ID]  (generates files to inspect)  │
+│  Step 3: Identify error type from logs/output                       │
+│  Step 4: Diagnose root cause category (1-4)                         │
+│  Step 5: Attempt fix (database edit or universal mock)              │
+│  Step 6: Verify locally (curl returns 200)                          │
 │                   │                                                 │
 │         ┌─────────┴─────────┐                                       │
 │         ▼                   ▼                                       │
@@ -43,12 +81,12 @@ Determine whether a capture failure can be fixed locally (via database changes)
 │         │         Verify without regenerating                       │
 │         │                   │                                       │
 │         ▼                   ▼                                       │
-│   Step 6: Recapture    Step 6: Recapture --capture-only             │
+│   Step 7: Recapture    Step 7: Recapture --capture-only             │
 │   (normal)             (preserves file fixes)                       │
 │         │                   │                                       │
 │         └─────────┬─────────┘                                       │
 │                   ▼                                                 │
-│   Step 7: Verify screenshots (check for client-side errors)         │
+│   Step 8: Verify screenshots (check for client-side errors)         │
 │                   │                                                 │
 │                   ▼                                                 │
 │   Verify ALL files exist on disk                                    │
@@ -59,16 +97,128 @@ Determine whether a capture failure can be fixed locally (via database changes)
 └─────────────────────────────────────────────────────────────────────┘
 ```
 
+**Logs:** Before debugging copy the original logs to a temorary location as the debugging will overwrite these logs and they are valuable for debugging issues.
+
+Original Logs Locaion: `/tmp/codeyam/local-dev/{slug}/codeyam/logs.txt`
+Temporary location: `/tmp/codeyam/local-dev/{slug}/debug/original-logs.txt`
+
+**Notice:** Both paths lead to "Recapture" and "Verify screenshots". There is no path that ends after just identifying a bug category. You must always capture quality screenshots before completing.
+
+---
+
+## MANDATORY: Session Context (Do This First!)
+
+Long debugging sessions cause context loss. To prevent forgetting critical information:
+
+### Step 1: Create Session Context File
+
+At the **very start** of debugging, create `.codeyam/debug-session.md` in the **original project directory**:
+
+```markdown
+# Debug Session Context
+
+**IMPORTANT**: Keep a todo item "📍 Re-read debug session context" that is NEVER marked complete.
+If the todo disappears, add it back immediately.
+
+## Key Locations
+
+- **Original project**: [FULL PATH - run all codeyam commands here]
+- **Tmp folder**: /tmp/codeyam/local-dev/[SLUG]/project (edit files here, do NOT run codeyam commands)
+- **Database**: [ORIGINAL PROJECT]/.codeyam/db.sqlite3
+- **Logs**: /tmp/codeyam/local-dev/[SLUG]/codeyam/log.txt
+
+## IDs
+
+- **Analysis ID**: [ID]
+- **Scenario ID**: [ID]
+- **Entity**: [NAME] at [FILE PATH]
+
+## URLs (fill in after running codeyam debug)
+
+- **Scenario URL**: http://localhost:[PORT]/static/codeyam-sample
+- **Dev server port**: [PORT from codeyam debug output]
+
+## Commands Reference
+
+All commands run from: [ORIGINAL PROJECT PATH]
+
+- `codeyam debug [ANALYSIS_ID]` - regenerate files (overwrites tmp folder!)
+- `codeyam recapture [ID]` - regenerate AND capture (overwrites tmp folder!)
+- `codeyam recapture [ID] --capture-only` - capture WITHOUT regenerating (preserves your edits)
+- `codeyam test-startup` - test startup (overwrites tmp folder!)
+```
+
+### Step 2: Create Persistent Todo
+
+Use TodoWrite to create this todo list with the first item being a persistent reminder:
+
+```
+📍 Re-read .codeyam/debug-session.md before any codeyam command (NEVER complete this)
+```
+
+**CRITICAL**: The first todo item must NEVER be marked as completed. It serves as a constant reminder to check your session context before running commands. If you accidentally complete it or it disappears, add it back immediately.
+
+### Step 3: Read Context Before Actions
+
+**Before running ANY of these commands**, re-read `.codeyam/debug-session.md`:
+
+- `codeyam debug`
+- `codeyam recapture`
+- `codeyam test-startup`
+- Any database queries
+
+This prevents running commands from the wrong directory or forgetting key IDs.
+
+---
+
+## Critical: Where to Run Commands
+
+**All `codeyam` commands MUST be run from the ORIGINAL PROJECT DIRECTORY**, not from the tmp folder.
+
+| Location                                                               | What's There                                                   | Run Commands Here?                                |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------- |
+| **Original project** (e.g., `/Users/.../clients-codeyam/boltwise/app`) | Database (`.codeyam/db.sqlite3`), config, universal mocks      | **YES - run all codeyam commands here**           |
+| **Tmp folder** (`/tmp/codeyam/local-dev/{slug}/project/`)              | Copy of project with mock injections, generated scenario files | **NO - only edit files here, don't run commands** |
+
+**Common mistake:** Running `codeyam recapture` from the tmp folder. This will fail with "Not in a CodeYam project" because the database doesn't exist there.
+
+```bash
+# WRONG - running from tmp folder
+cd /tmp/codeyam/local-dev/boltwise-app/project
+codeyam recapture abc123  # ❌ Fails: "Not in a CodeYam project"
+
+# CORRECT - running from original project directory
+cd /Users/jaredcosulich/workspace/codeyam/clients-codeyam/boltwise/app
+codeyam recapture abc123  # ✅ Works
+```
+
+**Workflow:**
+
+1. Edit files in `/tmp/codeyam/local-dev/{slug}/project/` to fix issues
+2. Test by curling the dev server running from the tmp folder
+3. **Switch back to the original project directory** to run `codeyam recapture`
+
 ---
 
 ## What You Can and Cannot Modify
 
 **NEVER modify the client's original source code in the workspace.** Only modify files in the tmp folder.
 
+### CRITICAL: Fix the Mocks, Never the Client Code
+
+When debugging errors, the fix is ALWAYS in the mock data or mock code—never in the client's components or application code.
+
+**If a component crashes due to unexpected data:**
+
+- Fix the mock data to provide what the component expects
+- Do NOT modify the component to handle the bad data
+
+**The client's code is sacred.** Our job is to make the simulation environment correct, not to "improve" or "harden" the client's code. Even if a component could be more defensive, that's not our fix to make.
+
 **You CAN modify:**
 
-- Data in the local SQLite database (`.codeyam/db.sqlite3`)
-- Universal mocks in `.codeyam/universal-mocks`
+- Data in the local SQLite database (`.codeyam/db.sqlite3`) - in the **original project directory**
+- Universal mocks in `.codeyam/universal-mocks` - in the **original project directory**
 - **Files in `/tmp/codeyam/local-dev/{slug}/project/`** - These are temporary copies used for simulation
   - Generated mock files in `__codeyamMocks__/` directories
   - Layout/route files that wrap scenarios
@@ -157,12 +307,12 @@ This is the most important step. Determine WHERE in the pipeline the bug origina
 
 ### The 4 Error Categories
 
-| Category | What's Wrong                                         | Where to Check            | Fixable Locally?       |
-| -------- | ---------------------------------------------------- | ------------------------- | ---------------------- |
-| **1**    | Missing attribute in `isolatedDataStructure`         | `entities.metadata`       | Sometimes (re-analyze) |
-| **2**    | Attribute not merged into `mergedDataStructure`      | `analyses.metadata`       | Sometimes (re-analyze) |
-| **3**    | Data structure complete, but scenario data wrong     | `scenarios.metadata`      | Yes (edit mockData)    |
-| **4**    | Data complete, but mock code/mock data written wrong | Generated files in `/tmp` | **No (engine bug)**    |
+| Category | What's Wrong                                         | Where to Check            | Fixable Locally?              |
+| -------- | ---------------------------------------------------- | ------------------------- | ----------------------------- |
+| **1**    | Missing attribute in `isolatedDataStructure`         | `entities.metadata`       | Sometimes (re-analyze)        |
+| **2**    | Attribute not merged into `mergedDataStructure`      | `analyses.metadata`       | Sometimes (re-analyze)        |
+| **3**    | Data structure complete, but scenario data wrong     | `scenarios.metadata`      | Yes (edit mockData)           |
+| **4**    | Data complete, but mock code/mock data written wrong | Generated files in `/tmp` | **Yes (edit files directly)** |
 
 ### Diagnostic Queries
 
@@ -201,7 +351,7 @@ sqlite3 .codeyam/db.sqlite3 \
 6. **Check generated mock code** - Is the mock code syntactically/semantically correct? If wrong → **Category 4 (engine bug)**
 7. **Check generated imports** - Are the imports correct? Are entities containing environment variables mocked out? If wrong → **Category 4 (engine bug)**
 
-### Category 4 Indicators (Engine Bug)
+### Category 4 Indicators (Code Generation Issue)
 
 The issue is Category 4 if:
 
@@ -210,6 +360,16 @@ The issue is Category 4 if:
 - BUT the generated mock code has syntax errors, wrong structure, or doesn't match the data
 - Database edits don't fix the generated code (it regenerates wrong)
 
+**Category 4 does NOT mean you are blocked.** You have full access to fix these issues:
+
+1. **Edit the files directly** in `/tmp/codeyam/local-dev/{slug}/project/`
+2. **Fix any syntax errors, wrong imports, missing mocks** - these are just TypeScript files
+3. **Restart the dev server** and verify the fix works
+4. **Capture quality screenshots** with `codeyam recapture --capture-only`
+5. **Document what you fixed** for the CodeYam team to improve the engine
+
+The term "engine bug" means the CodeYam code generation has a bug—it does NOT mean you cannot fix the issue locally. You always can.
+
 ---
 
 ## Step 4: Attempt Fix
@@ -261,9 +421,15 @@ EOF
 
 ### For Category 4 (Code Generation Issues)
 
-**CAN be fixed locally by editing files in the tmp folder!** See Step 5a below.
+**MUST be fixed locally by editing files in the tmp folder.** This is a REQUIRED step, not optional.
 
-After fixing, use `codeyam recapture --capture-only` to capture without regenerating the (now-fixed) files.
+1. Go to Step 5a and fix all code issues in the tmp folder
+2. Verify the scenario loads correctly (curl returns 200)
+3. Run `codeyam recapture --capture-only` to capture screenshots (this preserves your fixes)
+4. Verify the screenshots look correct
+5. THEN document the engine bug in your final report
+
+**DO NOT stop after identifying a Category 4 issue.** The goal is to capture quality screenshots, then document what you fixed.
 
 ### Universal Mocks (for infrastructure dependencies)
 
@@ -322,7 +488,9 @@ After making **database changes** (Categories 1-3):
 
 ## Step 5a: Fix Code Issues in Tmp Folder (Category 4)
 
-If the error is in bad imports, generated code or mock files, you can fix them directly in the tmp folder:
+If the error is in bad imports, generated code or mock files, you can fix them directly in the tmp folder.
+
+**REMINDER: Only fix GENERATED files (mocks, layouts, routes)—never the client's application code.** If a client component crashes, the fix is in the mock data or mock code, not in the component itself.
 
 ### Locate the Problematic File
 
@@ -361,11 +529,19 @@ cd /tmp/codeyam/local-dev/{slug}/project
 npm run dev  # or pnpm dev / yarn dev
 ```
 
-Then curl the scenario URL to verify the fix works:
+Then verify the fix works. You can either:
 
-```bash
-curl -s http://localhost:3112/static/codeyam-sample | head -50
-```
+1. **Curl the URL** to check for errors:
+
+   ```bash
+   curl -s http://localhost:3112/static/codeyam-sample | head -50
+   ```
+
+2. **Ask the user to verify visually**: If the fix involves visual output or you're unsure if it worked, ask the user to visit the URL and confirm:
+
+   > "I've fixed the mock data. Can you visit http://localhost:3112/static/codeyam-sample and let me know if the component renders correctly now?"
+
+   This is especially useful for client-side rendering issues that curl won't catch.
 
 ---
 
@@ -574,8 +750,10 @@ If this is an engine bug, include:
 
 ### Verification
 
+**All of these must be checked before the debug session is complete:**
+
 - [ ] Scenario loads without errors (curl returns 200)
-- [ ] Screenshots recaptured successfully
+- [ ] Screenshots recaptured successfully (this is REQUIRED, not optional)
 - [ ] Used `--capture-only` flag (if file changes were made)
 - [ ] Screenshot files verified to exist on disk
 - [ ] Screenshots visually inspected - no client-side errors visible