gh-shakes-tzd-contextune/skills/decision-tracker/SKILL.md

name, description, keywords, auto_invoke

name	description	keywords	auto_invoke
decision-tracker	Git-powered state awareness - track file changes, session context, decisions, and work history. Query what happened in previous sessions and during current session. Auto-activates for state queries and before duplicating work.	what changed what happened previous session last session what did we what was show changes show status current state file changes git status session status why did we what was the decision should we use which approach research before we start have we already did we already	true

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:

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

Don't manually check git status - hook does it automatically!

If Starting Research or Planning

Query decisions.yaml first:

# Before research
uv run scripts/decision-query.py --topic "{topic}" --type research

# Before planning
uv run scripts/decision-query.py --topic "{topic}" --type plans

# Before deciding
uv run scripts/decision-query.py --topic "{topic}" --type decisions

If found: Load existing context (2-5K tokens) If not found: Proceed with new work

###If User Made External Changes

User says: "I made some changes" or "I committed something"

Your response:

# Check what changed
./scripts/session-status.sh

Then summarize what you found for the user.

---

The Complete State Awareness System

Component 1: In-Session State Sync (Automatic)

PreToolUse Hook checks git state before file operations:

# Happens automatically when you try to Edit/Write
PreToolUse: Intercepts tool call
  → Runs: git status <file>
  → If changed: "⚠️ File modified externally - Re-read before editing"
  → Always continues (non-blocking)

What you see:

⚠️ File State Change Detected

File: hooks/user_prompt_submit.py
Status: MODIFIED
Git Says: File has uncommitted changes

Recommendation:
- Re-read file to see current state
- Use Read tool before Edit

Continuing with your Edit operation...

Token cost: ~300 tokens (only when file actually changed)

Component 2: Between-Session Context (Automatic)

SessionStart Hook injects git context automatically:

Session starts:
  → SessionStart reads .contextune/last_session.yaml
  → Runs: git log <last_commit>..HEAD
  → Runs: git diff --stat <last_commit>..HEAD
  → Generates differential summary
  → Injects as additionalContext

What you see at session start:

📋 Git Context Since Last Session (2 hours ago)

**Git Activity:**
- 5 new commits
- 8 files changed (+250, -30)
- Branch: master

**Recent Commits:**
  a95478f feat: add three-layer git enforcement
  1e1a15a feat: add plan extraction support
  ... and 3 more

**Files Changed:**
  Added (2):
    - commands/ctx-git-commit.md
    - hooks/pre_tool_use_git_advisor.py
  Modified (6):
    - hooks/user_prompt_submit.py
    - hooks/hooks.json
    ... and 4 more

**Current Status:** 2 uncommitted changes

Ready to continue work!

Token cost: ~1-2K tokens (only NEW information since last session)

Component 3: Manual Status Check

When user asks "what changed?" or you need to check state:

# Run the status script
./scripts/session-status.sh

Shows:

• Current git state (branch, commit, uncommitted files)
• Changes since last session (commits, files, diff stats)
• Decision tracking status
• Full git summary

When to use:

• User asks "what's the current state?"
• You need to verify what happened
• Before major operations
• After user says "I made some changes"

Token cost: ~500 tokens

---

Complete Workflow Examples

Example 1: File Modified Externally (In-Session)

10:00 - You: Read hooks/user_prompt_submit.py
        [File contents loaded into context]

10:15 - User edits file in VS Code
        [Makes changes, saves]

10:20 - You: Edit hooks/user_prompt_submit.py

        PreToolUse Hook: ⚠️ File State Change Detected
          File: hooks/user_prompt_submit.py
          Status: MODIFIED
          Recommendation: Re-read before editing

You: "I see the file was modified externally. Let me re-read it first."
     [Read hooks/user_prompt_submit.py]
     [Now have current state]
     [Proceed with Edit]

Token saved: Prevented edit conflict + re-work

Example 2: New Session After External Changes

Session 1 ends:
  SessionEnd: Records metadata to .contextune/last_session.yaml
    - session_id, timestamp, last_commit, branch, files_worked_on

[User works outside Claude]
  - Commits via terminal: git commit -m "quick fix"
  - Edits 3 files manually
  - Switches to develop branch

Session 2 starts:
  SessionStart: Loads .contextune/last_session.yaml
    → git log <last_commit>..HEAD
    → git diff --stat <last_commit>..HEAD
    → Generates summary

Claude sees:
  📋 Git Context Since Last Session (3 hours ago)

  **Git Activity:**
  - 1 new commit: "quick fix"
  - 3 files changed
  - Branch: master → develop (switched)

  **Current Status:** Clean ✅

Claude: "I see you made a commit and switched to develop branch.
        The 3 files that changed are now in my context. Ready to continue!"

Token cost: ~1.5K (vs 50K+ full reload)

---

The Decision Tracking System

Structure

decisions.yaml - YAML database with 3 types of entries:

research:
  entries:
    - id: "res-001-authentication-libraries"
      topic: "Authentication libraries for Node.js"
      findings: "Compared Passport.js, Auth0, NextAuth..."
      recommendation: "Use NextAuth for React apps"
      created_at: "2025-10-28"
      expires_at: "2026-04-28"  # 6 months
      tags: [authentication, libraries, nodejs]

plans:
  entries:
    - id: "plan-001-jwt-implementation"
      title: "JWT Authentication Implementation"
      summary: "5 tasks: AuthService, middleware, tokens..."
      status: "completed"
      created_at: "2025-10-28"
      tags: [authentication, implementation]

decisions:
  entries:
    - id: "dec-001-dry-strategy"
      title: "Unified DRY Strategy"
      status: "accepted"
      context: "CHANGELOG grows unbounded..."
      alternatives_considered: [...]
      decision: "Use scripts for git workflows"
      consequences: {positive: [...], negative: [...]}
      tags: [architecture, cost-optimization]

CLI Tools

Query existing context:

# Check if we already researched a topic
uv run scripts/decision-query.py --topic "authentication" --type research

# Check for existing decisions
uv run scripts/decision-query.py --topic "DRY" --type decisions

# Check for active plans
uv run scripts/decision-query.py --type plans --status active

# Query by tags
uv run scripts/decision-query.py --tags architecture cost-optimization

Output format:

# Filtered entries matching your query
# Load only relevant context (2-5K tokens vs 150K full CHANGELOG)

---

Your Workflow (IMPORTANT!)

Before Starting Research

ALWAYS query first:

# Check if we already researched this topic
uv run scripts/decision-query.py --topic "{research_topic}" --type research

If found:

• Load the existing findings (2K tokens)
• Check expiration date (research expires after 6 months)
• If recent → Use existing research
• If expired → Research again, update entry

If NOT found:

• Proceed with research
• SessionEnd hook will auto-extract to decisions.yaml

Savings:

• Skip $0.07 redundant research
• Load 2K tokens instead of researching again

Before Making Decisions

ALWAYS query first:

# Check for existing decisions on this topic
uv run scripts/decision-query.py --topic "{decision_topic}" --type decisions

If found:

• Load the decision context
• Check status (accepted, rejected, superseded)
• If accepted → Follow existing decision
• If superseded → Find superseding decision
• If rejected → Understand why, avoid same approach

If NOT found:

• Proceed with decision-making
• SessionEnd hook will auto-extract to decisions.yaml

Savings:

• Skip 15-30 min re-discussion
• Consistent decisions across sessions

Before Planning

ALWAYS query first:

# Check for existing plans on this topic
uv run scripts/decision-query.py --topic "{feature_name}" --type plans

If found:

• Load existing plan (2-3K tokens)
• Check status (active, completed, archived)
• If active → Continue existing plan
• If completed → Reference, don't recreate

If NOT found:

• Create new plan with /ctx:plan
• Plan will be auto-extracted to decisions.yaml

---

Auto-Population

decision-sync.py scans conversation history and auto-populates decisions.yaml:

# Scan all conversations for decisions (run once)
uv run scripts/decision-sync.py

# Result: Populates decisions.yaml with historical context

How it works:

1. Scans ~/.claude/projects/*/conversation/ for transcripts
2. Uses extraction patterns to detect decisions/research/plans
3. Extracts and appends to decisions.yaml
4. Deduplicates (won't add same decision twice)

Already populated: Check current state:

# See what's already in decisions.yaml
uv run scripts/decision-query.py --all

---

Token Efficiency

Context Loading Comparison

Old approach (CHANGELOG.md):

Import entire CHANGELOG: 150K tokens
Problem: Loads everything, most irrelevant
Cost: High context usage

New approach (decisions.yaml with queries):

Query specific topic: 2-5K tokens (83-97% reduction!)
Example: decision-query.py --topic "authentication"
Loads: Only relevant 2-3 entries

Selective Loading Strategy

Scenario 1: Starting authentication work

# Query for authentication context
uv run scripts/decision-query.py --topic "authentication"

# Loads:
- Research: Authentication libraries (if exists)
- Decisions: Auth approach decisions (if exists)
- Plans: Auth implementation plans (if exists)

# Total: ~3K tokens vs 150K full CHANGELOG

Scenario 2: User asks "why did we choose X?"

# Query for specific decision
uv run scripts/decision-query.py --topic "DRY strategy"

# Loads: Single decision with full context
# Total: ~1K tokens

---

Integration with Hooks

SessionEnd Hook (Automatic)

session_end_extractor.py already extracts to decisions.yaml:

• Detects decisions in conversation (## Decision: pattern)
• Extracts structured data
• Appends to decisions.yaml automatically

You don't need to do anything - it happens automatically at session end!

What You Should Do

During conversation:

1. Output decisions in extraction-optimized format (see output style)
2. SessionEnd hook extracts automatically
3. Next session, query for context if needed

---

Examples

Example 1: Before Researching Libraries

User: "Research best state management libraries for React"

You: Let me check if we already researched this.

[Run decision-query.py --topic "state management" --type research]

Result: Found existing research from 2 months ago
  - Compared: Redux, Zustand, Jotai, Valtio
  - Recommendation: Zustand for simple apps, Jotai for complex
  - Tags: [react, state-management, libraries]

You: We already researched this! Here's what we found:
     [Load 2K tokens vs spending $0.07 to research again]

Example 2: Before Making Architecture Decision

User: "Should we use microservices or monolith?"

You: Let me check if we already decided on architecture approach.

[Run decision-query.py --topic "architecture" --type decisions]

Result: Found decision "dec-002-monolith-first"
  - Decision: Start with modular monolith
  - Rationale: Team size <5, single deployment simpler
  - Status: accepted
  - Date: 2025-09-15

You: We already decided this! Here's the context:
     [Load 1K tokens vs re-discussing for 30 minutes]

Example 3: Before Planning Feature

User: "Plan implementation for user dashboard"

You: Let me check for existing plans.

[Run decision-query.py --topic "dashboard" --type plans]

Result: Found plan "plan-005-dashboard-v1"
  - Status: completed
  - Summary: "5 tasks implemented, merged to main"
  - Created: 2025-10-01

You: We already implemented this! Let me load the existing plan.
     [Load 3K tokens, reference existing work]

---

Lifecycle Management

Research entries expire after 6 months:

• Rationale: Technology evolves, best practices change
• Old research becomes stale (2024 → 2025 practices differ)
• Expired entries moved to archives

Plans archive 90 days after completion:

• Rationale: Useful during implementation, less useful after
• Completed plans moved to docs/archive/

Decisions never auto-expire:

• Unless explicitly superseded by new decision
• Architectural decisions stay relevant

Check lifecycle status:

# See active vs expired entries
uv run scripts/decision-query.py --show-expired

---

Cost Impact

Annual savings (assuming 50 research sessions):

Old: 50 × $0.07 = $3.50 in redundant research
New: Query first (free), research only if needed
Savings: ~$3.00/year + avoid 25 hours of redundant work

Token savings per query:

Load full CHANGELOG: 150K tokens
Load specific query: 2-5K tokens
Savings: 97% reduction per lookup

---

Quick Reference

Check before researching:

uv run scripts/decision-query.py --topic "{topic}" --type research

Check before deciding:

uv run scripts/decision-query.py --topic "{topic}" --type decisions

Check before planning:

uv run scripts/decision-query.py --topic "{topic}" --type plans

See all active context:

uv run scripts/decision-query.py --all

---

Integration Points

1. Before /ctx:research - Query for existing research first
2. Before /ctx:plan - Query for existing plans first
3. Before /ctx:design - Query for existing decisions first
4. When user asks "why" - Query for decision rationale
5. At SessionEnd - Automatic extraction (no action needed)

---

Summary

Key principle: Query before doing work that might already be done.

Benefits:

• 83-97% token reduction for context loading
• Avoid $0.07 redundant research
• Consistent decisions across sessions
• Queryable, structured context
• Auto-populated from conversation history

Remember: decisions.yaml is plugin-local, works for all users who install Contextune!