Cf Debug

CLI Usage: When unsure about a CLI's interface or flags, run it with --help first. Do NOT attempt to discover functionality by reading plugin source code — doing so leads to incorrect execution from assumptions made without context of the holistic flow.

CLEAR Debug & Diagnostics

Validate CLEAR framework state across all domains (sync, workpackage, plan, knowledge, session) and optionally auto-repair fixable issues. Routes to the debug CLI tool for execution.

Plugin Root Resolution

CLI commands in this skill reference $CLEAR_PLUGIN_ROOT — a .claude/settings.json env var the shell expands. The SessionStart hook persists it, but settings env vars load at session launch, so on a brand-new consumer's first session (before its next restart) the variable is empty and node "$CLEAR_PLUGIN_ROOT/build/..." fails with MODULE_NOT_FOUND.

First-session bootstrap — if $CLEAR_PLUGIN_ROOT is empty, set it inline in the same Bash call as the CLI (each Bash call is a fresh shell, so a separate export would not carry over):

export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"

Prepend it to the CLI in one shell line: export CLEAR_PLUGIN_ROOT="${CLEAR_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"; <node "$CLEAR_PLUGIN_ROOT/build/..." command>. ${CLAUDE_PLUGIN_ROOT} resolves in this SKILL.md body to the actually-loaded plugin path; once the consumer restarts, $CLEAR_PLUGIN_ROOT is populated and the assignment is a harmless no-op.

When to Use This Skill

Load this skill when the user request matches ANY of these patterns:

DO NOT use for:

• Initializing CLEAR for the first time (use /cf-init instead)
• Viewing current CLEAR status or session info (use /cf-status instead)
• Reloading CLEAR context (use /cf-reload instead)

Command Reference

Debug CLI at $CLEAR_PLUGIN_ROOT/build/infrastructure/sync/cli/.

Usage

/cf-debug                        # Full diagnostic across all domains
/cf-debug workpackage            # Focus on a specific domain
/cf-debug install                # Verify Claude Code install wiring (run after restart)
/cf-debug --check-ids            # Include dual-ID integrity validation
/cf-debug --repair               # Attempt auto-repair of fixable issues
/cf-debug sync --repair          # Domain-specific diagnostic with repair

Arguments:

• [domain]: Optional. One of sync, workpackage, plan, knowledge, session, install
• --repair: Attempt auto-repair of fixable issues
• --check-ids: Include dual-ID integrity validation

Instructions

Step 1: Pre-flight Check

Verify CLEAR is initialized:

if [ -d ".clear" ]; then
  echo "CLEAR_EXISTS"
else
  echo "NO_CLEAR"
fi

If NO_CLEAR: tell the user "CLEAR directory not found. Run /cf-init to initialize CLEAR." and stop.

Step 2: Parse Arguments and Execute

Build the CLI command from the provided arguments and run the debug tool:

ARGS=""

for arg in $ARGUMENTS; do
  case "$arg" in
    sync|workpackage|plan|knowledge|session|install)
      ARGS="$ARGS $arg"
      ;;
    --repair)
      ARGS="$ARGS --repair"
      ;;
    --check-ids)
      ARGS="$ARGS --check-ids"
      ;;
  esac
done

cd "$(pwd)" && node "$CLEAR_PLUGIN_ROOT/build/infrastructure/sync/cli/debug-cli.js" $ARGS

Step 3: Interpret Results

The CLI checks the following by domain:

Step 4: Report Auto-Repair Results (if --repair)

When --repair is specified, the following issues can be auto-repaired:

Issues that cannot be auto-repaired (inform the user):

• Invalid systemId formats (requires manual correction)
• Duplicate systemIds (requires manual resolution)
• Missing workpackage/plan files (requires recreation)
• Cross-domain reference mismatches (requires investigation)

Step 5: Present Summary

Present the diagnostic report to the user. Highlight any errors or warnings that need attention, and confirm any repairs that were applied.

Completion Checklist

Before returning to the user, verify:

• CLEAR directory existence was confirmed before running diagnostics
• Debug CLI executed successfully with the correct arguments
• Diagnostic output was presented to the user with clear next steps for any issues found