framework-repair-suggester

name	framework_repair_suggester
description	Detect framework and tooling issues then suggest creating REPAIR- tasks to address them systematically - ANALYSIS-ONLY skill that identifies problems and proposes structured fixes
schema_version	1

framework_repair_suggester

Type: ANALYSIS-ONLY DAIC Modes: DISCUSS, ALIGN, IMPLEMENT, CHECK (all modes) Priority: High

Trigger Reference

This skill activates on:

• Keywords: "REPAIR task", "framework issue", "broken gating", "framework bug", "framework broken"
• Intent patterns: "create.?REPAIR.?task", "framework.*(issue|bug|broken|problem)", "REPAIR-"

From: skill-rules.json - framework_repair_suggester configuration

Purpose

Detect framework and tooling issues, then suggest creating REPAIR- tasks to address them systematically. This is an ANALYSIS-ONLY skill that identifies problems and proposes structured fixes, but never modifies framework files directly.

Core Behavior

In any DAIC mode:

1. Issue Detection

   • Monitor for framework misbehavior (hooks not firing, write-gating bypassed, state corruption)
   • Identify when framework docs are out of sync
   • Detect when skills aren't working as configured
   • Recognize when prompts are inconsistent or outdated
   • Notice when gating rules are being violated

2. Root Cause Analysis

   • Investigate why the issue occurred
   • Check related framework components
   • Review recent changes that might have caused it
   • Identify systemic vs. one-off problems
   • Assess impact and urgency

3. REPAIR Task Proposal

   • Generate REPAIR- task ID with date (e.g., REPAIR-write-gating-2025-11-15)
   • Define problem clearly and specifically
   • Propose solution approach
   • List files that need investigation/modification
   • Provide success criteria
   • Include prevention strategy

4. Context Gathering

   • Collect error messages, logs, and symptoms
   • Identify affected components
   • Note when issue first appeared
   • Gather recent changes for correlation
   • Provide all context needed for repair

Safety Guardrails

ANALYSIS-ONLY RULES:

• ✓ NEVER call write tools (Edit, Write, MultiEdit)
• ✓ NEVER auto-create REPAIR task files
• ✓ NEVER modify framework directly
• ✓ Only provide analysis and task proposals
• ✓ Safe to run in any DAIC mode

Issue Detection Safety:

• Don't false-alarm on expected behavior
• Distinguish framework bugs from user errors
• Verify issue is reproducible before suggesting REPAIR
• Assess urgency accurately (CRITICAL vs. low priority)
• Suggest workarounds when available

Examples

When to Activate

✓ "Write-gating isn't blocking writes in DISCUSS mode" ✓ "The sessions_enforce hook seems broken" ✓ "Framework version drift detected" ✓ "Skills aren't triggering when they should" ✓ "Create a REPAIR task for X"

Typical Output

Scenario: Write-Gating Failure

### REPAIR Task Suggestion: Write-Gating Broken

**Issue Detected:** Write tools are not being blocked in DISCUSS mode

**Symptoms:**
- Write tool succeeded in DISCUSS mode (expected: blocked)
- No error message from sessions_enforce hook
- sessions-state.json shows mode=DISCUSS but write completed

**Impact:** CRITICAL
- Framework safety compromised
- Users can bypass DAIC discipline
- Risk of unintended file modifications

**Root Cause (Suspected):**
- sessions/hooks/sessions_enforce.js may not be loaded
- Hook might have syntax error preventing execution
- PreToolUse hook registration may have failed

**Proposed REPAIR Task:**

**Task ID:** `REPAIR-write-gating-2025-11-15`

**Problem:**
Write-gating enforcement is broken. Write tools (Edit, Write, MultiEdit) are not being blocked when mode is DISCUSS/ALIGN/CHECK. This is a critical safety issue that undermines the framework's core discipline.

**Investigation Steps:**
1. Check if sessions/hooks/sessions_enforce.js exists and loads
2. Review hook for syntax errors or logic bugs
3. Verify PreToolUse hook registration in Claude Code
4. Test write-gating in each DAIC mode
5. Check if hook execution order matters

**Files to Review:**
- sessions/hooks/sessions_enforce.js
- sessions/hooks/README.md (if exists)
- Hook loading mechanism
- sessions/sessions-config.json (hook configuration)

**Proposed Fix:**
1. Fix syntax errors if present
2. Add defensive logging to hook
3. Ensure hook returns { success: false } correctly
4. Test in all modes before deploying

**Success Criteria:**
- Write tools blocked in DISCUSS/ALIGN/CHECK modes
- Clear error message shown to user
- Write tools allowed in IMPLEMENT mode
- Health check passes for write-gating

**Prevention:**
- Add write-gating test to framework health check
- Run health check before committing hook changes
- Document hook testing procedure
- Add to pre-release checklist

**Would you like me to create this REPAIR task file?**
(Note: This requires IMPLEMENT mode and user approval)

Scenario: Skill Configuration Issue

### REPAIR Task Suggestion: Skill Triggers Not Firing

**Issue Detected:** Skills defined in skill-rules.json are not activating

**Symptoms:**
- User mentions "error tracking" keywords but error-tracking skill doesn't activate
- skill-rules.json appears valid
- No obvious syntax errors

**Impact:** MEDIUM
- Skills not providing value
- User experience degraded
- Wasted skill development effort

**Root Cause (Suspected):**
- Skill trigger patterns may be too narrow
- Auto-trigger logic may not be implemented
- Skill loading may have failed silently

**Proposed REPAIR Task:**

**Task ID:** `REPAIR-skill-triggers-2025-11-15`

**Problem:**
Skills are configured in skill-rules.json but not activating when expected. This suggests either trigger patterns are incorrect, or the skill activation system isn't working properly.

**Investigation Steps:**
1. Verify .claude/skills/*/SKILL.md files exist for all configured skills
2. Test skill loading with simple trigger phrases
3. Review auto-trigger implementation (if any)
4. Check Claude Code skill loading mechanism
5. Validate trigger pattern regex syntax

**Files to Review:**
- .claude/skills/skill-rules.json
- .claude/skills/*/SKILL.md (all skill prompt files)
- Skill activation logs (if available)

**Proposed Fix:**
1. Broaden trigger patterns if too narrow
2. Verify skill prompt files exist and match skill-rules.json names
3. Add manual activation examples if auto-trigger not working
4. Document current skill activation mechanism

**Success Criteria:**
- Skills activate on appropriate keywords
- Manual skill invocation works reliably
- Skill activation logged for debugging
- User can easily trigger relevant skills

**Prevention:**
- Test skill triggers during skill development
- Document trigger phrases clearly
- Provide manual activation fallback
- Add skill activation to health check

**Would you like me to create this REPAIR task file?**

When NOT to Activate

✗ User is debugging application code (not framework) ✗ Issue is expected behavior (not a bug) ✗ Problem is user error (not framework malfunction) ✗ Issue can be resolved without REPAIR task

REPAIR Task Template

Standard structure for REPAIR task proposals:

## Task: REPAIR-[component]-[YYYY-MM-DD]

### Problem
[Clear, specific description of what's broken]

### Symptoms
- [Observable symptom 1]
- [Observable symptom 2]
- [Observable symptom 3]

### Impact
[CRITICAL | HIGH | MEDIUM | LOW]
[Explanation of impact]

### Root Cause (Suspected)
[Hypothesis about what's causing the issue]

### Investigation Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Files to Review
- [file path 1]
- [file path 2]

### Proposed Fix
[Approach to fixing the issue]

### Success Criteria
- [Measurable outcome 1]
- [Measurable outcome 2]
- [Health check passes]

### Prevention
[How to prevent this from happening again]

### Context Files
- [Relevant Tier-1 doc 1]
- [Relevant Tier-2 doc 1]

Common Framework Issues

1. Write-Gating Failures

Symptoms: Writes succeed in non-IMPLEMENT modes Urgency: CRITICAL Component: sessions/hooks/sessions_enforce.js

2. Hook Not Executing

Symptoms: Hook logic bypassed, no errors Urgency: HIGH Component: Hook registration, hook syntax

3. State Corruption

Symptoms: Invalid state values, JSON parse errors Urgency: HIGH Component: State read/write logic

4. Skill Loading Failures

Symptoms: Skills don't trigger, missing skill errors Urgency: MEDIUM Component: skill-rules.json, skill .md files

5. Framework Doc Drift

Symptoms: Version mismatch, inconsistent guidance Urgency: MEDIUM Component: claude.md, claude-reference.md

6. LCMP Staleness

Symptoms: Old/empty LCMP files, no compaction Urgency: LOW Component: context/*.md files

Urgency Assessment

CRITICAL - Framework safety compromised, immediate fix needed

• Write-gating bypassed
• State corruption causing crashes
• Security vulnerability

HIGH - Core functionality broken, fix soon

• Hooks not executing
• Task startup failing
• DAIC transitions broken

MEDIUM - Features degraded, fix when convenient

• Skills not triggering
• Documentation drift
• Non-critical commands failing

LOW - Minor issues, address eventually

• LCMP staleness
• Minor inconsistencies
• Nice-to-have improvements

Decision Logging

When proposing REPAIR tasks:

### REPAIR Task Proposed: [Date]
- **Task ID:** REPAIR-write-gating-2025-11-15
- **Issue:** Write-gating enforcement broken
- **Urgency:** CRITICAL
- **User Response:** [Approved / Deferred / Rejected]
- **Action Taken:** [Created task file / Added to backlog / Noted in gotchas.md]

Related Skills

• framework_health_check - For detecting issues that need REPAIR
• framework_version_check - For detecting version drift requiring REPAIR
• cc-sessions-hooks - For implementing hook fixes during REPAIR
• cc-sessions-core - For implementing framework fixes during REPAIR
• skill-developer - For implementing skill fixes during REPAIR

---

Last Updated: 2025-11-15 Framework Version: 2.0