process-improvement-protocol

What this skill does

# Process Improvement Protocol

## Overview

Systematic intervention system that detects frustration, analyzes root causes, implements fixes, and tracks effectiveness over time.

**Core principle:** Data-driven behavioral change. Success = days between frustration incidents increasing over time.

**Announce at start:** "🛟 Process Improvement Protocol initiated! Saving my context for later."

## Phase 0: Plugin Path Discovery (ALWAYS RUN FIRST)

**CRITICAL**: Before any file operations, discover where this plugin is installed.

The plugin must work regardless of installation method:
- Local testing: `/path/to/process-improvement/`
- Marketplace install: `~/.claude/plugins/marketplaces/process-improvement/`
- Legacy location: `~/.claude/process-improvement/` (deprecated)

**Path Discovery Strategy**:

```bash
# Determine plugin root directory
# Priority: CLAUDE_PLUGIN_ROOT env var > marketplace location > current directory
if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then
  PLUGIN_ROOT="$CLAUDE_PLUGIN_ROOT"
elif [ -d ~/.claude/plugins/marketplaces/process-improvement ]; then
  PLUGIN_ROOT=~/.claude/plugins/marketplaces/process-improvement
elif [ -d ~/.claude/process-improvement ]; then
  # Legacy fallback
  PLUGIN_ROOT=~/.claude/process-improvement
else
  # Assume local development
  PLUGIN_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
fi

# Export data directory for all file operations
export PLUGIN_DATA="$PLUGIN_ROOT/data"

# Verify data directory exists, create if missing
mkdir -p "$PLUGIN_DATA"/{sessions,deferred-incidents,fixes-registry}

# Verify required files exist, create if missing
touch "$PLUGIN_DATA/incidents.jsonl"
[ -f "$PLUGIN_DATA/days-without-incident.json" ] || echo '{"last_incident":null,"days_since_last":0,"longest_streak":0}' > "$PLUGIN_DATA/days-without-incident.json"
```

**Usage**: All file operations in this skill use `${PLUGIN_DATA}/filename` instead of absolute paths.

## Trigger Conditions

### Primary Trigger
User types `/improve [timeframe]` command

**Time frame parameter** (optional):
- `week` - Analyze last 7 days
- `month` - Analyze last 30 days (default)
- `year` - Analyze last 365 days
- `all` - Analyze entire history

If no time frame specified, default to `month`.

**Parse time frame:**
```bash
# Extract from command arguments
timeframe="${1:-month}"  # Default to month if not specified

case "$timeframe" in
  week)  days=7 ;;
  month) days=30 ;;
  year)  days=365 ;;
  all)   days=99999 ;;  # Effectively all time
  *)     days=30 ;;     # Default to month for invalid input
esac
```

### Auto-Detection (Frustration Phrase Library)

Check user message for ANY of these phrases:
- "Stop"
- "I keep asking"
- "Did you actually"
- "You didn't test"
- "You didn't..."
- "I didn't ask for..."
- "How many times"
- "Again?"
- "Still not working"

**If detected**, offer choice:
```
🛟 I detected a potential frustration pattern. Would you like to:
1. Run Process Improvement Protocol now
2. Defer this and continue working (I'll save the context)
```

If user chooses option 2 (defer):
- Save context to `${PLUGIN_DATA}/deferred-incidents/YYYY-MM-DD-HHMMSS.json`
- Include: timestamp, trigger phrase, last user message, current todos, files being edited
- Continue with original work
- Skill will check for deferred incidents on next /improve run

## Phase 1: Context Preservation

### 1. Acknowledge

Display which time frame is being analyzed:

```
🛟 Process Improvement Protocol initiated! Saving my context for later.

Analyzing: Last [7 days|30 days|365 days|all time] of conversations
```

Replace bracketed text with actual time frame based on parameter.

### 2. Save Resume State

Create `${PLUGIN_DATA}/sessions/YYYY-MM-DD-HHMMSS-resume.json`:

```json
{
  "timestamp": "2025-11-21T17:45:00Z",
  "current_todos": [...],  // from TodoWrite
  "last_user_message": "...",
  "working_on": "...",  // brief summary
  "files_being_edited": [...]
}
```

### 3. Display Streak

Read `${PLUGIN_DATA}/days-without-incident.json` and calculate days since last incident:

```
Days since last frustration incident: X

[If X < 7]: Definitely still learning here. Let's get to it!
[If X >= 7]: Oof! We had a good streak going. Let's get back on track!
```

## Phase 2: Quick Context Analysis

### 1. Analyze Current Conversation

Check for obvious patterns:
- Testing skipped? (claims of "complete" or "working" without evidence)
- Review skipped? (spec/plan written without review agent)
- Rationalization detected? ("should work", "logic is correct")
- Hallucination? (claiming features exist that don't)
- Repeated request? (user asked for same thing 2+ times)

### 2. Check Deferred Incidents

Read `${PLUGIN_DATA}/deferred-incidents/*.json`

If any found:
```
Current issue: [describe current frustration]

I also found X deferred incidents from earlier sessions that may be related:
- [incident 1 summary]
- [incident 2 summary]

Analyzing all together.
```

### 3. Load Historical Context

Read files within the specified time frame:
- `${PLUGIN_DATA}/incidents.jsonl` (filter by timestamp and `days` parameter)
- `${PLUGIN_DATA}/successful-fixes.md` (what worked before)
- `${PLUGIN_DATA}/patterns-detected.md` (known failure modes)
- `${PLUGIN_DATA}/fixes-registry/*.md` (filter by file modification date using `days` parameter)

**Filter incidents.jsonl by time frame:**
```bash
# Only load incidents within the specified time frame
jq -c --arg cutoff_days "$days" \
  'select((now - (.timestamp | fromdate)) / 86400 <= ($cutoff_days | tonumber))' \
  "${PLUGIN_DATA}/incidents.jsonl"
```

Check for similar past incidents (within time frame) and their solutions.

## Phase 3: Deep Investigation

### Skill-Based Analysis

Using available context, perform analysis:

1. **Pattern matching**: Does this match a known failure mode from patterns-detected.md?
2. **Historical check**: Has this happened before? What fixed it then? Did that fix last?
3. **Regression check**: Were fixes previously applied but now broken/removed?
4. **Root cause**: Why did this actually happen? (Be specific, not generic)

### Generate Solution Options

Create 2-3 solution options with:
- **What**: Specific implementation (file edits, config changes, skill creation)
- **Why it should work**: Evidence-based reasoning (similar past fixes, proven patterns)
- **Drawbacks**: Honest assessment
- **Expected effectiveness**: Based on historical data if available

### Recommend Best Option

Select the most likely to solve this based on evidence, with reasoning.

### Optional: Spawn Agent for Complex Cases

If analysis requires:
- Deep investigation across many historical conversations
- Research (WebSearch for solutions)
- Comparing multiple historical patterns

Spawn general-purpose agent with full context package.

## Phase 4: Present & Implement

### 1. Present Findings

```
## Root Cause Analysis
[What happened + why + is this a pattern?]

## Historical Context
[Has this happened before? What fixed it then? Did that fix last?]

## Solution Options

### Option A: [Name]
**What**: [Specific implementation]
**Why it should work**: [Evidence-based reasoning]
**Drawbacks**: [Honest assessment]
**Expected effectiveness**: [Based on historical data]

### Option B: [Name]
...

## Recommendation
**Recommended**: Option [X]
**Reasoning**: [Why this one, with evidence]
**Success criteria**: [How we'll know if it worked]
```

### 2. User Selects or Approves

User chooses option (or approves recommendation).

### 3. Implement Fix Immediately

Apply the selected fix:
- Update configuration files (e.g., `actually_works_plus_superpowers.md`)
- Create new skill if needed (in `~/.claude/skills/user/`)
- Add enforcement hook if needed (in `~/.claude/hooks/`)
- Create entry in `${PLUGIN_DATA}/fixes-registry/YYYY-MM-DD-fix-name.md` with:
  - Date implemented
  - Problem it solves
  - What was changed (file paths)
  - Expected impact
  - How to verify it's working

### 4. Log to incidents.jsonl

Append new line to `${PLUGIN_DATA