@codeyam/codeyam-cli 0.1.0-staging.b8a55ba → 0.1.0-staging.c90f8c9

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,6 +97,107 @@ 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
@@ -67,8 +206,8 @@ Determine whether a capture failure can be fixed locally (via database changes)
 
 **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 +296,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
 
@@ -199,8 +338,9 @@ sqlite3 .codeyam/db.sqlite3 \
 4. **Check `scenariosDataStructure`** - Is the data structure for mocks correct? If wrong → Category 2
 5. **Check scenario `mockData`** - Does the scenario have correct mock values? If wrong → Category 3
 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:
 
@@ -209,6 +349,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
@@ -260,9 +410,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.
+
+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
 
-After fixing, use `codeyam recapture --capture-only` to capture without regenerating the (now-fixed) files.
+**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)
 
@@ -321,7 +477,7 @@ After making **database changes** (Categories 1-3):
 
 ## Step 5a: Fix Code Issues in Tmp Folder (Category 4)
 
-If the error is in 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:
 
 ### Locate the Problematic File
 
@@ -458,6 +614,8 @@ Then read the screenshot file to visually inspect it.
 - **Missing components** or broken layouts
 - **Console errors** shown in error overlays
 
+If the screenshot shows a dedicated 500 page with no clear error then you may want to find and comment out any error boundary logic that is catching errors and preventing you from easily reading them.
+
 ### If Screenshot Shows Errors
 
 1. The fix didn't fully work - go back to Step 5 or 5a
@@ -571,8 +729,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
@@ -593,7 +753,9 @@ After completing the debug session, **you MUST save the report**:
    ```
 
 2. **Ask user if they want to upload:**
-   After saving, ask the user: "Would you like to upload this debug report to CodeYam for the team to review? Run: `codeyam report --upload`"
+   After saving, ask the user: "Would you like me to upload this debug report to CodeYam for the team to review?"
+
+- If the user response affirmatively then run `codeyam report --upload` to upload the report.
 
 The report will be:
 

package/codeyam-cli/templates/codeyam:new-rule.md

@@ -0,0 +1,13 @@
+---
+name: codeyam:new-rule
+autoApprove: true
+description: |
+  Create a new Claude Rule for documenting codebase patterns.
+  Use when: User wants to add documentation for a specific area of the codebase.
+---
+
+# Create New Claude Rule
+
+Read `.codeyam/rules/instructions.md` for guidance on how to create and structure a new rule.
+
+If the instructions file doesn't exist, inform the user they should run `/codeyam:power-rules` first to set up the rules system.