Initial commit

2025-11-29 18:03:14 +08:00
commit bec17d2416
10 changed files with 1007 additions and 0 deletions
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "ref-tracker",
+  "description": "Reference and research tracking system for academic work. Tracks WebSearch/WebFetch sources and major prompts to CLAUDE_SOURCES.md and CLAUDE_PROMPTS.md with configurable verbosity.",
+  "version": "1.1.0",
+  "author": {
+    "name": "Mae Capacite",
+    "email": "cadrianmae@users.noreply.github.com"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
--- a/README.md
+++ b/README.md
@@ -0,0 +1,3 @@
+# ref-tracker
+
+Reference and research tracking system for academic work. Tracks WebSearch/WebFetch sources and major prompts to CLAUDE_SOURCES.md and CLAUDE_PROMPTS.md with configurable verbosity.
--- a/commands/auto.md
+++ b/commands/auto.md
@@ -0,0 +1,93 @@
+---
+description: Toggle or set automatic reference tracking on/off
+argument-hint: [on|off]
+allowed-tools: Bash, Write
+---
+
+# auto - Control auto-tracking on/off
+
+Toggle or explicitly set automatic reference tracking state.
+
+## Usage
+
+```bash
+/track:auto          # Toggle between enabled/disabled
+/track:auto on       # Explicitly enable
+/track:auto off      # Explicitly disable
+```
+
+## What it does
+
+1. **Check current status:**
+   - Looks for `./.claude/.ref-autotrack` marker file
+   - If exists → auto-tracking is enabled
+   - If missing → auto-tracking is disabled
+
+2. **Update state:**
+   - **No argument** → toggle current state
+   - **Argument "on"** → enable (create marker if missing)
+   - **Argument "off"** → disable (delete marker if exists)
+
+3. **When enabling:**
+   - Creates `./.claude/.ref-autotrack` with explanatory content:
+     ```
+     # Auto-tracking marker for ref-tracker plugin
+     # Presence = enabled | Absence = disabled
+     # Managed by: /track:auto command
+     # See: /track:help for details
+     ```
+
+4. **When disabling:**
+   - Deletes `./.claude/.ref-autotrack` marker file
+
+5. **Show new status:**
+   - Reports whether auto-tracking is now enabled or disabled
+   - Shows what will be tracked based on current config
+   - Explains how to change verbosity settings
+
+## Output examples
+
+**When enabling:**
+```
+✓ Auto-tracking enabled
+
+The ref-tracker skill will now automatically track:
+- Research sources (WebSearch/WebFetch) → CLAUDE_SOURCES.md
+- Major prompts and outcomes → CLAUDE_PROMPTS.md
+
+Current verbosity settings:
+- Prompts: major (only significant academic/development work)
+- Sources: all (every search operation)
+
+Use /track:config to adjust verbosity settings.
+```
+
+**When disabling:**
+```
+✓ Auto-tracking disabled
+
+The ref-tracker skill will no longer automatically track.
+
+You can still manually track using:
+- /track:update - Scan recent history
+
+To re-enable: /track:auto on
+```
+
+**When toggling:**
+```
+✓ Auto-tracking toggled: OFF → ON
+
+[Shows enabled message above]
+```
+
+## Prerequisites
+
+Run `/track:init` first to create `.claude/` directory structure.
+
+## Notes
+
+- State changes do not affect existing tracked data
+- Manual tracking via `/track:update` works regardless of state
+- Configuration in `.claude/.ref-config` persists across state changes
+- Marker file includes explanatory content for other Claude sessions
--- a/commands/config.md
+++ b/commands/config.md
@@ -0,0 +1,114 @@
+---
+description: View or update tracking verbosity configuration
+argument-hint: [prompts=all|major|off] [sources=all|off]
+allowed-tools: Bash, Read, Write
+---
+
+# config - View or update verbosity settings
+
+View or update tracking verbosity configuration.
+
+## Usage
+
+**View current settings:**
+```bash
+/track:config
+```
+
+**Update settings:**
+```bash
+/track:config prompts=all
+/track:config sources=off
+/track:config prompts=major sources=all
+```
+
+## What it does
+
+1. **With no arguments** - Shows current configuration:
+   - Reads `./.claude/.ref-config`
+   - Displays PROMPTS_VERBOSITY and SOURCES_VERBOSITY
+   - Explains what each setting means
+   - Shows example entries for each level
+
+2. **With arguments** - Updates configuration:
+   - Parses `key=value` pairs
+   - Updates `./.claude/.ref-config`
+   - Validates setting values
+   - Shows new configuration
+
+## Configuration options
+
+### PROMPTS_VERBOSITY
+
+Controls what prompts are tracked to `CLAUDE_PROMPTS.md`:
+
+- **`major`** (default) - Only significant multi-step academic/development work
+  - Example: "Implement authentication system", "Debug complex algorithm"
+  - Best for: Academic research, project documentation
+
+- **`all`** - Track every user request
+  - Example: "What is X?", "Explain Y", "Fix typo in file.txt"
+  - Best for: Complete session logs, detailed auditing
+
+- **`minimal`** - Only explicitly user-requested tracking
+  - Only tracks when user says "track this" or similar
+  - Best for: Selective manual curation
+
+- **`off`** - Disable prompt tracking completely
+  - No entries added to CLAUDE_PROMPTS.md
+  - Best for: Source-only tracking
+
+### SOURCES_VERBOSITY
+
+Controls what sources are tracked to `CLAUDE_SOURCES.md`:
+
+- **`all`** (default) - Track all WebSearch/WebFetch operations
+  - Every search logged automatically
+  - Best for: Complete research audit trail
+
+- **`off`** - Disable source tracking completely
+  - No entries added to CLAUDE_SOURCES.md
+  - Best for: Prompt-only tracking
+
+## Example output
+
+**Viewing config:**
+```
+Current tracking configuration (./.claude/.ref-config):
+
+PROMPTS_VERBOSITY=major
+  Tracks: Only significant multi-step academic/development work
+  Example: "Implement user authentication", "Debug performance issue"
+
+SOURCES_VERBOSITY=all
+  Tracks: All WebSearch/WebFetch operations
+  Example: Every search for documentation, APIs, or concepts
+
+To change settings:
+  /track:config prompts=all
+  /track:config sources=off
+  /track:config prompts=minimal sources=all
+```
+
+**Updating config:**
+```
+✓ Configuration updated
+
+PROMPTS_VERBOSITY: major → all
+SOURCES_VERBOSITY: all (unchanged)
+
+New behavior:
+- Every user request will be tracked to CLAUDE_PROMPTS.md
+- All searches continue to be tracked to CLAUDE_SOURCES.md
+```
+
+## Prerequisites
+
+Run `/track:init` first to create `.claude/.ref-config`.
+
+## Notes
+
+- Changes take effect immediately
+- Existing tracked data is not affected
+- Works regardless of auto-tracking status (on/off)
+- Invalid values are rejected with error message
--- a/commands/help.md
+++ b/commands/help.md
@@ -0,0 +1,211 @@
+---
+description: Display comprehensive help for the ref-tracker system
+disable-model-invocation: true
+---
+
+# help - Reference tracking system help
+
+Comprehensive help for the ref-tracker system.
+
+## Overview
+
+The ref-tracker system automatically tracks research sources and major prompts for academic work and project documentation.
+
+**Two tracking files:**
+- `CLAUDE_SOURCES.md` - Research sources (WebSearch, WebFetch, documentation)
+- `CLAUDE_PROMPTS.md` - Major prompts and outcomes
+
+**Key features:**
+- Automatic tracking when enabled
+- Configurable verbosity
+- Manual retroactive scanning
+- Attribution system ([User] vs [Claude])
+
+## Commands
+
+### `/track:init` - Initialize tracking
+Set up tracking files and configuration for the current project.
+
+Creates:
+- `CLAUDE_SOURCES.md` (empty)
+- `CLAUDE_PROMPTS.md` (with header)
+- `.claude/.ref-autotrack` (enables auto-tracking)
+- `.claude/.ref-config` (verbosity settings)
+
+**Run this first** before using other tracking commands.
+
+---
+
+### `/track:update` - Retroactive scan
+Scan last 20 messages and add missing tracking entries.
+
+Works even when auto-tracking is disabled (manual override).
+Respects verbosity configuration.
+
+**Use when:** You want to capture recent work retroactively.
+
+---
+
+### `/track:auto` - Toggle auto-tracking
+Enable or disable automatic tracking.
+
+**Enabled:** ref-tracker skill automatically logs sources and prompts
+**Disabled:** Manual tracking only via `/track:update`
+
+**Use when:** You want to pause/resume automatic tracking.
+
+---
+
+### `/track:config` - Manage verbosity
+View or update tracking verbosity settings.
+
+**View:** `/track:config`
+**Update:** `/track:config prompts=all sources=off`
+
+**Use when:** You want to control what gets tracked.
+
+---
+
+### `/track:help` - Show this help
+Display comprehensive documentation.
+
+## File Formats
+
+### CLAUDE_SOURCES.md
+
+**Format:** Pure KV file (no headers, one line per entry)
+
+**Pattern:** `[Attribution] Tool("query"): result`
+
+**Examples:**
+```
+[User] WebSearch("PostgreSQL foreign keys tutorial"): https://postgresql.org/docs/current/ddl-constraints.html
+[Claude] WebFetch("https://go.dev/doc/", "embed.FS usage"): Use embed.FS to embed static files at compile time
+[Claude] Grep("CORS middleware", "*.go"): Found in api/routes.go:23-45
+```
+
+**Attribution:**
+- **[User]** - User explicitly requested ("search the web for...")
+- **[Claude]** - Claude autonomously searched for missing information
+
+---
+
+### CLAUDE_PROMPTS.md
+
+**Format:** Two-line entries with blank separator
+
+**Pattern:**
+```
+Prompt: "user request"
+Outcome: what was accomplished
+
+```
+
+**Example:**
+```markdown
+# CLAUDE_PROMPTS.md
+
+This file tracks significant prompts and development decisions.
+
+---
+
+Prompt: "Implement user authentication with JWT"
+Outcome: Created auth middleware, login/logout endpoints, JWT token generation and verification, integrated with database user model
+
+Prompt: "Debug slow database queries"
+Outcome: Added query logging, identified N+1 problem in user posts endpoint, implemented eager loading, reduced query time from 2.3s to 0.15s
+
+```
+
+---
+
+## Verbosity Settings
+
+Located in `./.claude/.ref-config`:
+
+### PROMPTS_VERBOSITY
+
+- **`major`** (default) - Significant multi-step academic/development work
+- **`all`** - Every user request
+- **`minimal`** - Only explicit user requests to track
+- **`off`** - Disable prompt tracking
+
+### SOURCES_VERBOSITY
+
+- **`all`** (default) - Track all WebSearch/WebFetch operations
+- **`off`** - Disable source tracking
+
+## Academic Workflow Example
+
+**1. Setup (once per project):**
+```bash
+/track:init
+```
+
+**2. Work session:**
+- Auto-tracking captures all searches and major work
+- Sources logged to CLAUDE_SOURCES.md
+- Prompts logged to CLAUDE_PROMPTS.md
+
+**3. Review tracked data:**
+- Open CLAUDE_SOURCES.md - see all research sources
+- Open CLAUDE_PROMPTS.md - see work completed
+- Use for citations, bibliography, project documentation
+
+**4. Adjust if needed:**
+```bash
+/track:config prompts=minimal    # Less verbose
+/track:auto                       # Pause tracking
+```
+
+**5. Export for paper:**
+- CLAUDE_SOURCES.md entries become citations
+- CLAUDE_PROMPTS.md becomes methodology section
+- Clear audit trail of research process
+
+## Tips
+
+**For research papers:**
+- Keep `prompts=major` and `sources=all`
+- Review CLAUDE_SOURCES.md for bibliography
+- Use prompts for methodology section
+
+**For development projects:**
+- Use `prompts=all` for complete audit
+- CLAUDE_PROMPTS.md documents decisions
+- Useful for project retrospectives
+
+**For focused work:**
+- Use `/track:auto` to toggle off
+- Manual `/track:update` when needed
+- Reduces noise during exploration
+
+## File Locations
+
+- Tracking files: Project root (`./CLAUDE_SOURCES.md`, `./CLAUDE_PROMPTS.md`)
+- Configuration: `./.claude/.ref-config`
+- Auto-tracking marker: `./.claude/.ref-autotrack`
+
+## Common Issues
+
+**"No tracking files found"**
+→ Run `/track:init` first
+
+**"Too verbose"**
+→ Use `/track:config prompts=minimal`
+
+**"Missing recent searches"**
+→ Run `/track:update` to scan history
+
+**"Want to pause tracking"**
+→ Use `/track:auto` to toggle off
+
+## Related
+
+- **ref-tracker skill** - Automatic tracking when enabled
+- **Global CLAUDE.md** - Documents the system in detail
+- **Project CLAUDE.md** - Can contain project-specific notes
+
+---
+
+For more help, consult plugin README or global ~/.claude/CLAUDE.md documentation.
--- a/commands/init.md
+++ b/commands/init.md
@@ -0,0 +1,64 @@
+---
+description: Initialize reference tracking for the current project
+allowed-tools: Bash, Write
+---
+
+# init - Initialize reference tracking
+
+Initialize reference and research tracking for the current project.
+
+## What it does
+
+1. **Create tracking files:**
+   - Creates `./CLAUDE_SOURCES.md` (empty, pure KV format)
+   - Creates `./CLAUDE_PROMPTS.md` (with header)
+   - If files exist, leaves them unchanged
+
+2. **Create `.claude/` directory structure:**
+   - Creates `./.claude/` directory if missing
+   - Creates `./.claude/.ref-config` with default settings:
+     ```
+     PROMPTS_VERBOSITY=major
+     SOURCES_VERBOSITY=all
+     ```
+   - **Note:** Does NOT create `.ref-autotrack` marker (use `/track:auto` to enable)
+
+3. **Check skill availability:**
+   - Verifies ref-tracker skill is available
+   - Reports status
+
+4. **Show setup summary:**
+   - Files created/existing
+   - Auto-tracking status (disabled by default)
+   - Config location
+   - Next steps
+
+## Default configuration
+
+After init, tracking is **disabled by default**. Configuration file contains these defaults:
+- **Sources**: Track all WebSearch/WebFetch operations (when enabled)
+- **Prompts**: Track major academic/development work only (when enabled)
+
+Use `/track:auto` to enable auto-tracking.
+
+## Next steps
+
+After running `/track:init`:
+- Use `/track:update` to scan recent history
+- Use `/track:config` to adjust verbosity settings
+- Use `/track:auto` to toggle auto-tracking on/off
+- Use `/track:help` for detailed documentation
+
+## Files created
+
+```
+.claude/
+├── .ref-autotrack          # Marker: auto-tracking enabled
+└── .ref-config             # Verbosity settings
+CLAUDE_SOURCES.md           # Research sources (KV format)
+CLAUDE_PROMPTS.md           # Major prompts and outcomes
+```
+
+## Output
+
+Concise status report showing what was created and current configuration.
--- a/commands/update.md
+++ b/commands/update.md
@@ -0,0 +1,62 @@
+---
+description: Scan recent conversation history and add missing tracking entries
+allowed-tools: Read, Write
+---
+
+# update - Retroactive tracking scan
+
+Scan recent conversation history and add missing tracking entries.
+
+## What it does
+
+1. **Review last 20 messages** in this conversation looking for:
+   - WebSearch operations and results
+   - WebFetch operations and results
+   - Grep/Read operations on documentation
+   - Major user requests (features, debugging, refactoring)
+
+2. **Track sources** to `./CLAUDE_SOURCES.md`:
+   - Format: `[User] Tool("query"): result` or `[Claude] Tool("query"): result`
+   - **[User]** if user explicitly requested search ("search the web for...")
+   - **[Claude]** if Claude autonomously searched for missing info
+   - Result is URL or brief concept (1-2 sentences max)
+
+3. **Track prompts** to `./CLAUDE_PROMPTS.md`:
+   - Two-line format:
+     ```
+     Prompt: "user request verbatim or paraphrased"
+     Outcome: what was accomplished in present tense
+
+     ```
+   - Blank line separator after each entry
+   - Only significant work (features, complex tasks, multi-step work)
+   - Respects verbosity setting from `.claude/.ref-config`
+
+4. **Read configuration:**
+   - Checks `./.claude/.ref-config` for verbosity settings
+   - Respects PROMPTS_VERBOSITY (major, all, minimal, off)
+   - Respects SOURCES_VERBOSITY (all, off)
+
+5. **Check prerequisites:**
+   - Verifies tracking files exist
+   - If missing, suggests running `/track:init` first
+
+6. **Show summary:**
+   - Number of sources added
+   - Number of prompts added
+   - Confirmation message
+
+## Usage notes
+
+- Works regardless of auto-tracking status (manual override)
+- Respects verbosity configuration
+- Scans only last 20 messages (not entire conversation)
+- Safe to run multiple times (appends new entries only)
+
+## Prerequisites
+
+Run `/track:init` first to create tracking files and configuration.
+
+## Output
+
+Concise summary showing what was tracked from recent history.
--- a/plugin.lock.json
+++ b/plugin.lock.json
@@ -0,0 +1,69 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:cadrianmae/claude-marketplace:plugins/ref-tracker",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "9643b4bf1a3a90186bfb42b200dfc0187029c230",
+    "treeHash": "8fcf3db39b0751dda977696c2ad2ad234b6ffaf496ec08fef84a4ec7616c15a0",
+    "generatedAt": "2025-11-28T10:14:27.623727Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "ref-tracker",
+    "description": "Reference and research tracking system for academic work. Tracks WebSearch/WebFetch sources and major prompts to CLAUDE_SOURCES.md and CLAUDE_PROMPTS.md with configurable verbosity.",
+    "version": "1.1.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "c8f0023040e41553f7c81fafd3625535474799b5d0ea6257f8035d8f320af360"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "2d7b2510d6443755a48818e03b0c5334ffcf27694f10e0d9ce8bc509e2f3c97e"
+      },
+      {
+        "path": "commands/auto.md",
+        "sha256": "5491e2679970f79b6bd16de5e3f30f58ad041272209dba1bd800bbdebb77a3f5"
+      },
+      {
+        "path": "commands/help.md",
+        "sha256": "be602806af7538ccef93a4d21e2d6ac2beda62d11dbe0485eb6beddeca3825d3"
+      },
+      {
+        "path": "commands/init.md",
+        "sha256": "d976d1c6fe267a2a019397eb7389a7a9b2a3e54e5ec6754452f4ee0db5ddf3cd"
+      },
+      {
+        "path": "commands/config.md",
+        "sha256": "6dd2030fb20ac3d9a927f25ba04946886c34a8846432d6b8e93eba26c7d45bc2"
+      },
+      {
+        "path": "commands/update.md",
+        "sha256": "ad9dc3e02ed34677161fe422c71186385aa564e7f2d276b4c2ea6aff86bc55ae"
+      },
+      {
+        "path": "skills/ref-tracker/SKILL.md",
+        "sha256": "1620f64694a035d89137856908af4c7f44a96b065ddda4df5309117d67b88b7c"
+      },
+      {
+        "path": "skills/ref-tracker/references/examples.md",
+        "sha256": "26edd9bb06cd45cf85d41adb40467c3a6677e3a9db91ff02f5c57d8623183da2"
+      }
+    ],
+    "dirSha256": "8fcf3db39b0751dda977696c2ad2ad234b6ffaf496ec08fef84a4ec7616c15a0"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
--- a/skills/ref-tracker/SKILL.md
+++ b/skills/ref-tracker/SKILL.md
@@ -0,0 +1,226 @@
+---
+name: ref-tracker
+description: Use this skill if /track:init is called OR you notice the project contains tracking files (CLAUDE_SOURCES.md or CLAUDE_PROMPTS.md). Automatically tracks research sources and major prompts when enabled. Checks ./.claude/.ref-autotrack marker file for activation status and ./.claude/.ref-config for verbosity settings. Appends to CLAUDE_SOURCES.md (WebSearch/WebFetch) and CLAUDE_PROMPTS.md (major requests) using [User]/[Claude] attribution.
+allowed-tools: Read, Edit, Write
+---
+
+# Reference Tracker Skill
+
+Automatically track research sources and major prompts for academic and project documentation.
+
+## When to Activate
+
+This skill activates automatically when:
+1. User runs `/track:init` command
+2. You notice `CLAUDE_SOURCES.md` or `CLAUDE_PROMPTS.md` files in the project
+
+Claude autonomously decides when to use this skill based on the description and context.
+
+Once activated, check `./.claude/.ref-autotrack` to determine if auto-tracking is enabled.
+
+## Activation Check
+
+**Before any tracking operation:**
+
+1. Check if `./.claude/.ref-autotrack` exists
+   - If exists → auto-tracking enabled, proceed with tracking
+   - If missing → auto-tracking disabled, skip tracking
+
+2. Read `./.claude/.ref-config` for verbosity settings:
+   ```
+   PROMPTS_VERBOSITY=major|all|minimal|off
+   SOURCES_VERBOSITY=all|off
+   ```
+
+## About the .ref-autotrack File
+
+**Location:** `./.claude/.ref-autotrack`
+
+**Purpose:** Marker file that enables/disables automatic tracking
+
+**Contents:** Contains explanatory comments for other Claude sessions:
+```
+# Auto-tracking marker for ref-tracker plugin
+# Presence = enabled | Absence = disabled
+# Managed by: /track:auto command
+# See: /track:help for details
+```
+
+**Created by:** `/track:auto` or `/track:auto on` command
+
+**Managed by:** `/track:auto` command (toggles on/off, or explicit on/off)
+
+**NOT created by:** `/track:init` - tracking starts disabled
+
+**If you find this file:** The project has reference tracking initialized. Use the ref-tracker skill to automatically log research sources and major prompts according to the verbosity configuration in `./.claude/.ref-config`.
+
+## Tracking Rules
+
+When auto-tracking is enabled (`.ref-autotrack` exists), automatically track:
+
+### CLAUDE_SOURCES.md
+Track **after every**:
+- WebSearch operation
+- WebFetch operation
+- Local documentation search (Grep/Read for docs, API references)
+
+**Respect SOURCES_VERBOSITY:**
+- `all` (default) → Track all operations
+- `off` → Skip source tracking
+
+### CLAUDE_PROMPTS.md
+Track **after completing**:
+- Feature implementations
+- Complex debugging/refactoring
+- Multi-step workflows
+- Non-trivial research questions
+
+**Respect PROMPTS_VERBOSITY:**
+- `major` (default) → Only significant multi-step academic/development work
+- `all` → Every user request
+- `minimal` → Only explicit user requests to track
+- `off` → Skip prompt tracking
+
+## Format Specifications
+
+### CLAUDE_SOURCES.md
+
+**Pattern:** `[Attribution] Tool("Query"): Result`
+
+**Rules:**
+- `[User]` if user explicitly requested search ("search the web for...")
+- `[Claude]` if you autonomously searched for missing information (renamed from [Auto])
+- Tool name in PascalCase (WebSearch, WebFetch, Grep, Read)
+- Query in double quotes (exact query used)
+- Result is URL or brief key concept (1-2 sentences max)
+- Single line per entry, no blank lines between entries
+- **No headers or markdown formatting** (pure KV file)
+
+**Examples:**
+```
+[User] WebSearch("PostgreSQL foreign keys documentation"): https://postgresql.org/docs/current/ddl-constraints.html
+[Claude] WebFetch("https://go.dev/doc/", "embed.FS usage"): Use embed.FS to embed static files at compile time
+[Claude] Grep("CORS middleware", "*.go"): Found in api/routes.go:23-45
+```
+
+### CLAUDE_PROMPTS.md
+
+**Pattern:** Two-line entry with blank separator
+
+**Rules:**
+- Line 1: `Prompt: "<user request verbatim or paraphrased>"`
+- Line 2: `Outcome: <concise result in present tense, 1-2 sentences>`
+- Blank line after each entry
+- Header included if creating new file
+
+**Example:**
+```markdown
+# CLAUDE_PROMPTS.md
+
+This file tracks significant prompts and development decisions.
+
+---
+
+Prompt: "Implement JWT authentication"
+Outcome: Created auth middleware, login/logout endpoints, JWT token generation and verification, integrated with user model
+
+Prompt: "Debug slow database queries"
+Outcome: Added query logging, identified N+1 problem, implemented eager loading, reduced query time from 2.3s to 0.15s
+
+```
+
+## Tracking Workflow
+
+### For CLAUDE_SOURCES.md
+
+1. **After operation completes** (WebSearch/WebFetch/doc search)
+2. **Check activation:** Look for `./.claude/.ref-autotrack`
+3. **Read config:** Check SOURCES_VERBOSITY in `./.claude/.ref-config`
+4. **If enabled and verbosity allows:**
+   - Check if `./CLAUDE_SOURCES.md` exists
+   - If missing: Create empty file
+   - Append entry: `[User|Claude] Tool("query"): result`
+   - **Be silent:** Never announce tracking to user
+
+### For CLAUDE_PROMPTS.md
+
+1. **After completing major request**
+2. **Check activation:** Look for `./.claude/.ref-autotrack`
+3. **Read config:** Check PROMPTS_VERBOSITY in `./.claude/.ref-config`
+4. **If enabled and verbosity allows:**
+   - Check if `./CLAUDE_PROMPTS.md` exists
+   - If missing: Create with header
+   - Append two-line entry + blank line
+   - **Be silent:** Never announce tracking to user
+
+## File Locations
+
+- **Tracking files:** Project root (`./CLAUDE_SOURCES.md`, `./CLAUDE_PROMPTS.md`)
+- **Configuration:** `./.claude/.ref-config`
+- **Activation marker:** `./.claude/.ref-autotrack`
+
+Never create tracking files in subdirectories or `~/.claude/`.
+
+## Error Handling
+
+If Edit fails (file locked, permissions):
+1. Read current contents
+2. Write with contents + new entry appended
+
+## Attribution Decision Guide
+
+**[User]** - User explicitly requested:
+- "Search for X"
+- "Look up Y documentation"
+- "Find examples of Z"
+- "Check the docs for..."
+
+**[Claude]** - You decided to search (renamed from [Auto]):
+- Verifying current syntax/API
+- Checking best practices
+- Looking up error messages
+- Researching to complete a task
+- Missing information to answer question
+
+## Verbosity Handling
+
+### PROMPTS_VERBOSITY=major (default)
+Track only:
+- Multi-step feature implementations
+- Complex debugging sessions
+- Significant refactoring
+- Academic research questions requiring substantial work
+
+Skip:
+- Simple questions ("What is X?")
+- Typo fixes
+- Trivial changes
+
+### PROMPTS_VERBOSITY=all
+Track every user interaction and request.
+
+### PROMPTS_VERBOSITY=minimal
+Track only when user explicitly says "track this" or similar.
+
+### PROMPTS_VERBOSITY=off
+Skip all prompt tracking.
+
+### SOURCES_VERBOSITY=all (default)
+Track every WebSearch/WebFetch operation.
+
+### SOURCES_VERBOSITY=off
+Skip all source tracking.
+
+## Best Practices
+
+1. **Check activation first** - Always look for `./.claude/.ref-autotrack` before tracking
+2. **Read configuration** - Respect verbosity settings in `./.claude/.ref-config`
+3. **Be immediate** - Track right after triggering action completes
+4. **Be silent** - Never announce "Tracking to CLAUDE_SOURCES.md"
+5. **Be accurate** - Use exact queries and URLs
+6. **Be concise** - Keep results brief (1-2 sentences)
+7. **Be selective** - Respect verbosity settings for what to track
+
+## Detailed Examples
+
+For edge cases, multi-line results, concurrent tracking, and comprehensive examples, see `references/examples.md`.
--- a/skills/ref-tracker/references/examples.md
+++ b/skills/ref-tracker/references/examples.md
@@ -0,0 +1,150 @@
+# Documentation Tracker - Detailed Examples
+
+This reference file contains comprehensive examples and edge cases for the doc-tracker skill.
+
+## CLAUDE_SOURCES.md Examples
+
+### Standard Research Entries
+
+```
+[User] WebSearch("PostgreSQL INSERT INTO SELECT documentation official"): https://www.postgresql.org/docs/current/sql-insert.html
+[Auto] WebFetch("https://go.dev/blog/embed", "How to use embed.FS for static files"): embed.FS embeds files at compile time, use fs.Sub to extract subdirectories
+[Auto] Grep("embed.FS", "*.go"): Found implementation in embed.go:14-88 using //go:embed directive
+[User] Read("/usr/share/doc/gin/routing.md", "Route ordering best practices"): Routes matched sequentially, register specific routes before wildcards
+[Auto] WebSearch("Fyne GUI main thread requirements Linux"): https://developer.fyne.io/architecture/threading
+```
+
+### Local Documentation Searches
+
+```
+[Auto] Grep("CORS configuration", "api/*.go"): Found CORS setup in api/routes.go:13-23 with wildcard origin
+[User] Read("go.mod", "Check Gin version"): Using gin-gonic/gin v1.9.1
+[Auto] Glob("*.md"): Found README.md, CLAUDE.md, context.md in project root
+```
+
+### Web Research Patterns
+
+```
+[User] WebSearch("React useEffect cleanup function best practices 2025"): https://react.dev/reference/react/useEffect#cleanup-function
+[Auto] WebFetch("https://pkg.go.dev/embed", "Check FS interface methods"): embed.FS implements fs.FS and fs.ReadDirFS interfaces
+[User] WebSearch("Raspberry Pi 5 7-inch touchscreen resolution specs"): https://www.raspberrypi.com/documentation/accessories/display.html
+```
+
+## CLAUDE_PROMPTS.md Examples
+
+### Simple Feature Implementation
+
+```
+Prompt: "init git"
+Outcome: Initialized repository, created .gitignore excluding build artifacts (ui-web/dist/, app-test-arm64, node_modules/), made initial commit with 28 files
+
+```
+
+### Complex Multi-Step Task
+
+```
+Prompt: "Add dark mode toggle to settings"
+Outcome: Implemented dark mode with context provider, CSS-in-JS theme switching, and persistent localStorage. Updated 8 components to support theming.
+
+```
+
+### Debugging and Optimization
+
+```
+Prompt: "Optimize the database queries causing slow dashboard load"
+Outcome: Added composite indexes on user_id+timestamp columns, implemented query result caching with 5-minute TTL, reduced average load time from 3.2s to 0.4s
+
+```
+
+### Refactoring Work
+
+```
+Prompt: "Refactor the authentication middleware to support OAuth2"
+Outcome: Extracted auth logic into separate middleware package, added OAuth2 provider interface, implemented Google and GitHub providers, maintained backward compatibility with existing JWT auth
+
+```
+
+### Investigation and Research
+
+```
+Prompt: "Figure out why the embedded React app returns 404 for assets"
+Outcome: Discovered fs.Sub() extracts subdirectory but Gin's FileFromFS causes 301 redirects. Fixed by serving with c.Data() and manual MIME type detection using mime.TypeByExtension()
+
+```
+
+## Edge Cases
+
+### Empty Files
+
+When files don't exist yet, create with appropriate starter content:
+
+**CLAUDE_SOURCES.md**: Create empty (no header)
+```
+[Auto] WebSearch("first query"): https://example.com
+```
+
+**CLAUDE_PROMPTS.md**: Create with header
+```markdown
+# CLAUDE_PROMPTS.md
+
+This file tracks significant prompts and development decisions.
+
+---
+
+Prompt: "init git"
+Outcome: Initialized repository with .gitignore
+
+```
+
+### File Already Exists with Content
+
+Use Edit tool to append at the end:
+
+**Before**:
+```
+[User] WebSearch("Go embed tutorial"): https://go.dev/blog/embed
+```
+
+**After Edit**:
+```
+[User] WebSearch("Go embed tutorial"): https://go.dev/blog/embed
+[Auto] WebFetch("https://gin-gonic.com/docs/", "CORS middleware setup"): Use gin.Default() with cors middleware from gin-contrib/cors
+```
+
+### Attribution Decision Guide
+
+**[User]** - Use when:
+- User explicitly asked you to search/fetch
+- User's question requires you to look up information
+- User requested documentation
+
+**[Auto]** - Use when:
+- You decided to verify something
+- You're researching to complete a task
+- You're checking current best practices
+- You're looking up syntax or API details
+
+### Multi-Line Results
+
+Keep results on single line using semicolons for compound information:
+
+```
+[Auto] WebFetch("https://example.com/api", "Extract rate limits"): Rate limits are 100 req/hour for free tier; 1000 req/hour for paid; uses X-RateLimit headers
+```
+
+### Failed Searches
+
+Only track successful searches that yielded useful results. Skip tracking if:
+- Search returned no useful results
+- WebFetch failed with 404/timeout
+- Grep found no matches
+
+### Concurrent Tracking
+
+If performing multiple searches in parallel, track all of them:
+
+```
+[Auto] WebSearch("React 19 new features"): https://react.dev/blog/2024/react-19
+[Auto] WebSearch("Vite 5 migration guide"): https://vitejs.dev/guide/migration
+[Auto] WebSearch("TypeScript 5.4 release notes"): https://devblogs.microsoft.com/typescript/announcing-typescript-5-4/
+```