@codeyam/codeyam-cli 0.1.0-staging.62d4615 → 0.1.0-staging.693b02d

package/codeyam-cli/templates/rule-reflection-hook.py

@@ -2,11 +2,13 @@
 """
 Rule reflection hook for Claude Code.
 
-Two responsibilities, now split into independent agents:
-1. Check for stale rules (files changed since rule was last reviewed) and prompt review
-2. Review conversation for confusion signals (mistakes, corrections, interruptions)
+Handles two hook events:
+1. Stop — Reviews completed turns for stale rules and conversation confusion signals
+2. UserPromptSubmit — Detects user interruptions (Escape/Ctrl+C) by checking if the
+   Stop hook's marker file is stale, then spawns a rule-reflection agent focused on
+   the interruption signal
 
-Each fires as a separate `claude -p` invocation so the LLM can focus on one task at a time.
+Each review fires as a separate `claude -p` invocation so the LLM can focus on one task at a time.
 Stays silent if there's nothing to review.
 
 Prompt text lives in templates/prompts/*.txt (single source of truth shared with TypeScript tests).
@@ -16,6 +18,7 @@ import json
 import os
 import subprocess
 import sys
+from datetime import datetime
 from pathlib import Path
 
 MIN_USER_TURNS = 3  # Minimum user turns before checking for confusion
@@ -117,6 +120,51 @@ def read_rule_content(rule_name):
     return text
 
 
+def get_project_slug():
+    """
+    Derive project slug from .codeyam/config.json (matching getProjectSlug() on the TS side).
+    Falls back to os.path.basename(project_dir) if config is absent or malformed.
+    """
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+    try:
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        slug = config.get('projectSlug', '')
+        if slug:
+            return slug
+    except (IOError, json.JSONDecodeError, KeyError):
+        pass
+    return os.path.basename(project_dir)
+
+
+def load_memory_settings():
+    """
+    Load memory settings from .codeyam/config.json.
+    Returns dict with safe defaults when absent or malformed.
+    """
+    defaults = {
+        'conversationReflection': True,
+        'ruleMaintenance': True,
+        'promptModel': 'haiku',
+    }
+    try:
+        project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+        config_path = os.path.join(project_dir, '.codeyam', 'config.json')
+        with open(config_path, 'r') as f:
+            config = json.load(f)
+        memory = config.get('memory', {})
+        if not isinstance(memory, dict):
+            return defaults
+        return {
+            'conversationReflection': memory.get('conversationReflection', True),
+            'ruleMaintenance': memory.get('ruleMaintenance', True),
+            'promptModel': memory.get('promptModel', 'haiku'),
+        }
+    except (IOError, json.JSONDecodeError, KeyError):
+        return defaults
+
+
 def get_stale_rules():
     """
     Run `codeyam memory status` and parse the output to find stale rules.
@@ -154,8 +202,8 @@ def get_stale_rules():
                 # Look for the next few lines for details
                 for j in range(i + 1, min(i + 4, len(lines))):
                     detail = lines[j].strip()
-                    if detail.startswith('Rule timestamp:'):
-                        rule_info['rule_timestamp'] = detail.replace('Rule timestamp:', '').strip()
+                    if detail.startswith('Last audited:'):
+                        rule_info['last_audited'] = detail.replace('Last audited:', '').strip()
                     elif detail.startswith('Newest file:'):
                         rule_info['newest_file'] = detail.replace('Newest file:', '').strip()
                     elif detail.startswith('File modified:'):
@@ -250,6 +298,28 @@ def get_conversation_context(transcript_path, last_line):
     return user_turn_count, conversation_snippets, modified_files, current_line_count
 
 
+def has_assistant_messages(transcript_path, start_line):
+    """
+    Check if there are any assistant messages in the transcript after start_line.
+    Used to confirm Claude actually started responding before treating a gap as an interruption.
+    """
+    try:
+        with open(transcript_path, 'r') as f:
+            all_lines = f.readlines()
+    except IOError:
+        return False
+
+    for line in all_lines[start_line:]:
+        try:
+            obj = json.loads(line)
+            if obj.get('type') == 'assistant':
+                return True
+        except (json.JSONDecodeError, KeyError):
+            continue
+
+    return False
+
+
 def build_stale_rules_context(stale_rules):
     """Build context content for stale rules review."""
     parts = []
@@ -261,7 +331,7 @@ def build_stale_rules_context(stale_rules):
     parts.append("For each rule, review the rule content and the diff of changes, then:")
     parts.append("1. Determine if the rule content needs updating based on the code changes")
     parts.append("2. Update the rule if needed")
-    parts.append("3. ALWAYS update the timestamp (run `codeyam memory touch`)\n")
+    parts.append("3. Run `codeyam memory touch <rule-path1> <rule-path2> ...` with the SPECIFIC rule paths you reviewed to mark them as audited\n")
 
     for rule in stale_rules:
         parts.append(f"### {rule['name']}")
@@ -273,8 +343,8 @@ def build_stale_rules_context(stale_rules):
             parts.append(f"  Changed file: {rule['newest_file']}")
         if rule.get('file_modified'):
             parts.append(f"  File modified: {rule['file_modified']}")
-        if rule.get('rule_timestamp'):
-            parts.append(f"  Rule timestamp: {rule['rule_timestamp']}")
+        if rule.get('last_audited'):
+            parts.append(f"  Last audited: {rule['last_audited']}")
         if rule.get('diff'):
             parts.append(f"  Changes:")
             for line in rule['diff'].split('\n'):
@@ -314,7 +384,41 @@ def build_conversation_context(conversation_snippets, modified_files):
     return '\n'.join(parts)
 
 
-def spawn_claude_agent(prompt, log_file, project_dir):
+def build_interruption_context(conversation_snippets, follow_up_prompt, modified_files):
+    """Build context content for an interrupted session review."""
+    parts = []
+    parts.append("## Interruption Review\n")
+    parts.append(
+        "The user interrupted Claude mid-response — a strong signal of confusion or misunderstanding. "
+        "Review the interrupted conversation and the user's follow-up to identify rule-worthy learnings.\n"
+    )
+
+    # Load guidance from shared template file
+    guidance = (PROMPTS_DIR / 'conversation-guidance.txt').read_text()
+    parts.append(guidance)
+
+    if modified_files:
+        parts.append("Files modified this session:")
+        for file_path, tool_name in sorted(modified_files):
+            parts.append(f"- {file_path} ({tool_name})")
+        parts.append("")
+
+    parts.append("### Session transcript\n")
+    summary_lines = []
+    for snippet in conversation_snippets:
+        role = snippet['role']
+        content = snippet['content'].replace('\n', ' ')
+        summary_lines.append(f"[{role}]: {content}")
+    parts.append('\n'.join(summary_lines))
+
+    parts.append("")
+    parts.append("### User's follow-up after interruption\n")
+    parts.append(follow_up_prompt)
+
+    return '\n'.join(parts)
+
+
+def spawn_claude_agent(prompt, log_file, project_dir, model='haiku'):
     """Spawn a detached claude -p agent as a background process."""
     try:
         log_fh = open(log_file, 'w')
@@ -322,7 +426,8 @@ def spawn_claude_agent(prompt, log_file, project_dir):
         env['CODEYAM_RULE_AGENT'] = '1'
         subprocess.Popen(
             ['claude', '-p', prompt,
-             '--model', 'haiku',
+             '--model', model,
+             '--no-session-persistence',
              '--output-format', 'stream-json', '--verbose',
              '--allowedTools', 'Read,Edit,Write,Bash,Glob,Grep'],
             cwd=project_dir,
@@ -335,81 +440,69 @@ def spawn_claude_agent(prompt, log_file, project_dir):
         pass  # claude CLI not available, skip silently
 
 
-def main():
-    # Read hook input from stdin
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        return
+def read_marker(marker_file):
+    """
+    Read marker file. Returns (last_line, written_by_stop).
+    Format: "<line_count>" or "<line_count> stop" — the suffix distinguishes
+    whether the Stop hook wrote this marker (normal completion) vs the
+    UserPromptSubmit handler (interruption detection).
+    """
+    if marker_file.exists():
+        try:
+            text = marker_file.read_text().strip()
+            parts = text.split()
+            line_count = int(parts[0])
+            was_stop = len(parts) > 1 and parts[1] == 'stop'
+            return line_count, was_stop
+        except (ValueError, IOError):
+            pass
+    return 0, False
+
+
+def write_marker(marker_file, line_count, source='submit'):
+    """Write marker with source tag. source is 'stop' or 'submit'."""
+    marker_file.write_text(f'{line_count} {source}')
+
+
+def handle_stop(hook_input):
+    """
+    Handle the Stop hook event.
+    Reviews completed turns for stale rules and conversation confusion signals.
+
+    Important: the fast work (transcript parsing, marker update, conversation
+    agent spawn) runs first. The slow `get_stale_rules()` call (~10s) runs last
+    so the hook timeout doesn't kill us before the critical work is done.
+    """
+    settings = load_memory_settings()
 
     session_id = hook_input.get('session_id', '')
     transcript_path = hook_input.get('transcript_path', '')
-    stop_hook_active = hook_input.get('stop_hook_active', False)
-
-    # Prevent infinite loops — stop_hook_active covers same-process recursion,
-    # env var covers spawned subagent sessions triggering the hook on exit
-    if stop_hook_active or os.environ.get('CODEYAM_RULE_AGENT'):
-        return
 
     if not session_id or not transcript_path:
         return
 
-    marker_dir = Path('/tmp/claude-rule-markers')
-    marker_dir.mkdir(exist_ok=True)
+    slug = get_project_slug()
+    marker_dir = Path('/tmp/claude-rule-markers') / slug
+    marker_dir.mkdir(parents=True, exist_ok=True)
     marker_file = marker_dir / f'{session_id}.marker'
 
-    # Read last checked line
-    last_line = 0
-    if marker_file.exists():
-        try:
-            last_line = int(marker_file.read_text().strip())
-        except (ValueError, IOError):
-            last_line = 0
-
-    # Check for stale rules
-    stale_rules = get_stale_rules()
+    last_line, _ = read_marker(marker_file)
 
-    # Get conversation context
+    # Fast: parse transcript for conversation context
     user_turn_count, conversation_snippets, modified_files, current_line_count = get_conversation_context(
         transcript_path, last_line
     )
 
-    # Determine what to include in review
-    has_stale_rules = len(stale_rules) > 0
-    has_conversation = len(conversation_snippets) > 0
-
-    # Only fire if there's something to review
-    if not has_stale_rules and not has_conversation:
-        return
-
-    # Update marker
-    marker_file.write_text(str(current_line_count))
+    # Update marker immediately so UserPromptSubmit knows Stop ran,
+    # even if we get killed during the slow stale rules check below
+    write_marker(marker_file, current_line_count, 'stop')
 
     project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
-
-    # Unique suffix per invocation so each Stop produces a distinct transcript
-    from datetime import datetime
     invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
     invocation_id = f'{session_id}-{invocation_ts}'
 
-    # Spawn independent agent for stale rules review
-    if has_stale_rules:
-        stale_context = build_stale_rules_context(stale_rules)
-        stale_context_file = marker_dir / f'{invocation_id}-stale.context'
-        stale_context_file.write_text(stale_context)
-
-        stale_log_file = marker_dir / f'{invocation_id}-stale.log'
-        stale_notification_file = marker_dir / 'rule-notification-stale.md'
-        stale_prompt = load_prompt_template(
-            'stale-rules-prompt.txt',
-            CONTEXT_FILE=str(stale_context_file),
-            NOTIFICATION_FILE=str(stale_notification_file),
-            PROJECT_DIR=project_dir,
-        )
-        spawn_claude_agent(stale_prompt, stale_log_file, project_dir)
-
-    # Spawn independent agent for conversation review
-    if has_conversation:
+    # Fast: spawn conversation review agent first (if enabled)
+    if settings['conversationReflection'] and len(conversation_snippets) > 0:
         conv_context = build_conversation_context(conversation_snippets, modified_files)
         conv_context_file = marker_dir / f'{invocation_id}-conversation.context'
         conv_context_file.write_text(conv_context)
@@ -422,7 +515,133 @@ def main():
             NOTIFICATION_FILE=str(conv_notification_file),
             PROJECT_DIR=project_dir,
         )
-        spawn_claude_agent(conv_prompt, conv_log_file, project_dir)
+        spawn_claude_agent(conv_prompt, conv_log_file, project_dir, model=settings['promptModel'])
+
+    # Slow (~10s): check for stale rules last — if the hook timeout kills us
+    # here, the conversation agent and marker are already handled
+    if settings['ruleMaintenance']:
+        stale_rules = get_stale_rules()
+
+        if len(stale_rules) > 0:
+            stale_context = build_stale_rules_context(stale_rules)
+            stale_context_file = marker_dir / f'{invocation_id}-stale.context'
+            stale_context_file.write_text(stale_context)
+
+            stale_log_file = marker_dir / f'{invocation_id}-stale.log'
+            stale_notification_file = marker_dir / 'rule-notification-stale.md'
+            stale_prompt = load_prompt_template(
+                'stale-rules-prompt.txt',
+                CONTEXT_FILE=str(stale_context_file),
+                NOTIFICATION_FILE=str(stale_notification_file),
+                PROJECT_DIR=project_dir,
+            )
+            spawn_claude_agent(stale_prompt, stale_log_file, project_dir, model=settings['promptModel'])
+
+
+def handle_user_prompt_submit(hook_input):
+    """
+    Handle the UserPromptSubmit hook event.
+    Detects whether the previous turn was interrupted by checking if the Stop hook's
+    marker file is stale (transcript has lines beyond the marker). If so, spawns a
+    rule-reflection agent focused on the interruption.
+    """
+    settings = load_memory_settings()
+
+    # Interruption detection is part of conversation reflection
+    if not settings['conversationReflection']:
+        return
+
+    session_id = hook_input.get('session_id', '')
+    transcript_path = hook_input.get('transcript_path', '')
+    follow_up_prompt = hook_input.get('prompt', '')
+
+    if not session_id or not transcript_path:
+        return
+
+    slug = get_project_slug()
+    marker_dir = Path('/tmp/claude-rule-markers') / slug
+    marker_dir.mkdir(parents=True, exist_ok=True)
+    marker_file = marker_dir / f'{session_id}.marker'
+
+    last_line, was_stop = read_marker(marker_file)
+
+    # If the Stop hook already ran for the previous turn, this is a normal
+    # completion — not an interruption. The Stop hook tags the marker with
+    # 'stop' when it writes it.
+    if was_stop:
+        return
+
+    # Count current transcript lines
+    try:
+        with open(transcript_path, 'r') as f:
+            current_line_count = sum(1 for _ in f)
+    except IOError:
+        return
+
+    # Quick exit: if nothing new since the marker, definitely no interruption
+    if current_line_count <= last_line:
+        return
+
+    # Verify Claude actually started responding in the unprocessed lines.
+    # Guards against false positives on first prompt (no assistant yet) or
+    # if the user hit Escape before Claude produced any output.
+    if not has_assistant_messages(transcript_path, last_line):
+        return
+
+    # Interruption detected! Build context and spawn agent.
+    _, conversation_snippets, modified_files, _ = get_conversation_context(
+        transcript_path, last_line
+    )
+
+    if not conversation_snippets:
+        return
+
+    # Update marker so we don't re-process these lines
+    write_marker(marker_file, current_line_count, 'submit')
+
+    project_dir = os.environ.get('CLAUDE_PROJECT_DIR', os.getcwd())
+
+    invocation_ts = datetime.now().strftime('%Y%m%d-%H%M%S')
+    invocation_id = f'{session_id}-{invocation_ts}'
+
+    interruption_context = build_interruption_context(
+        conversation_snippets, follow_up_prompt, modified_files
+    )
+    context_file = marker_dir / f'{invocation_id}-interruption.context'
+    context_file.write_text(interruption_context)
+
+    log_file = marker_dir / f'{invocation_id}-interruption.log'
+    notification_file = marker_dir / 'rule-notification-interruption.md'
+    prompt = load_prompt_template(
+        'interruption-prompt.txt',
+        CONTEXT_FILE=str(context_file),
+        NOTIFICATION_FILE=str(notification_file),
+        PROJECT_DIR=project_dir,
+    )
+    spawn_claude_agent(prompt, log_file, project_dir, model=settings['promptModel'])
+
+
+def main():
+    # Read hook input from stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+
+    stop_hook_active = hook_input.get('stop_hook_active', False)
+
+    # Prevent infinite loops — stop_hook_active covers same-process recursion,
+    # env var covers spawned subagent sessions triggering the hook on exit
+    if stop_hook_active or os.environ.get('CODEYAM_RULE_AGENT'):
+        return
+
+    # Detect event type: UserPromptSubmit has a 'prompt' field, Stop does not
+    is_user_prompt = 'prompt' in hook_input
+    if is_user_prompt:
+        handle_user_prompt_submit(hook_input)
+    else:
+        handle_stop(hook_input)
+
 
 if __name__ == '__main__':
     main()

package/codeyam-cli/templates/rules-instructions.md

@@ -4,120 +4,75 @@ Rules provide context-specific guidance when working in files matching their `pa
 
 ## Core Principles
 
-1. **One concept per rule** - Each rule should cover a single topic. If you're documenting two unrelated things, create two rules.
-2. **Paths must match content scope** - A rule about one specific file should have that file in `paths`, not a broad `**/*.ts` pattern.
-3. **Be concise** - Every word costs context. Use bullets and tables.
+1. **One concept per rule** — If you're documenting two unrelated things, create two rules.
+2. **Paths must match content scope** — A rule about one file should have that file in `paths`, not a broad `**/*.ts` pattern.
+3. **Keep rules SHORT** — Most rules should be **1-4 bullets**. Only complex multi-file architectures should exceed ~10 lines.
 
-## When to Create a New Rule
+**Example** — a typical rule:
 
-Create a new rule when:
-
-- You learn something non-obvious about the codebase
-- You make a mistake and want to prevent it in the future
-- The user explains something that isn't clear from the code
-- An existing rule is covering multiple unrelated topics (split it)
-
-## Before Creating: The Confusion Test
-
-Only create rules that document genuinely confusing aspects—not things Claude can figure out by reading code and will likely come up again in future sessions.
-
-**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, non-obvious architectural decisions
-   - Bad: Bug fixes, Limitations (unless the user requests the limitation be noted), What functions do (unless providing a high-level architectural overview)
-
-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
-
-### Examples
-
-**✅ Worth documenting:**
-
-- Where to add new functionality
-- An overview of all files, classes, functions, etc used in a particular part of the repo
-- Debugging strategies for a particular area of the repo
-- "Use `pnpm test` to run tests" (if there is more than one way to run tests and this way is preferred)
-
-**❌ Not worth documenting:**
-
-- "The auth module handles authentication" (obvious from reading code)
-- "This function takes X and returns Y" (Claude can read the signature)
+```markdown
+---
+paths:
+  - 'packages/ai/src/lib/generateMockData.ts'
+---
 
-## Path Specificity
+# Mock Data Generation
 
-The `paths` field controls when the rule is shown. Match the scope of your content:
+- Entry point: `generateMockData()` in `generateMockData.ts`
+- Uses `convertDotNotation` to transform flat schema into nested objects
+- Schema entry ORDER matters — `key[]` must come before `key[].property` or arrays get overwritten
+- Test with exact ordering from database, not just same entries
+```
 
-| Content Scope | Path Pattern            | Example                                                |
-| ------------- | ----------------------- | ------------------------------------------------------ |
-| Single file   | `'path/to/file.ts'`     | Rule about `processExpression.ts` specifically         |
-| Related files | `'path/to/feature*.ts'` | Rule about `generateExecutionFlows*.ts` files          |
-| Directory     | `'path/to/dir/**/*.ts'` | Rule about the queue system in `utils/queue/`          |
-| Cross-cutting | Multiple specific paths | Testing rule with paths to test configs and test files |
+## When to Create a Rule
 
-**Anti-pattern**: Don't use `'**/*.ts'` for a rule about one specific feature.
+Create a rule when you learn something that **reading the code alone wouldn't reveal**:
 
-## File Structure
+- Non-obvious gotchas or behavior that caused real confusion or bugs
+- Architecture, file relationships, or data flows that take time to piece together
+- Debugging strategies for a tricky area of the codebase
+- Preferred commands or workflows when multiple options exist (e.g. "Use `pnpm test` to run tests")
+- User corrections or explanations that aren't captured in the code itself
 
-Rules mirror the source code structure:
+**Skip** rules that restate what the code says — function signatures, type definitions, "this module handles X." Claude can read the code.
 
-| Source Location      | Rule Location                           |
-| -------------------- | --------------------------------------- |
-| `src/api/auth.ts`    | `.claude/rules/src/api/auth.md`         |
-| `src/utils/queue/**` | `.claude/rules/src/utils/queue.md`      |
-| Test configuration   | `.claude/rules/testing/jest-configs.md` |
+## Frontmatter & Paths
 
-## Required Frontmatter
+Every rule needs a `paths` frontmatter field. Be specific to avoid loading rules unnecessarily:
 
 ```yaml
 ---
 paths:
   - 'specific/path/to/file.ts'
   - 'another/specific/path/*.ts'
-timestamp: 2026-01-30T00:00:00Z
 ---
 ```
 
-| Field       | Purpose                                                          |
-| ----------- | ---------------------------------------------------------------- |
-| `paths`     | Glob patterns - be specific to avoid loading rules unnecessarily |
-| `timestamp` | ISO 8601 - update when rule is reviewed                          |
-
-## Content Guidelines
-
-### Be Actionable
-
-- Good: "Run `pnpm test:api` for API tests"
-- Bad: "Make sure to run the appropriate tests"
+| Content Scope | Path Pattern            | Example                                        |
+| ------------- | ----------------------- | ---------------------------------------------- |
+| Single file   | `'path/to/file.ts'`     | Rule about `processExpression.ts` specifically |
+| Related files | `'path/to/feature*.ts'` | Rule about `generateExecutionFlows*.ts` files  |
+| Directory     | `'path/to/dir/**/*.ts'` | Rule about the queue system in `utils/queue/`  |
+| Cross-cutting | Multiple specific paths | Testing rule spanning test configs and tests   |
 
-### Focus on What, Not What Not
+Audit dates live in `.claude/codeyam-rule-state.json` (managed by `codeyam memory touch`). Keep frontmatter limited to `paths`.
 
-- Good: "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`"
-- Bad: "WARNING: Don't store tokens in localStorage!"
+## File Placement
 
-### Keep Rules Short
+Rules must be written to `.claude/rules/`, NOT `.codeyam/rules/`. The instructions file lives in `.codeyam/` but actual rule files go in `.claude/rules/`.
 
-- Target 30-50 lines
-- If a rule exceeds 60 lines, consider splitting it
+Use `codeyam memory rule-path` to compute the correct directory from your frontmatter paths:
 
-## Categories
-
-**architecture** - Design decisions, file relationships, data flow
-
-- "These three files must change together because..."
-- "Data flows from X → Y → Z"
-
-**testing** - Test commands, mock patterns, fixtures
+```
+$ codeyam memory rule-path packages/ai/src/lib/foo.ts packages/ai/src/utils/bar.ts
+{"result":".claude/rules/packages/ai/src/"}
+```
 
-- "Run tests with: `pnpm test path/to/test.ts`"
-- "Must run `pnpm pretest` first because..."
+The command computes the deepest common directory shared by all paths and returns the `.claude/rules/` subdirectory where the rule file should live. Reserve the top level of `.claude/rules/` for rules whose paths genuinely span the entire repo.
 
-**faq** - Gotchas, workarounds, common questions
+## Content Guidelines
 
-- "If you see error X, it means Y"
-- "This looks wrong but is intentional because..."
+- **Be actionable** — "Run `pnpm test:api` for API tests" not "Make sure to run the appropriate tests"
+- **Focus on why, not what** — Gotchas, non-obvious behavior, architectural decisions. The code already shows "what."
+- **Point to specifics** — "Auth tokens are stored in httpOnly cookies via `src/auth/cookies.ts`" beats a vague description.
+- **Be short!** - Context window space is precious! Do not ramble, use bullets, focus on providing clear actionable information.