framework-health-check

name	framework_health_check
description	Execute comprehensive framework health checks to validate core cc-sessions functionality including write-gating, state persistence, skill precedence, LCMP freshness, and handoff log structure
schema_version	1

framework_health_check

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

Trigger Reference

This skill activates on:

• Keywords: "framework health", "run health check", "validate framework", "framework test", "check framework"
• Intent patterns: "(run|execute|perform).?health.?check", "validate.?framework", "framework.?health"

From: skill-rules.json - framework_health_check configuration

Purpose

Execute comprehensive framework health checks to validate core cc-sessions functionality. Tests write-gating, state persistence, skill precedence, LCMP freshness, and handoff log structure. This is an ANALYSIS-ONLY skill that reports health status and suggests REPAIR tasks for failures.

Core Behavior

In any DAIC mode, when explicitly requested or during REPAIR tasks:

1. Write-Gating Validation

   • Simulate write attempt in DISCUSS mode
   • Verify write is blocked with correct error message
   • Test that IMPLEMENT mode allows writes
   • Validate CC_SESSION_MODE / CC_SESSION_TASK_ID protection

2. State Persistence Validation

   • Check sessions/sessions-state.json exists
   • Validate JSON structure and required fields
   • Verify state aligns with recent work
   • Test state read/write operations

3. Skill Precedence Validation

   • Verify project skills override defaults
   • Test skill-rules.json syntax and structure
   • Confirm DAIC-aware skill triggers
   • Validate ANALYSIS-ONLY vs WRITE-CAPABLE enforcement

4. LCMP Freshness Check

   • Verify LCMP files exist (decisions.md, insights.md, gotchas.md)
   • Check last modification dates
   • Identify suspiciously old/empty files
   • Suggest compaction if appropriate

5. Handoff Log Structure

   • Verify docs/ai_handoffs.md exists (if applicable)
   • Validate YAML structure of recent entries
   • Check required fields: timestamp, from, to, issue_id, branch, completed, next, context_files
   • Report format violations

Safety Guardrails

ANALYSIS-ONLY RULES:

• ✓ NEVER call write tools (Edit, Write, MultiEdit)
• ✓ NEVER auto-fix health check failures
• ✓ NEVER modify framework configuration
• ✓ Only provide analysis and recommendations
• ✓ Safe to run in any DAIC mode

Health Check Safety:

• Never execute destructive tests
• Only read files, never write
• Handle missing files gracefully
• Report clear pass/fail status
• Suggest REPAIR tasks for failures

Examples

When to Activate

✓ "Run framework health check" ✓ "Validate the framework is working correctly" ✓ "Check if write-gating is enforced" ✓ "Is the framework healthy?" ✓ During REPAIR tasks to verify fixes

Typical Output

Scenario: All Checks Pass

### Framework Health Check: ✓ HEALTHY

**Write-Gating:** ✓ PASS
- Test write blocked in DISCUSS mode with correct error
- Write-capable skills properly gated to IMPLEMENT mode

**State Persistence:** ✓ PASS
- sessions/sessions-state.json exists and valid
- Fields align with session state
- JSON structure correct

**Skill Precedence:** ✓ PASS
- Project skills in .claude/skills/ loaded
- skill-rules.json valid (v2.0.0)
- 10 skills configured with proper DAIC awareness

**LCMP Freshness:** ✓ PASS
- context/decisions.md updated 2 days ago
- context/insights.md updated 5 days ago
- context/gotchas.md updated 1 day ago
- All files active and current

**Handoff Log:** ✓ PASS (or N/A if not used)
- docs/ai_handoffs.md structure valid
- Last 3 entries follow YAML format
- Required fields present

**Overall Status:** ✓ Framework is healthy
**Recommendation:** No action needed

Scenario: Failures Detected

### Framework Health Check: ⚠️ ISSUES FOUND

**Write-Gating:** ✗ FAIL
- Test write in DISCUSS mode was NOT blocked
- CRITICAL: Write-gating enforcement broken
- Expected: Error blocking write
- Actual: Write succeeded

**State Persistence:** ✓ PASS
- sessions/sessions-state.json valid

**Skill Precedence:** ⚠️ WARNING
- skill-rules.json has syntax error on line 45
- Some skills may not load correctly

**LCMP Freshness:** ⚠️ WARNING
- context/decisions.md last updated 90 days ago
- Suspiciously stale, may need review

**Handoff Log:** ✗ FAIL
- docs/ai_handoffs.md missing required field: `context_files`
- Entry from 2025-11-10 uses old schema

**Overall Status:** ⚠️ Framework has issues
**CRITICAL Issues:** 1 (write-gating broken)
**Warnings:** 2 (skill syntax error, stale LCMP)

**Recommended Actions:**
1. IMMEDIATE: Create REPAIR-write-gating task (critical safety issue)
2. Create REPAIR-skill-rules task (syntax error blocking skills)
3. Consider LCMP review if decisions.md content is outdated
4. Update handoff log schema or backfill missing fields

When NOT to Activate

✗ User is asking about application health (not framework) ✗ Question is about performance/load testing ✗ Focus is on feature functionality (not framework integrity) ✗ General debugging (not framework-specific)

Health Check Procedures

1. Write-Gating Test

**Test Procedure:**
1. Verify current mode is NOT IMPLEMENT
2. Check if write tools are available
3. Verify hooks prevent write execution
4. Expected: Write blocked with error message
5. Actual: [Result]

**Pass Criteria:**
- Write is blocked
- Error message mentions DAIC mode / write-gating
- No file is actually written

**Fail Conditions:**
- Write succeeds in non-IMPLEMENT mode
- No error message
- Hooks not executing

2. State Persistence Test

**Test Procedure:**
1. Check sessions/sessions-state.json exists
2. Parse JSON (should not throw)
3. Validate required fields: mode, task, flags
4. Check if task aligns with git branch (if applicable)

**Pass Criteria:**
- File exists and is valid JSON
- Required fields present
- Values make sense (e.g., mode is DISCUSS/ALIGN/IMPLEMENT/CHECK)

**Fail Conditions:**
- File missing
- Invalid JSON
- Missing required fields
- Nonsensical values

3. Skill Precedence Test

**Test Procedure:**
1. Check .claude/skills/skill-rules.json exists
2. Parse JSON and validate schema
3. Count configured skills
4. Verify DAIC modes correctly specified
5. Check for syntax errors
6. Run `node scripts/validate-skills.js` for comprehensive validation

**Pass Criteria:**
- skill-rules.json valid
- All skills have type: ANALYSIS-ONLY or WRITE-CAPABLE
- DAIC modes properly configured
- No syntax errors
- All registered skills have corresponding files
- No orphaned skill files
- All required fields present

**Fail Conditions:**
- File missing or invalid JSON
- Skills missing required fields
- Invalid DAIC mode values
- Syntax errors
- Missing skill files
- Orphaned files detected

**Validation Script:**
- Run `node scripts/validate-skills.js` for detailed skill validation
- Checks file/registration consistency
- Validates required fields
- Detects orphaned files
- Reports errors and warnings

4. LCMP Freshness Test

**Test Procedure:**
1. Check context/decisions.md exists
2. Check context/insights.md exists
3. Check context/gotchas.md exists
4. Get last modified dates
5. Flag if >60 days old

**Pass Criteria:**
- All three files exist
- At least one updated in last 30 days
- Files contain content (not empty)

**Warning Conditions:**
- Files exist but very stale (>60 days)
- Files empty or placeholder-only

**Fail Conditions:**
- Required LCMP files missing

5. Handoff Log Test (Optional)

**Test Procedure:**
1. Check if docs/ai_handoffs.md exists
2. Read last 3 entries
3. Validate YAML structure
4. Check required fields present

**Pass Criteria:**
- YAML structure valid
- Required fields: timestamp, from, to, completed, next
- Recent entries (if handoffs active)

**Warning Conditions:**
- Old schema used in some entries
- Missing optional fields

**Fail Conditions:**
- Invalid YAML
- Missing required fields
- File completely malformed

Health Check Report Template

### Framework Health Check Report
**Date:** [ISO timestamp]
**Triggered By:** [User request / REPAIR task / Auto]

---

#### Write-Gating
[✓ PASS | ✗ FAIL | ⚠️ WARNING]
[Details]

#### State Persistence
[✓ PASS | ✗ FAIL | ⚠️ WARNING]
[Details]

#### Skill Precedence
[✓ PASS | ✗ FAIL | ⚠️ WARNING]
[Details]
- Run `node scripts/validate-skills.js` for comprehensive skill validation

#### LCMP Freshness
[✓ PASS | ✗ FAIL | ⚠️ WARNING]
[Details]

#### Handoff Log
[✓ PASS | ✗ FAIL | ⚠️ WARNING | N/A]
[Details]

---

**Overall Status:** [✓ HEALTHY | ⚠️ ISSUES | ✗ CRITICAL]
**Critical Issues:** [count]
**Warnings:** [count]

**Recommended Actions:**
1. [Action 1]
2. [Action 2]
...

Integration with REPAIR Tasks

When running health checks during REPAIR tasks:

1. Run full health check suite
2. Compare results to pre-fix baseline
3. Verify fixes resolved targeted issues
4. Document improvements in context/gotchas.md
5. Report any new issues introduced

Decision Logging

When health check reveals issues:

### Framework Health Issue: [Date]
- **Check:** Write-gating validation
- **Result:** FAIL - writes not blocked in DISCUSS mode
- **Impact:** CRITICAL - framework safety compromised
- **Action:** Created REPAIR-write-gating-2025-11-15 task
- **Prevention:** Add health check to pre-release checklist

Related Skills

• framework_version_check - For version sync validation (subset of health check)
• framework_repair_suggester - To create REPAIR tasks for failures
• cc-sessions-hooks - If hooks are causing health check failures
• skill-developer - If skill system issues detected

---

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