decision-tracker

# State Tracker - Git-Powered Session & State Awareness

**Purpose:** Provide Claude with complete awareness of project state using git as source of truth, preventing stale mental models and redundant work.

**What This System Tracks:**

1. **In-Session State** (real-time)
   - File modifications (git diff)
   - Uncommitted changes (git status)
   - Current branch and commit

2. **Between-Session Context** (differential)
   - What happened since last session
   - Commits made (by you or others)
   - Files changed externally
   - Branch switches

3. **Historical Decisions** (queryable)
   - Past research findings
   - Architectural decisions
   - Implementation plans

**Token Overhead:**
- In-session checks: ~200-500 tokens (only when files change)
- Between-session context: ~1-2K tokens (differential only)
- Decision queries: ~2-5K tokens (selective loading)
- **Total:** <5K tokens vs 50K+ full reload

---

## When This Skill Activates

**Auto-activates when you detect:**

**State Queries:**
- "what changed since last session?"
- "show me what happened"
- "what's the current state?"
- "what files did we work on?"
- "what commits were made?"

**Before File Operations:**
- PreToolUse hook activates automatically
- Checks if file changed externally
- Warns before Edit/Write if file is stale

**Before Duplicating Work:**
- "research X" → Check if already researched
- "decide on Y" → Check if already decided
- "plan Z" → Check if plan exists

---

## Your Workflow When This Skill Activates

### If User Asks "What Changed?"

**Run the manual status script:**
```bash
./scripts/session-status.sh
```

**This shows:**
- Git activity since last session
- Current working directory status
- Decision tracking summary

**Token cost:** ~500 tokens for complete state summary

### If You're About to Edit a File

**Trust the PreToolUse hook:**
- It automatically checks git status
- If file changed externally, you'll see warning
- Follow the recommendation: Re-read before editing

**Do