AgentSkillsCN

framework_repair_suggester

检测框架和工具问题，然后建议创建REPAIR任务以系统地解决——仅限分析的技能，识别问题并提出结构化修复方案

SKILL.md
--- frontmatter
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.0

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

markdown
### 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

markdown
### 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:

markdown
## 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:

markdown
### 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