zhongwei/gh-gserafini-process-improvement
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:29:33 +08:00
commit 70c0fb03a9
5 changed files with 523 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": "process-improvement",
"description": "Systematic intervention system for detecting frustration, analyzing root causes, implementing fixes, and tracking effectiveness over time",
"version": "1.0.1",
"author": {
"name": "Greg Serafini",
"email": "greg@serafini.com"
},
"skills": [
"./skills"
],
"commands": [
"./commands"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# process-improvement
Systematic intervention system for detecting frustration, analyzing root causes, implementing fixes, and tracking effectiveness over time

23
commands/improve.md Normal file
View File

@@ -0,0 +1,23 @@
Use the process-improvement-protocol skill to systematically analyze and fix workflow frustrations.
**Usage:** `/improve [week|month|year|all]`
**Time frames:**
- `/improve` or `/improve month` - Analyze last 30 days (default)
- `/improve week` - Analyze last 7 days (recent issues only)
- `/improve year` - Analyze last 365 days (long-term patterns)
- `/improve all` - Analyze entire history (all time)
**What this does:**
1. Saves your current context (for resume later)
2. Analyzes root causes using historical data (within time frame)
3. Proposes evidence-based fixes
4. Implements fixes immediately (with your approval)
5. Tracks effectiveness over time
**When to use:**
- You're frustrated with repeated agent failures
- Agent keeps making the same mistake
- You want systematic improvement, not apologies
**Invokes:** Skill(process-improvement:process-improvement-protocol)

49
plugin.lock.json Normal file
View File

@@ -0,0 +1,49 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:gserafini/process-improvement:",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "1314a172919ee31a0011f8d98e6dc0fb23872ba5",
"treeHash": "8c7c858c537ac1407c332c1d60e5b60e6024e07f7cf995e80c5f0ec534372f75",
"generatedAt": "2025-11-28T10:17:06.903417Z",
"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": "process-improvement",
"description": "Systematic intervention system for detecting frustration, analyzing root causes, implementing fixes, and tracking effectiveness over time",
"version": "1.0.1"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "035c9a5b3284f7ffdd531a6ce06981a157863a65aacb0f7c56793f480b6c3450"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "415d77d5cbf9fa22a86b7336e34cc68b83256e72c9548e3094af80b2e06bf34a"
},
{
"path": "commands/improve.md",
"sha256": "9d3eb7b98401c5880ed20fb6f4ec8266fc7361b0e739e668c4153bcc011305fa"
},
{
"path": "skills/process-improvement-protocol/SKILL.md",
"sha256": "001f4678f1d679c1bce2390447888be26e6797a812fe286f2f942f7f584d7752"
}
],
"dirSha256": "8c7c858c537ac1407c332c1d60e5b60e6024e07f7cf995e80c5f0ec534372f75"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

433
skills/process-improvement-protocol/SKILL.md Normal file
View File

@@ -0,0 +1,433 @@
---
name: process-improvement-protocol
description: Use when user types /improve or frustration patterns detected - systematic intervention for reducing user frustration and improving workflow effectiveness through root cause analysis, evidence-based fixes, and effectiveness tracking
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Task, TodoWrite]
---
# 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}/incidents.jsonl`:
```json
{"timestamp":"2025-11-21T17:45:00Z","days_since_last":7,"severity":"major_win","pattern":"Testing skipped","root_cause":"Agent claimed 'production-ready' without testing","solution_implemented":"Added BLOCKER section to actually_works.md requiring TodoWrite + verification skill","fix_file":"fixes-registry/2025-11-21-testing-protocol-blocker.md","expected_impact":"Zero untested 'complete' claims","effectiveness_1week":null,"effectiveness_2week":null,"status":"active"}
```
### 5. Update days-without-incident.json
```json
{
"last_incident": "2025-11-21T17:45:00Z",
"days_since_last": 0,
"longest_streak": 14
}
```
### 6. User Acceptance
```
I hope this will improve our process and this frustration will hopefully not recur again.
We'll track our performance over time and revisit if needed.
Ready to get back to our earlier task?
1. Yes
2. Keep discussing improvements
```
If option 1: Continue to Phase 5 (Resume)
If option 2: Continue improvement conversation
## Phase 5: Resume Work
Display saved context from `${PLUGIN_DATA}/sessions/YYYY-MM-DD-HHMMSS-resume.json`:
```
We're done with Process Improvement Protocol. Here's where we were:
**What you were working on**: [working_on from resume.json]
**Active TODOs**:
- [list from current_todos]
**Files being edited**:
- [list from files_being_edited]
**Last thing you said**:
[last_user_message]
Please let me know how you'd like to proceed - continue with the above, or start something new?
```
User manually decides next action.
## Effectiveness Tracking (Weekly /improve Run)
When `/improve` runs (weekly or user-initiated), check for pending effectiveness measurements:
### 1. Load Pending Checks
```bash
# Find incidents needing 1-week check
jq -c 'select(.effectiveness_1week == null and
(now - (.timestamp | fromdate)) >= 604800)' "${PLUGIN_DATA}/incidents.jsonl"
# Find incidents needing 2-week check
jq -c 'select(.effectiveness_2week == null and
(now - (.timestamp | fromdate)) >= 1209600)' "${PLUGIN_DATA}/incidents.jsonl"
```
### 2. Count Pattern Occurrences
For each pending check, grep conversations within time frame:
```bash
# Example: Count "review agent" mentions within time frame
pattern_keywords="review agent|Plan agent|code-reviewer"
project_dir=$(echo ~/.claude/projects/-Users-gserafini-git-src-* | head -1)
# Use the parsed $days variable from trigger time frame
occurrences=$(find "$project_dir" -name "*.jsonl" -type f -mtime -${days} \
-exec grep -l "$pattern_keywords" {} \; | wc -l)
```
### 3. Calculate Success Rate
```
success_rate = 1 - (occurrences_after / occurrences_before)
status = success_rate >= 0.8 ? 'highly_effective' :
success_rate >= 0.5 ? 'moderately_effective' :
success_rate >= 0.2 ? 'minimally_effective' : 'ineffective'
```
### 4. Update incidents.jsonl
Update the incident entry with effectiveness data.
### 5. Report to User
```
📊 Effectiveness Check Results:
Fix: [fix name] (1 week ago)
- Before: X occurrences/week
- After: Y occurrences/week
- Success rate: Z%
- Status: [Highly effective ✅ / Needs refinement ⚠️]
- Recommendation: [Keep as-is / Refine / Replace]
```
## Common Mistakes
**Skipping context preservation**
- **Problem**: Lose work in progress when investigating frustration
- **Fix**: Always save resume.json FIRST before analyzing
**Generic root cause**
- **Problem**: "Agent made a mistake" doesn't help prevent recurrence
- **Fix**: Be specific - what EXACTLY went wrong? Why?
**No historical check**
- **Problem**: Repeat the same failed fixes
- **Fix**: Always check if this happened before and what was tried
**Implementing without user approval**
- **Problem**: User loses control, may disagree with approach
- **Fix**: Present options, get explicit approval before implementing
**No effectiveness tracking**
- **Problem**: Fixes live forever even if they don't work
- **Fix**: Always log to incidents.jsonl with null effectiveness fields for later measurement
## Red Flags
**Never:**
- Implement fixes without user approval
- Skip logging to incidents.jsonl
- Proceed without saving resume context
- Give generic "I'll do better" responses without specific fixes
- Skip effectiveness measurement for past fixes
**Always:**
- Save context FIRST (sessions/resume.json)
- Check for deferred incidents
- Present specific, evidence-based options
- Implement fixes immediately when approved
- Log everything to incidents.jsonl
- Track effectiveness over time
## Integration
**Invoked by:**
- User typing `/improve` command
- Frustration keyword auto-detection
**May invoke:**
- General-purpose Task agent for complex investigation (optional)
**Updates:**
- ${PLUGIN_DATA}/incidents.jsonl (append only)
- ${PLUGIN_DATA}/days-without-incident.json (overwrite)
- ${PLUGIN_DATA}/sessions/*.json (create new)
- ${PLUGIN_DATA}/deferred-incidents/*.json (create when deferred)
- ${PLUGIN_DATA}/fixes-registry/*.md (create per fix)
- ${PLUGIN_DATA}/successful-fixes.md (manual curation based on effectiveness)
- ${PLUGIN_DATA}/patterns-detected.md (manual curation of common issues)