@codeyam/codeyam-cli 0.1.0-staging.323686 → 0.1.0-staging.483fdc2

package/codeyam-cli/src/webserver/build/server/index.js

@@ -1 +1 @@
-import{Y as I,M as J,N as K,W as L,O as Z,R as _,T as $,V as rr,U as tr,X as or,Q as ir}from"./assets/server-build-4Cr0uToj.js";import"react/jsx-runtime";import"node:stream";import"@react-router/node";import"react-router";import"isbot";import"react-dom/server";import"react";import"lucide-react";import"fetch-retry";import"better-sqlite3";import"pg";import"fs";import"path";import"kysely";import"kysely/helpers/sqlite";import"kysely/helpers/postgres";import"typescript";import"fs/promises";import"os";import"prompts";import"chalk";import"crypto";import"child_process";import"url";import"util";import"dotenv";import"events";import"uuid";import"openai";import"p-queue";import"p-retry";import"@aws-sdk/client-dynamodb";import"lru-cache";import"pluralize";import"piscina";import"json5";import"@aws-sdk/util-dynamodb";import"v8";import"react-syntax-highlighter";import"react-syntax-highlighter/dist/cjs/styles/prism/index.js";import"node:crypto";import"minimatch";import"react-markdown";import"remark-gfm";import"react-diff-viewer-continued";export{I as assets,J as assetsBuildDirectory,K as basename,L as entry,Z as future,_ as isSpaMode,$ as prerender,rr as publicPath,tr as routeDiscovery,or as routes,ir as ssr};
+import{Y as H,Z as I,M as J,N as K,W as L,O as _,R as $,T as rr,V as tr,U as or,X as ir,Q as pr}from"./assets/server-build-BQ-1XyEa.js";import"react/jsx-runtime";import"node:stream";import"@react-router/node";import"react-router";import"isbot";import"react-dom/server";import"react";import"lucide-react";import"fetch-retry";import"better-sqlite3";import"pg";import"fs";import"path";import"kysely";import"kysely/helpers/sqlite";import"kysely/helpers/postgres";import"typescript";import"fs/promises";import"os";import"prompts";import"chalk";import"crypto";import"child_process";import"url";import"util";import"dotenv";import"events";import"uuid";import"openai";import"p-queue";import"p-retry";import"@aws-sdk/client-dynamodb";import"lru-cache";import"pluralize";import"piscina";import"json5";import"@aws-sdk/util-dynamodb";import"v8";import"react-syntax-highlighter";import"react-syntax-highlighter/dist/cjs/styles/prism/index.js";import"node:crypto";import"minimatch";import"react-markdown";import"remark-gfm";import"react-diff-viewer-continued";export{H as allowedActionOrigins,I as assets,J as assetsBuildDirectory,K as basename,L as entry,_ as future,$ as isSpaMode,rr as prerender,tr as publicPath,or as routeDiscovery,ir as routes,pr as ssr};

package/codeyam-cli/src/webserver/build-info.json

@@ -1,7 +1,7 @@
 {
-  "buildTimestamp": "2026-01-30T00:55:49.390Z",
-  "buildTime": 1769734549390,
-  "buildNumber": 569,
-  "semanticVersion": "0.1.569",
-  "version": "0.1.569 (2026-01-30T00:55)"
+  "buildTimestamp": "2026-02-04T17:33:55.043Z",
+  "buildTime": 1770226435043,
+  "buildNumber": 583,
+  "semanticVersion": "0.1.583",
+  "version": "0.1.583 (2026-02-04T17:33)"
 }

package/codeyam-cli/templates/codeyam:memory.md

@@ -3,13 +3,29 @@ name: codeyam:memory
 autoApprove: true
 description: |
   Generate and maintain Claude Rules for your codebase based on thorough analysis.
-  Use when: User wants to set up memory, claude rules, document confusing areas, 
+  Use when: User wants to set up memory, claude rules, document confusing areas,
   or ensure Claude has proper context for working in the codebase.
 ---
 
 # CodeYam Memory Assistant
 
-This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that provide context-specific guidance. The goal is robust coverage of anything confusing while avoiding documentation of things Claude can intuit.
+This skill helps you generate and maintain Claude Rules (`.claude/rules/`) that provide context-specific guidance. The goal is to **document genuinely confusing aspects** of the codebase—not things Claude can figure out by reading code.
+
+## Core Principle: Document Confusion, Not Information
+
+**Good rules** explain things that are NOT obvious from reading the code:
+
+- Historical context (why code evolved this way)
+- Hidden relationships (files that must change together)
+- Gotchas that caused bugs
+- Non-obvious conventions
+
+**Bad rules** document things Claude can easily ascertain:
+
+- What functions do (Claude can read the code)
+- Type definitions (Claude can see them)
+- Directory structure (Claude can explore it)
+- Basic patterns (Claude knows common patterns)
 
 ## When to Use This Skill
 
@@ -43,9 +59,9 @@ Please see `.codeyam/rules/instructions.md` for guidance.
 After making any code changes please run `codeyam memory status` and follow the instructions.
 ```
 
-### 1B. Create Instructions File
+### 1B. Verify Instructions File
 
-Create `.codeyam/rules/instructions.md` with the content from the Instructions File section at the end of this document.
+Check that `.codeyam/rules/instructions.md` exists (it should be created during `codeyam init`). If missing, copy it from `codeyam-cli/templates/rules-instructions.md`.
 
 ### 1C. Install Pre-commit Hook
 
@@ -66,176 +82,170 @@ Ensure `.codeyam/bin/memory-hook.sh` exists and is executable (`chmod +x`).
 
 ---
 
-## Phase 2: Deep Codebase Analysis
+## Phase 2: Confusion Archaeology
 
-Perform thorough analysis to identify areas that may be confusing. The goal is to find everything that might trip up someone (or Claude) working in this codebase.
+The goal is to find areas where developers have **struggled**—not just areas that are complex. High churn alone doesn't mean confusion; we're looking for patterns that indicate something is genuinely non-obvious.
 
-### 2A. Analyze Git Commit Messages for Problem Signals
+### 2A. Find Confusion Signals in Commit History
 
-Look for commits indicating gotchas, workarounds, or complexity:
+**Files with rapid successive changes** (same file, multiple commits in short windows = iteration/confusion):
 
 ```bash
-# Find commits with problem-indicating keywords
-git log --oneline --since="6 months ago" --grep="fix" --grep="bug" --grep="workaround" --grep="hack" --grep="revert" --grep="oops" --grep="forgot" --grep="actually" --all-match | head -30
+# Files changed 3+ times in last month (rapid iteration signal)
+git log --since="1 month ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | awk '$1 >= 3 {print}' | head -20
+```
 
-# Find commits with long messages (indicate complex changes)
-git log --since="6 months ago" --format="%h %s" | awk 'length($0) > 80' | head -20
+**Reverts** (definite confusion signals—someone made a change that didn't work):
 
-# Find reverted commits
-git log --oneline --since="6 months ago" --grep="revert" -i | head -10
+```bash
+git log --since="6 months ago" --oneline --grep="[Rr]evert" | head -10
 ```
 
-For interesting commits, examine the full message and changes:
+**Correction language** (commits that fix misunderstandings):
 
 ```bash
-git show <commit-hash> --stat
-git log -1 --format="%B" <commit-hash>
+git log --since="6 months ago" --oneline | grep -iE "(oops|forgot|actually|wrong|typo|missing|should have|meant to)" | head -15
 ```
 
-### 2B. Identify Files with High Churn or Complexity Signals
+**Files with multiple fix commits** (confusion hotspots):
 
 ```bash
-# Files changed most frequently (last 6 months)
-git log --since="6 months ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -30
+git log --since="3 months ago" --oneline --grep="fix" -i --name-only --pretty=format: | sort | uniq -c | sort -rn | awk '$1 >= 2 {print}' | head -15
+```
 
-# Files with many different authors (tribal knowledge risk)
-git shortlog -sn --since="6 months ago" -- . | head -20
+**Long commit messages** (someone felt the need to explain—complexity that needs documentation):
 
-# Files frequently modified together (hidden dependencies)
-git log --since="6 months ago" --name-only --pretty=format: | awk '/^$/{if(NR>1)print "---"}; /./{print}' | head -100
+```bash
+git log --since="6 months ago" --format="%h %s" | awk 'length($0) > 100' | head -15
 ```
 
-Look for patterns where the same 2-3 files appear together repeatedly.
+### 2B. Dig Into High-Confusion Files
 
-### 2C. Scan for Developer Notes in Code
+For each file that shows confusion signals, examine its evolution:
 
 ```bash
-# Find TODO, FIXME, HACK, XXX, NOTE comments
-grep -rn "TODO\|FIXME\|HACK\|XXX\|NOTE:" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" --include="*.rb" --include="*.go" --include="*.java" --include="*.rs" . 2>/dev/null | head -50
+# View the story of changes to understand what kept going wrong
+git log --since="6 months ago" --oneline -- path/to/confusing-file.ts
 
-# Find "workaround" or "hack" mentions in comments
-grep -rni "workaround\|hack\|temporary\|legacy" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -30
+# Read the full commit messages for context
+git log --since="6 months ago" --format="%h %s%n%b" -- path/to/confusing-file.ts | head -100
 ```
 
-### 2D. Analyze Project Structure
+**As you analyze, ask:**
 
-```bash
-# Get directory structure (2 levels deep)
-find . -type d -maxdepth 3 | grep -v node_modules | grep -v .git | grep -v dist | grep -v build | head -50
+- What was the initial implementation?
+- What kept breaking or needed fixing?
+- What was non-obvious about the fix?
+- What knowledge would have prevented the issue?
 
-# Find config files
-find . -name "*.config.*" -o -name "*.rc" -o -name ".env*" -o -name "tsconfig*" -o -name "package.json" 2>/dev/null | grep -v node_modules | head -30
+### 2C. Find Hidden Dependencies
 
-# Find test directories
-find . -type d -name "*test*" -o -type d -name "*spec*" -o -type d -name "__tests__" 2>/dev/null | grep -v node_modules | head -20
+**Files that always change together** (may have non-obvious relationships):
+
+```bash
+# Look for file pairs that frequently appear in the same commits
+git log --since="3 months ago" --name-only --pretty=format: | awk 'NF' | sort | uniq -c | sort -rn | head -30
 ```
 
-### 2E. Check for Environment and Configuration Complexity
+When you see the same files appearing together repeatedly, investigate why they're coupled.
 
-```bash
-# Find environment variable references
-grep -rn "process.env\|os.environ\|ENV\[" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.py" . 2>/dev/null | head -30
+### 2D. Scan for Developer Notes
 
-# Find multiple config files that might conflict or confuse
-ls -la *.config.* .*.rc tsconfig*.json 2>/dev/null
+**TODO/FIXME/HACK comments** often mark confusion points:
+
+```bash
+grep -rn "TODO\|FIXME\|HACK\|XXX" --include="*.ts" --include="*.tsx" --include="*.js" --include="*.jsx" --include="*.py" . 2>/dev/null | head -30
 ```
 
-### 2F. Review Existing Documentation
+Focus on comments that explain **why** something is the way it is, not just **what** needs to be done.
 
-Read these files if they exist:
+### 2E. Review Existing Documentation
+
+Read these files if they exist to understand what's already documented:
 
 - `README.md`
 - `CLAUDE.md`
 - `CONTRIBUTING.md`
 - `docs/` directory
-- Any `*.md` files in the root
-
-Note what's already documented and what gaps exist.
 
-### 2G. Examine Import/Dependency Patterns
-
-```bash
-# Find files with many imports (high coupling)
-for f in $(find . -name "*.ts" -o -name "*.tsx" -o -name "*.js" 2>/dev/null | grep -v node_modules | head -100); do
-  count=$(grep -c "^import\|^from\|require(" "$f" 2>/dev/null || echo 0)
-  if [ "$count" -gt 15 ]; then
-    echo "$count $f"
-  fi
-done | sort -rn | head -20
-
-# Find commonly imported local modules (core utilities)
-grep -rh "from '\.\|from \"\.\|require('\.\|require(\"\." --include="*.ts" --include="*.tsx" --include="*.js" . 2>/dev/null | sort | uniq -c | sort -rn | head -20
-```
+Note gaps between what's documented and the confusion signals you found.
 
 ---
 
-## Phase 3: Cluster and Prioritize Findings
+## Phase 3: Distinguish Important from Confusing
 
-After gathering signals, organize them by area/module:
+Not all high-churn areas need documentation. Filter your findings:
 
-1. **Group findings by directory** - Which parts of the codebase have the most signals?
-2. **Identify themes**:
-   - Architecture patterns (how things connect)
-   - Testing complexity (special setup needed)
-   - Configuration/environment gotchas
-   - Historical workarounds still in place
-   - Non-obvious conventions
+### Skip These (High Churn but NOT Confusing)
 
-3. **Score areas** - More signals = higher priority for documentation
+- Lock files (`pnpm-lock.yaml`, `package-lock.json`)
+- Build outputs (`dist/`, `build/`)
+- Generated files (`.build-info.json`, etc.)
+- Files with mechanical changes (version bumps, auto-formatting)
 
-Create a mental map of:
+### Document These (High Churn AND Confusing)
 
-- Which directories/modules are most complex?
-- What relationships exist between different parts?
-- Where are the gotchas hiding?
+- Files with multiple fix commits in short windows
+- Files with reverts (someone's approach didn't work)
+- Files where commit messages explain complex reasoning
+- Files where the same area keeps breaking
+- Files that must change together but aren't obviously related
 
----
+### Confusion Scoring
 
-## Phase 4: Ask Specific Questions
+Prioritize areas with stronger confusion signals:
 
-Based on your analysis, ask the user specific questions about the actual findings. Reference the concrete evidence you found (file names, commit messages, code patterns) and ask about the substance.
+| Signal                    | Weight | Example                           |
+| ------------------------- | ------ | --------------------------------- |
+| Reverts                   | 5      | "Revert 'Track useState sources'" |
+| Correction language       | 5      | "Oops, forgot to import..."       |
+| Follow-up fix within days | 5      | Fix commit 2 days after change    |
+| "Workaround" or "hack"    | 3      | "Workaround for webpack issue"    |
+| Long commit message       | 3      | >100 chars explaining complexity  |
+| Multiple fix commits      | 2      | 3+ fixes to same file             |
+| Numbered fix series       | 1      | "Analysis Fixes 4", "Fixes 5"     |
 
-Always include "I'm not sure - please investigate" as an option so users can delegate investigation to you.
+Focus your documentation efforts on areas with the highest confusion scores.
+
+---
 
-### Question Format
+## Phase 4: Ask Evidence-Based Questions
 
-Ask about the **specific finding**, not the file generally:
+Questions must reference **specific confusion evidence** you found. Don't ask generic questions about files; ask about the specific commits, patterns, or problems you discovered.
 
-**For high-churn files with concerning commits:**
+Always include "I'm not sure - please investigate" as an option so users can delegate investigation to you.
 
-> "ScopeDataStructure.ts has commits mentioning 'exponential blowup' and 'execution flows'. What causes this blowup? When does it happen?"
->
-> Options: [Explain the cause] [I'm not sure - please investigate]
+### Question Examples
 
-**For files frequently modified together:**
+**For rapid successive changes:**
 
-> "`src/api/auth.ts` and `src/middleware/session.ts` are modified together in 12 commits. Why do these need to change together?"
+> "I found 5 commits to `ScopeDataStructure.ts` in 3 weeks, including 'Fix exponential blowup' and 'scope data structure optimization'. What kept causing issues here? What would someone need to know to avoid similar problems?"
 >
-> Options: [Explain the relationship] [I'm not sure - please investigate]
+> Options: [Explain the pattern] [I'm not sure - please investigate]
 
-**For commits with workaround language:**
+**For reverts:**
 
-> "Commit `abc123` says 'workaround for webpack issue'. What's the underlying issue and what's the workaround?"
+> "Commit `a9fbd6385` reverted 'Track useState initialization sources'. Why didn't that approach work? What should be done instead?"
 >
-> Options: [Explain] [I'm not sure - please investigate]
+> Options: [Explain what went wrong] [I'm not sure - please investigate]
 
-**For multiple config files:**
+**For correction commits:**
 
-> "There are 3 tsconfig files. When is each one used?"
+> "Commit `31e4a3842` says 'Oops, lost an import'. What import was lost and why is it easy to miss?"
 >
-> Options: [Explain usage] [I'm not sure - please investigate]
+> Options: [Explain the gotcha] [I'm not sure - please investigate]
 
-**For TODO/FIXME comments:**
+**For files that change together:**
 
-> "There's a FIXME in `src/parser.ts:142` about 'handle nested callbacks'. What's the issue with nested callbacks here?"
+> "I noticed `auth.ts` and `session.ts` are modified together in 8 commits. Is there an invariant that must be maintained between them? What would break if someone changed one without the other?"
 >
-> Options: [Explain] [I'm not sure - please investigate]
+> Options: [Explain the relationship] [I'm not sure - please investigate]
 
-**For test organization:**
+**For long explanatory commits:**
 
-> "Tests are split between `__tests__/` folders and colocated `*.test.ts` files. When should each approach be used?"
+> "Commit `abc123` has a detailed message about 'why we need to track execution flows separately'. What's the key insight here that should be documented?"
 >
-> Options: [Explain convention] [I'm not sure - please investigate]
+> Options: [Summarize the insight] [I'm not sure - please investigate]
 
 ### Process
 
@@ -249,11 +259,59 @@ Ask about the **specific finding**, not the file generally:
 
 ---
 
-## Phase 5: Generate Rules
+## Phase 5: Generate and Validate Rules
+
+For each area where you have enough information, create a rule file—but **validate it first**.
+
+### 5A. Rule Validation (Before Writing)
+
+Before generating each rule, verify it passes these tests:
+
+**1. Evidence check**: Does the rule reference actual confusion evidence from commit history?
+
+- If no evidence of confusion, reconsider whether the rule is needed
+
+**2. Code-derivable check**: Read the files the rule will cover. Could the rule's content be determined by reading those files alone?
+
+- If YES → rule probably not needed (Claude can read the code)
+- If NO (historical context, edge cases, non-obvious behavior) → rule is valuable
+
+**3. Prevention check**: Would this rule have prevented one of the confusion commits you found?
+
+- If YES → definitely document it
+- If NO → reconsider its value
+
+### Rule Quality Examples
+
+**✅ Good rule** (passes all tests):
 
-For each area where you have enough information, create a rule file.
+```markdown
+## Path Prefix Matching Must Check Boundaries
+
+When checking if one schema path is a prefix of another using `startsWith()`,
+you must verify the match is at a path boundary. Otherwise sibling properties
+with similar names incorrectly match.
+
+This caused a bug where `entity` matched `entityCode` (siblings, not parent-child).
+```
 
-### Rule File Guidelines:
+- Evidence: Learned from actual bug (commit history evidence)
+- Not code-derivable: Code doesn't explain why boundary checking matters
+- Prevention: Would prevent future prefix-matching bugs
+
+**❌ Bad rule** (fails tests):
+
+```markdown
+## Running Tests
+
+Use `pnpm jest` to run tests. Configuration is in `jest.config.ts`.
+```
+
+- No confusion evidence (no commits showing people struggled with this)
+- Code-derivable: Anyone can see `jest.config.ts` exists
+- Doesn't prevent any confusion
+
+### 5B. Rule File Guidelines
 
 1. **Location mirrors code structure**
    - Rule for `src/api/` → `.claude/rules/src/api/architecture.md`
@@ -263,16 +321,15 @@ For each area where you have enough information, create a rule file.
    - Good: `paths: ['src/api/**/*.ts']`
    - Bad: `paths: ['**/*.ts']` (too broad, wastes context)
 
-3. **Content should be actionable**
-   - Focus on "how to" and "what to know"
-   - Avoid warnings unless truly critical
+3. **Content should explain "why" not just "what"**
+   - Focus on the reasoning, history, or gotcha
    - Be concise - every word costs context
 
 4. **Timestamp must be current**
    - Use ISO 8601 format: `2026-01-27T15:30:00Z`
    - This enables the pre-commit hook enforcement
 
-### Rule Template:
+### Rule Template
 
 ```markdown
 ---
@@ -284,11 +341,15 @@ timestamp: [CURRENT_ISO_TIMESTAMP]
 
 ## [Clear, Descriptive Title]
 
-[Concise explanation of what this covers]
+[What's the gotcha/insight/non-obvious thing?]
+
+### Why This Matters
+
+[What would go wrong if someone didn't know this?]
 
-### [Section as appropriate]
+### The Solution/Pattern
 
-[Specific, actionable content]
+[What should someone do differently?]
 ```
 
 ---
@@ -298,6 +359,7 @@ timestamp: [CURRENT_ISO_TIMESTAMP]
 After generating rules based on your analysis and user answers:
 
 1. **Present a summary** of all rules created
+
 2. **Ask the user:**
 
    > "I've created rules covering [list areas]. Are there any other areas of the codebase that you know are confusing or have tribal knowledge that I might have missed?"
@@ -339,124 +401,3 @@ To proceed:
 2. Update content if needed
 3. Update the `timestamp` to current time
 4. Stage and commit
-
----
-
-## Instructions File Content
-
-Create `.codeyam/rules/instructions.md` with this content:
-
-```markdown
-# Memory Guide
-
-## Maintaining Rules
-
-- It is your responsibility to maintain all rules
-- Rules should be concise and to the point. We want to be very conscientious about abusing the context window with too much text.
-- Use bullets and tables to communicate information efficiently
-- Review relevant rules after every code change using `codeyam memory status`
-- Constantly seek to improve rules. They will ensure every future coding session is more effective!
-
-## Editing Rules
-
-We focus on three categories of documentation:
-
-1. Architecture
-
-- Any time there is a specific relationship between files please capture the architecture
-- Note how the files relate, how data flows, and how changes should be approached
-
-2. Testing
-
-- For complex areas of the app where both manual and automated testing is complex track:
-  - Helpful commands used in debugging and testing
-  - Where test files are located if it is not obvious (and the command to run them if not obvious)
-
-3. FAQ
-
-- If you are ever confused about something that does not fit into the above categories document it here.
-- Anything you have to figure out or ask the user about should be captured here.
-
-**Please do not add to rules that are serving a different purpose. Create a new rule.**
-
-- Rules should be short and concise. Look for opportunities to improve them.
-- Use bullets and tables to communicate information efficiently.
-- Break up rules and create new rules if they are getting too long or are discussin different topics.
-
-## Creating a New Rule
-
-1. **Ask the user** If not obvious ask the user what they want to document (architecture, testing pattern, or gotcha/FAQ)
-2. **Read the relevant source files** to understand the patterns
-3. **Ask clarifying questions** if anything is unclear
-4. **Determine the file location** - rules mirror the source code structure (see below)
-5. **Create the rule file** with proper YAML frontmatter and concise content
-6. **Remind the user** to commit the rule and suggest running `codeyam` to view it in the dashboard
-
-## File Locations
-
-Rules mirror the source code structure:
-
-| Source Path          | Rule Path                                 |
-| -------------------- | ----------------------------------------- |
-| `src/api/auth.ts`    | `.claude/rules/src/api/auth.md`           |
-| `src/utils/**`       | `.claude/rules/src/utils/architecture.md` |
-| Project-wide testing | `.claude/rules/testing-patterns.md`       |
-
-## YAML Frontmatter (Required)
-
-Every rule file MUST have this structure:
-
-## \`\`\`yaml
-
-paths:
-
-- 'specific/path/\*_/_.ts'
-- 'another/path/\*.tsx'
-  category: architecture | testing | faq
-  timestamp: 2026-01-27T15:30:00Z
-
----
-
-\`\`\`
-
-### Fields
-
-| Field       | Required | Description                                          |
-| ----------- | -------- | ---------------------------------------------------- |
-| `paths`     | Yes      | Glob patterns - be specific to avoid wasting context |
-| `category`  | Yes      | `architecture`, `testing`, or `faq`                  |
-| `timestamp` | Yes      | ISO 8601 - must update when reviewing rule           |
-
-### Timestamp Enforcement
-
-The pre-commit hook blocks commits when:
-
-- You modify files matching a rule's `paths`
-- The rule's `timestamp` is older than your changes
-
-To proceed: review the rule, update timestamp, commit.
-
-## Content Guidelines
-
-### Be Specific and Actionable
-
-- Good: "Run `pnpm test:api` for API tests, `pnpm test:ui` for component tests"
-- Bad: "Make sure to run the appropriate tests"
-
-### Be Concise
-
-Every word costs context window space. Trim aggressively.
-
-### Focus on Positive Instructions
-
-- Good: "Auth tokens are stored in httpOnly cookies managed by `src/auth/cookies.ts`"
-- Bad: "WARNING: Don't store tokens in localStorage!"
-
-## Categories
-
-**architecture** - Design decisions, file relationships, data flow, "why X is done this way"
-
-**testing** - Test commands, mock patterns, fixtures, "how to test X"
-
-**faq** - Gotchas, workarounds, common questions, "if you see X, do Y"
-```

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

@@ -8,6 +8,45 @@ description: |
 
 # Create New Claude Rule
 
-Read `.codeyam/rules/instructions.md` for guidance on how to create and structure a new rule.
+## Before Creating: The Confusion Test
 
-If the instructions file doesn't exist, inform the user they should run `/codeyam:memory` first to set up the rules system.
+Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code.
+
+**Ask yourself:**
+
+1. **Could Claude figure this out by reading the code?**
+   - If YES → don't create the rule
+   - If NO → proceed
+
+2. **Does this explain "why" not just "what"?**
+   - Good: Historical context, gotchas, non-obvious behavior
+   - Bad: What functions do, how files are structured
+
+3. **Would this have prevented a past mistake?**
+   - If you can point to a bug or confusion this would have prevented → create it
+   - If it's just "nice to know" → skip it
+
+## Creating the Rule
+
+Read `.codeyam/rules/instructions.md` for detailed guidance on structure and formatting.
+
+If the instructions file doesn't exist, copy it from `codeyam-cli/templates/rules-instructions.md`.
+
+### Quick Template
+
+```markdown
+---
+paths:
+  - 'specific/path/**/*.ts'
+category: architecture | testing | faq
+timestamp: [CURRENT_ISO_TIMESTAMP]
+---
+
+## [Clear, Descriptive Title]
+
+[What's the gotcha/insight/non-obvious thing?]
+
+### Why This Matters
+
+[What would go wrong if someone didn't know this?]
+```