zhongwei/gh-cadrianmae-claude-marketplace-plugins-ref-tracker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:03:14 +08:00
commit bec17d2416
10 changed files with 1007 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
.claude-plugin/plugin.json Normal file
View File

@@ -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"
]
}

3
README.md Normal file
View File

@@ -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.

93
commands/auto.md Normal file
View File

@@ -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

114
commands/config.md Normal file
View File

@@ -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

211
commands/help.md Normal file
View File

@@ -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.

64
commands/init.md Normal file
View File

@@ -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.

62
commands/update.md Normal file
View File

@@ -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.

69
plugin.lock.json Normal file
View File

@@ -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": []
}
}

226
skills/ref-tracker/SKILL.md Normal file
View File

@@ -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`.

150
skills/ref-tracker/references/examples.md Normal file
View File

@@ -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/
```