From capa
Corrective and Preventive Action process for fixing broken processes. Use when: - A delivered feature doesn't work despite having process skills in place - The same failure pattern recurs (you've seen this before) - "Done" was claimed but it doesn't actually work - A skill or gate failed to fire when it should have - Process was followed on paper but missed reality Trigger: /capa [what's broken], or when user says "figure out why X isn't working", "why did this fail again", "our process didn't catch this", "do a retrospective on X" NOT for: simple bugs (use systematic-debugging), first-time implementation (use dev-process), or design exploration (use brainstorming). CAPA is for when the PROCESS itself failed.
How this skill is triggered — by the user, by Claude, or both
Slash command
/capa:capaThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
```
FIX THE PROCESS FIRST.
THEN USE THE FIXED PROCESS TO FIX THE DEFECT.
If you fix the defect before fixing the process, you lose leverage to fix the root cause. The defect fix is the PROOF the process works — not the primary deliverable.
CAPA records are tracked in a shared SQLite DB accessible from BOTH environments:
Canonical path (in container): /home/openclaw/.openclaw/capa/capa.db
Access from Claude Code (host):
docker exec openclaw-playground sqlite3 /home/openclaw/.openclaw/capa/capa.db "YOUR QUERY"
Access from OpenClaw (container):
sqlite3 /home/openclaw/.openclaw/capa/capa.db "YOUR QUERY"
Schema is in references/schema.sql. Initialize if it doesn't exist:
# From host:
docker cp references/schema.sql openclaw-playground:/tmp/capa-schema.sql
docker exec -u openclaw openclaw-playground bash -c "cat /tmp/capa-schema.sql | sqlite3 /home/openclaw/.openclaw/capa/capa.db"
# From container:
cat references/schema.sql | sqlite3 /home/openclaw/.openclaw/capa/capa.db
Log every phase transition to the changelog table. This is append-only — never delete rows.
IMPORTANT: Use the CAPA_DB helper variable throughout this skill. Set it at the start:
CAPA_DB="docker exec openclaw-playground sqlite3 /home/openclaw/.openclaw/capa/capa.db"CAPA_DB="sqlite3 /home/openclaw/.openclaw/capa/capa.db"You MUST complete each phase before proceeding. Create tasks for tracking.
Phase 1: DETECT ──> Phase 2: INVESTIGATE ──> Phase 3: RESEARCH ──> Phase 4: DESIGN
│
Phase 8: CLOSE <── Phase 7: RE-EXECUTE <── Phase 6: VERIFY <── Phase 5: IMPLEMENT
Goal: Create a clear record of what went wrong.
Document the gap:
Create CAPA record:
sqlite3 ~/.claude/capa/capa.db "
INSERT INTO capa_records (title, trigger_description, status, severity)
VALUES ('[short title]', '[full description]', 'open', '[critical|high|medium|low]');
"
Log to changelog:
sqlite3 ~/.claude/capa/capa.db "
INSERT INTO changelog (capa_id, phase, action, details)
VALUES ([id], 'detect', 'CAPA opened', '[summary]');
"
Output: CAPA record ID. Use this ID for all subsequent phases.
Goal: Map every failure to the skill or gate that should have prevented it.
Do NOT propose fixes yet. Investigation only. If you catch yourself proposing solutions, STOP and return to tracing the failure chain.Trace the failure chain using the 5 Whys:
Map each failure to a skill/gate:
| Failure | Skill That Should Have Caught It | Why It Didn't Fire |
|---|---|---|
| [what went wrong] | [which skill] | [why it was skipped/unavailable/ineffective] |
Categorize root causes and log them:
sqlite3 ~/.claude/capa/capa.db "
INSERT INTO root_causes (capa_id, description, skill_that_failed, why_it_failed, category)
VALUES ([id], '[description]', '[skill name]', '[why]', '[category]');
"
Categories: spec_written_from_memory, wrong_code_path, mock_tested_not_real,
tests_never_ran, self_reported_verification, skill_not_available,
skill_not_enforced, no_acceptance_criteria, speed_over_correctness
Check for patterns — has this root cause appeared before?
sqlite3 -header -column ~/.claude/capa/capa.db "SELECT * FROM recurring_patterns"
Update status:
sqlite3 ~/.claude/capa/capa.db "UPDATE capa_records SET status='investigating', category='[primary category]' WHERE id=[id]"
Output: Root cause map with skill-to-failure mapping. Present to user before proceeding.
Goal: Find proven solutions before designing your own.
External research (Perplexity):
perplexity_ask with max_tokens_per_page: 256, max_results: 3Internal research:
~/.claude/projects/-home-orangepi/memory/ for related past decisionsLog findings:
sqlite3 ~/.claude/capa/capa.db "
INSERT INTO research_findings (capa_id, source_type, finding, citation)
VALUES ([id], '[perplexity|github|memory|article|previous_capa|skill_review]',
'[finding]', '[url or reference]');
"
Update status:
sqlite3 ~/.claude/capa/capa.db "UPDATE capa_records SET status='researching' WHERE id=[id]"
Output: Research findings with citations. Synthesize into 3-5 actionable insights.
Goal: Design specific changes to skills, gates, or enforcement that address each root cause.
For each root cause, propose a fix:
Propose 2-3 approaches with trade-offs (like brainstorming):
Get Kyle's approval:
"Here's the process fix design. [Present options.] I recommend Option [X] because [reason]. Approve to proceed?"
Update status:
sqlite3 ~/.claude/capa/capa.db "UPDATE capa_records SET status='designing' WHERE id=[id]"
Output: Approved process fix design.
Goal: Build the approved process changes. This is the primary deliverable.
Implement each approved change:
Log each change:
sqlite3 ~/.claude/capa/capa.db "
INSERT INTO process_changes (capa_id, change_type, description, files_changed)
VALUES ([id], '[new_skill|modified_skill|new_gate|new_enforcement|config_change]',
'[what changed]', '[\"file1.md\", \"file2.md\"]');
"
Update status:
sqlite3 ~/.claude/capa/capa.db "UPDATE capa_records SET status='implementing' WHERE id=[id]"
Output: Working process changes, committed if applicable.
Goal: Prove the new process would have caught the original failure.
Walk through the original failure scenario with the new gates in place:
For each root cause, verify the fix addresses it:
| Root Cause | Fix Applied | Would It Have Caught It? | Evidence |
|---|---|---|---|
| [cause 1] | [fix 1] | Yes/No | [how you verified] |
Mark changes as verified:
sqlite3 ~/.claude/capa/capa.db "UPDATE process_changes SET verified=1 WHERE capa_id=[id]"
Update status:
sqlite3 ~/.claude/capa/capa.db "
UPDATE capa_records SET status='verifying', process_fixed=1 WHERE id=[id]
"
Output: Verification table showing each root cause is addressed.
Goal: Use the new process to fix what originally broke. This proves the process works.
Invoke the appropriate process skills:
brainstorming to re-spec correctlydev-process pipelinetest-driven-developmentThe new process gates should fire naturally:
Update status:
sqlite3 ~/.claude/capa/capa.db "UPDATE capa_records SET status='re-executing' WHERE id=[id]"
Output: The original defect, fixed correctly using the new process.
Goal: Close the loop. Log outcome, update records, save learnings.
Update CAPA record:
sqlite3 ~/.claude/capa/capa.db "
UPDATE capa_records SET
status='closed',
closed_at=datetime('now'),
defect_fixed=1,
outcome='[summary of what changed and what was learned]'
WHERE id=[id]
"
Final changelog entry:
sqlite3 ~/.claude/capa/capa.db "
INSERT INTO changelog (capa_id, phase, action, details)
VALUES ([id], 'close', 'CAPA closed', '[lessons learned summary]');
"
Save to memory if the learning is durable:
Check stats — how are we trending?
sqlite3 -header -column ~/.claude/capa/capa.db "SELECT * FROM category_stats"
sqlite3 -header -column ~/.claude/capa/capa.db "SELECT * FROM recurring_patterns"
Output: Closed CAPA record. Brief summary to Kyle.
| Thought | Reality | Go Back To |
|---|---|---|
| "Let me just fix the defect quickly first" | Process fix is the primary deliverable | Phase 4 |
| "The process fix is overkill for this" | If the process failed, it needs fixing | Phase 2 |
| "I know the fix without researching" | Past knowledge may be outdated or wrong | Phase 3 |
| "This root cause is too small to track" | Small gaps compound. Log everything. | Phase 2 |
| "The same skill exists, it just wasn't used" | Then enforcement is the root cause | Phase 2 |
| "Let me skip verification, the fix is obvious" | Obvious fixes fail silently | Phase 6 |
Check open CAPAs:
sqlite3 -header -column ~/.claude/capa/capa.db "SELECT * FROM capa_summary WHERE status != 'closed'"
Check recurring patterns:
sqlite3 -header -column ~/.claude/capa/capa.db "SELECT * FROM recurring_patterns"
Full stats:
sqlite3 -header -column ~/.claude/capa/capa.db "
SELECT COUNT(*) as total,
SUM(CASE WHEN status='closed' THEN 1 ELSE 0 END) as closed,
SUM(CASE WHEN process_fixed THEN 1 ELSE 0 END) as process_fixed,
SUM(CASE WHEN defect_fixed THEN 1 ELSE 0 END) as defect_fixed
FROM capa_records
"
Which skills fail most:
sqlite3 -header -column ~/.claude/capa/capa.db "
SELECT skill_that_failed, COUNT(*) as fails
FROM root_causes WHERE skill_that_failed IS NOT NULL
GROUP BY skill_that_failed ORDER BY fails DESC
"
npx claudepluginhub kyletabor/claude_plugins --plugin capaCaptures lessons learned from implementation, production, QA, and release so the project improves over time. Use after milestones, repeated failures, or postmortems.
Guides systematic debugging of bugs, test failures, unexpected behavior: memory integrity check, reproduce, isolate, diagnose root cause before fixes.
Structured root cause investigation and CAPA management for compliance deviations. Selects investigation methods (5-Why, fishbone, fault tree), designs corrective/preventive actions, verifies effectiveness, and analyzes trends.