Cleanup (part one) before release cut.

.claude/commands/audit-docs.md

@@ -2,7 +2,8 @@
 description: "Audit documentation for consistency and accuracy"
 ---
 
-Perform a documentation audit across the codebase. This is an AI-assisted review that produces a report for human judgment.
+Perform a documentation audit across the codebase. This is an AI-assisted 
+review that produces a report for human judgment.
 
 ## Audit Scope
 

.claude/commands/ctx-prompt-audit.md

@@ -0,0 +1,89 @@
+---
+description: "Analyze session logs to identify vague prompts and suggest improvements"
+---
+
+Analyze recent session transcripts to identify prompts that led to unnecessary clarification back-and-forth. This helps the user improve their prompting patterns.
+
+## Your Task
+
+1. **Read recent sessions** from `.context/sessions/` (focus on the 3-5 most recent)
+2. **Identify vague prompts** - user messages that caused you to ask clarifying questions
+3. **Generate a coaching report** with concrete examples and suggestions
+
+## What Makes a Prompt "Vague"
+
+Look for user prompts where Claude's immediate response was to ask clarifying questions rather than take action. Signs include:
+
+- **Missing file context**: "fix the bug" without specifying which file or error
+- **Ambiguous scope**: "optimize it" without what to optimize or success criteria
+- **Undefined targets**: "update the component" when multiple components exist
+- **Missing error details**: "it's not working" without symptoms or expected behavior
+- **Vague action words**: "make it better", "clean this up", "improve the code"
+
+## Important Nuance
+
+Not every short prompt is vague! Consider context:
+- "fix the bug" after discussing a specific error in detail → **NOT vague**
+- "fix the bug" as the first message → **VAGUE**
+- "optimize it" when working on a single function → probably fine
+- "optimize it" in a large codebase with no context → **VAGUE**
+
+## Output Format
+
+Generate a report like this:
+
+```
+## Prompt Audit Report
+
+**Sessions analyzed**: 5
+**User prompts reviewed**: 47
+**Vague prompts found**: 4 (8.5%)
+
+---
+
+### Example 1: Missing File Context
+
+**Your prompt**: "fix the bug"
+
+**What happened**: I had to ask which file and what error you were seeing, adding 2 messages of back-and-forth.
+
+**Better prompt**: "fix the authentication error in src/auth/login.ts where JWT validation fails with 401"
+
+**Cost**: ~2 extra messages, ~30 seconds
+
+---
+
+### Example 2: Undefined Target
+
+**Your prompt**: "optimize the component"
+
+**What happened**: Multiple components exist. I asked which one and what performance issue to address.
+
+**Better prompt**: "optimize UserList in src/components/UserList.tsx to reduce re-renders when parent state updates"
+
+**Cost**: ~3 extra messages, ~1 minute
+
+---
+
+## Patterns to Watch
+
+Based on your sessions, you tend to:
+1. Skip mentioning file paths (3 occurrences)
+2. Use "it" without establishing what "it" refers to (2 occurrences)
+
+## Tips
+
+- Start prompts with the **file path** when discussing specific code
+- Include **error messages** when debugging
+- Specify **success criteria** for optimization tasks
+```
+
+## Guidelines
+
+- Be constructive, not critical - the goal is to help, not shame
+- Show the actual prompt from their session (quoted)
+- Explain what happened (what you had to ask)
+- Provide a concrete better alternative
+- Estimate the "cost" in extra messages/time
+- Look for patterns across multiple examples
+- End with actionable tips based on their specific tendencies

.claude/hooks/prompt-coach.sh

@@ -0,0 +1,145 @@
+#!/bin/bash
+
+#   /    Context:                     https://ctx.ist
+# ,'`./    do you remember?
+# `.,'\
+#   \    Copyright 2026-present Context contributors.
+#                 SPDX-License-Identifier: Apache-2.0
+
+# Prompt coaching hook for Claude Code
+# Detects anti-patterns and suggests better alternatives.
+# Limits suggestions to MAX_SUGGESTIONS per pattern per session.
+#
+# Generated by: ctx init
+#
+# ANTI-PATTERNS DETECTED:
+# - "idiomatic X" → "follow project conventions"
+# - "best practices" → "follow CONVENTIONS.md"
+# - "fix the bug" (vague) → include error message, file, and context
+# - "optimize it" (vague) → specify what to optimize and why
+# - "make it better" (vague) → define "better" with criteria
+# - "update the component" (vague) → specify which component and what changes
+#
+# Output: Warnings to stderr (non-blocking)
+# Exit: Always 0 (never blocks execution)
+
+MAX_SUGGESTIONS=3
+SESSION_FILE="/tmp/ctx-prompt-coach-$$-$(date +%Y%m%d).state"
+
+# Initialize session file if it doesn't exist
+if [ ! -f "$SESSION_FILE" ]; then
+    cat > "$SESSION_FILE" << 'EOF'
+idiomatic=0
+bestpractices=0
+fixbug=0
+optimize=0
+makebetter=0
+update=0
+EOF
+fi
+
+# Read hook input from stdin (JSON)
+HOOK_INPUT=$(cat)
+
+# Extract the prompt text
+PROMPT=$(echo "$HOOK_INPUT" | jq -r '.prompt // empty')
+
+# If no prompt, allow
+if [ -z "$PROMPT" ]; then
+    exit 0
+fi
+
+# Helper: get count for a pattern
+get_count() {
+    grep "^$1=" "$SESSION_FILE" 2>/dev/null | cut -d= -f2 || echo "0"
+}
+
+# Helper: increment count for a pattern
+increment_count() {
+    local pattern="$1"
+    local count=$(get_count "$pattern")
+    local new_count=$((count + 1))
+    if grep -q "^$pattern=" "$SESSION_FILE" 2>/dev/null; then
+        sed -i "s/^$pattern=.*/$pattern=$new_count/" "$SESSION_FILE"
+    else
+        echo "$pattern=$new_count" >> "$SESSION_FILE"
+    fi
+}
+
+# Helper: output a coaching tip (only if under limit)
+suggest() {
+    local pattern="$1"
+    local tip="$2"
+    local example="$3"
+    local count=$(get_count "$pattern")
+
+    if [ "$count" -lt "$MAX_SUGGESTIONS" ]; then
+        echo "" >&2
+        echo "┌─ Prompt Tip ─────────────────────────────────────" >&2
+        echo "│ $tip" >&2
+        if [ -n "$example" ]; then
+            echo "│" >&2
+            echo "│ Example: $example" >&2
+        fi
+        echo "└──────────────────────────────────────────────────" >&2
+        echo "" >&2
+        increment_count "$pattern"
+    fi
+}
+
+# Calculate prompt length (for detecting short vague prompts)
+PROMPT_LEN=${#PROMPT}
+
+# Check for "idiomatic X" pattern (case-insensitive)
+if echo "$PROMPT" | grep -qiE 'idiomatic (go|python|rust|javascript|typescript|java|c\+\+|ruby)'; then
+    suggest "idiomatic" \
+        "Instead of 'idiomatic X', try 'follow project conventions'" \
+        "'follow CONVENTIONS.md patterns for error handling'"
+fi
+
+# Check for "best practices" pattern (case-insensitive)
+if echo "$PROMPT" | grep -qiE '\bbest practices?\b'; then
+    suggest "bestpractices" \
+        "Instead of 'best practices', try 'follow CONVENTIONS.md'" \
+        "'follow the error handling pattern from CONVENTIONS.md'"
+fi
+
+# Check for vague "fix the bug" / "fix this bug" patterns
+# Only trigger if the prompt is short and lacks specifics
+if [ "$PROMPT_LEN" -lt 50 ] && echo "$PROMPT" | grep -qiE '\bfix (the|this|that|a) (bug|issue|error|problem)\b'; then
+    # Check if prompt lacks context (no file path, no error message, no line number)
+    if ! echo "$PROMPT" | grep -qE '(\.[a-z]{2,4}|line [0-9]|:[0-9]+|error:|Error:|failed|Failed)'; then
+        suggest "fixbug" \
+            "Add context: which file? what error? what's broken?" \
+            "'fix the JWT validation error in src/auth/login.ts returning 401'"
+    fi
+fi
+
+# Check for vague "optimize" patterns
+if [ "$PROMPT_LEN" -lt 40 ] && echo "$PROMPT" | grep -qiE '\b(optimize|optimise) (it|this|that)\b'; then
+    suggest "optimize" \
+        "Specify what to optimize and what metric matters" \
+        "'optimize UserList to reduce re-renders when parent state updates'"
+fi
+
+# Check for vague "make it better" patterns
+if echo "$PROMPT" | grep -qiE '\bmake (it|this|that) (better|nicer|cleaner|good)\b'; then
+    if [ "$PROMPT_LEN" -lt 50 ]; then
+        suggest "makebetter" \
+            "Define 'better' - readability? performance? maintainability?" \
+            "'refactor to be more readable by extracting validation logic'"
+    fi
+fi
+
+# Check for vague "update the component/function/file" patterns
+if [ "$PROMPT_LEN" -lt 50 ] && echo "$PROMPT" | grep -qiE '\bupdate (the|this|that|a) (component|function|file|module|class)\b'; then
+    # Check if prompt lacks specifics
+    if ! echo "$PROMPT" | grep -qE '(\.[a-z]{2,4}|src/|lib/|internal/)'; then
+        suggest "update" \
+            "Specify which component and what changes" \
+            "'update Button in src/components/Button.tsx to use new color tokens'"
+    fi
+fi
+
+# Always allow the prompt to proceed
+exit 0

.context/AGENT_PLAYBOOK.md

@@ -366,9 +366,23 @@ Before writing or modifying CLI code (`internal/cli/**/*.go`):
 
 1. **Read CONVENTIONS.md** — Load established patterns into context
 2. **Check similar commands** — How do existing commands in the same package handle output?
-3. **Use cmd methods for output** — `cmd.Printf`, `cmd.Println`, not `fmt.Printf`, `fmt.Println`
+3. **Use cmd methods for I/O** — Never use `fmt` for output in CLI code
 4. **Follow docstring format** — See Go Documentation Standard below
 
+**cmd methods to use:**
+
+| Instead of        | Use                | Purpose                              |
+|-------------------|--------------------|--------------------------------------|
+| `fmt.Printf`      | `cmd.Printf`       | Formatted stdout                     |
+| `fmt.Println`     | `cmd.Println`      | Line to stdout                       |
+| `fmt.Print`       | `cmd.Print`        | Raw stdout                           |
+| `fmt.Fprintf(os.Stderr, ...)` | `cmd.PrintErrf` | Formatted stderr          |
+| `fmt.Fprintln(os.Stderr, ...)` | `cmd.PrintErrln` | Line to stderr           |
+| `fmt.Sprintf`     | `fmt.Sprintf`      | String formatting (OK to keep)       |
+| `fmt.Errorf`      | `fmt.Errorf`       | Error creation (OK to keep)          |
+
+**Why**: cmd methods write to testable buffers; fmt writes to real stdout/stderr.
+
 **Quick pattern check:**
 ```bash
 # See how other commands do output

.context/LEARNINGS.md

@@ -3,6 +3,7 @@
 <!-- INDEX:START -->
 | Date | Learning |
 |------|--------|
+| 2026-01-30 | Say 'project conventions' not 'idiomatic X' |
 | 2026-01-29 | Documentation audits require verification against actual standards |
 | 2026-01-28 | Required flags now enforced for learnings |
 | 2026-01-28 | Claude Code Hooks Receive JSON via Stdin |
@@ -40,6 +41,16 @@
 
 ---
 
+## [2026-01-30-120009] Say 'project conventions' not 'idiomatic X'
+
+**Context**: When asking Claude to follow documentation style, saying 'idiomatic Go' triggered training priors (stdlib conventions) instead of project-specific standards.
+
+**Lesson**: Use 'follow project conventions' or 'check AGENT_PLAYBOOK' rather than 'idiomatic [language]' to ensure Claude looks at project files first.
+
+**Application**: In prompts requesting style alignment, reference project files explicitly rather than language-wide conventions.
+
+---
+
 ## [2026-01-29-164322] Documentation audits require verification against actual standards
 
 **Context**: Agent claimed 'no Go docstring issues found' but manual inspection revealed many functions missing Parameters/Returns sections. The agent only checked if comments existed, not if they followed the standard format.