skills.rest
ElvinOuyang
ElvinOuyangCOMMUNITY
Explore all skills by this author →
GitHub

harness-troubleshoot

Diagnose Claude Code harness enforcement failures using a structured decision tree.

Updated Aug 27, 2026
Search Tags:#state management#troubleshooting#claude code#enforcement#harness#automation scripts#scope mismatch
One-click install
npx skills add https://github.com/ElvinOuyang/claude-skill-collection --skill harness-troubleshoot
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: harness-troubleshoot
Source: https://github.com/ElvinOuyang/claude-skill-collection/tree/main/plugins/harness-engineering-toolkit/skills/harness-troubleshoot
Command: npx skills add https://github.com/ElvinOuyang/claude-skill-collection --skill harness-troubleshoot

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you diagnose and fix Claude Code harness enforcement issues that prevent progress, such as infinite stop-hook loops, scope mismatches, stale harness state, stuck phases, or hooks not firing.

Core Features & Use Cases

  • Decision-tree troubleshooting to pinpoint the exact harness failure mode based on symptoms like “can’t stop,” “phases won’t mark complete,” or “hook not working.”
  • Targeted recovery steps for the most common harness breakdowns, including loop gate resets, scope override adjustments, harness state reinitialization, phase verification workflows, and hook wiring checks.
  • Use case: when you hit a harness error after modifying code or switching branches and Claude is either blocked forever or skipping required enforcement, use this Skill to quickly restore correct harness behavior.

Quick Start

Ask the AI to diagnose your harness issue and recommend the most likely fix based on the symptoms you’re seeing.

Frequently Asked Questions about harness-troubleshoot

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix an infinite stop-hook loop in Claude Code?▼

To fix an infinite stop-hook loop in Claude Code, validate your stop-gate logic and loop counters using a structured decision tree. Resetting the loop gate and reinitializing the harness state restores correct stop-hook enforcement behavior.

Why is my Claude Code harness not firing hooks after switching branches?▼

Your Claude Code harness is not firing hooks due to stale state or hook wiring misconfigurations after a branch switch. Check the hook configuration in .claude/scripts/harness-*.sh and verify the harness state to repair the non-firing hooks.

How do I resolve a scope mismatch error in harness enforcement?▼

Resolve a scope mismatch error in harness enforcement by confirming scope inference and adjusting the scope_override handling. Verifying these settings ensures the harness correctly matches the enforcement scope to your active feature work.

What is the best way to troubleshoot stuck phases in a harness state file?▼

The best way to troubleshoot stuck phases in a harness state file is to run phase verification workflows and repair state updates. Diagnosing the .harness-state.json file identifies incomplete phases and restores harness progress.

Can I use this troubleshooter for harness systems without .claude/commands?▼

No, this troubleshooter applies specifically to existing harness systems using .claude/scripts/harness-*.sh, .claude/commands, and .harness-state.json. It requires these specific files to validate stop-gate logic and repair hook configurations.

Related Skills

Explore More Software Engineering Skills→
Kabilan108Kabilan108
2

Hook Development

Develop Claude Code plugin hooks with structured JSON and scripts to enforce safety and automate workflows.

Community
Advanced
TruCol270TruCol270
1

gsd-pause-work

Capture phase progress, decisions, and blockers into a timestamped handoff file.

Community
Advanced
PolyArchPolyArch
1.4k

humanize-rlcr

Automate Ralph-Loop with Codex Review flow orchestration across branches and commits.

Official
Advanced
monktuimonktui

capability-diagnostic

Diagnose agent failures using a five-step decision tree and output Diagnosis, Root cause, and Fix.

Community
Intermediate