debug-rules

Skill: debug-rules

When to Use

Use this skill when:

• Conditional rules don't seem to be loading
• Claude is ignoring instructions that should be in a rule file
• You changed rule frontmatter and want to verify it works
• You want to see what rules loaded in a specific session

Prerequisites

This skill requires the InstructionsLoaded audit hook. The hook is not registered by default - it's an on-demand diagnostic tool you enable when needed.

Setup (one-time)

The hook script ~/.claude/hooks/log-instructions.sh should already exist. To enable logging, add this to ~/.claude/settings.json under "hooks":

"InstructionsLoaded": [
  {
    "hooks": [
      {
        "type": "command",
        "command": "~/.claude/hooks/log-instructions.sh"
      }
    ]
  }
]

Then start a new session, do some work that touches files matching your conditional rules, and run /debug-rules again.

Remove the hook from settings.json when done - it's lightweight but unnecessary for normal use.

Step 1: Verify hook is active

1. Check ~/.claude/hooks/log-instructions.sh exists and is executable
2. Check ~/.claude/settings.json has an InstructionsLoaded entry pointing to it
3. Check ~/.claude/instruction-audit.log exists and is non-empty

If the hook script is missing, tell the user and stop. If the hook script exists but isn't registered in settings.json, show them the setup instructions above. If the log doesn't exist or is empty, tell the user: "No audit log found. Register the hook, start a new session, do some work, then run /debug-rules again."

Step 2: Read the audit log

Read ~/.claude/instruction-audit.log. If the user provided a timestamp, filter to entries from that session. If they said "latest" or gave no argument, use the most recent session (group by timestamp - entries within 2 seconds of each other are the same session start).

Step 3: Inventory expected rules

Read all files in ~/.claude/rules/. For each file:

• If it has no paths: frontmatter → it should appear with reason: session_start
• If it has paths: frontmatter → it should appear with reason: path_glob_match only when matching files are read