gh-cadrianmae-claude-marketplace-plugins-ref-tracker/skills/ref-tracker/SKILL.md

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