Skip to content

Troubleshooting

Jump to bottom
Josemalyson Oliveira edited this page Jun 27, 2026 · 1 revision

Troubleshooting

Common issues and solutions.

Installation Issues

Issue: ./setup: Permission denied

Solution:

chmod +x setup
./setup

Issue: Command not found: /hes

Solution:

HES is not a CLI tool. It's a skill-based system that works within your AI coding assistant. Use:

/hes status

in your AI assistant, not in the terminal.

Issue: Skill not found

Solution:

Ensure the skill files are in the correct location:

# For Claude Code
ls ~/.claude/skills/hes/

# For Cursor
ls ~/.cursor/skills/hes/

Phase Issues

Issue: Cannot advance to next phase

Solution:

Check the gate conditions:

/hes status

The output will show what's missing.

Issue: Phase gate not satisfied

Solution:

Complete the required artifacts for the current phase. For example, in DISCOVERY:

  1. Create docs/discovery.md
  2. Document business rules
  3. Get user approval

Issue: Step budget exceeded

Solution:

The agent has taken too many actions. Options:

  1. Complete the current task manually
  2. Use /hes skip --reason "budget exceeded"
  3. Start a new session with /hes session --restore

State Issues

Issue: No current.json found

Solution:

Bootstrap the project:

/hes start

Issue: Orphan state detected

Solution:

Recovery options:

  1. Restore from checkpoint: /hes session --restore
  2. Start fresh: /hes uninstall then /hes install

Issue: State file corrupted

Solution:

  1. Check .hes/state/current.json
  2. Restore from backup or checkpoint
  3. If needed, reinstall: /hes uninstall then /hes install

Security Issues

Issue: Security gate failed

Solution:

  1. Review the security findings
  2. Fix critical/high issues
  3. Run security scan again: /hes security

Issue: False positive in security scan

Solution:

  1. Document the false positive
  2. Skip with justification: /hes skip --reason "false positive: ..."

Performance Issues

Issue: Agent is slow

Solution:

  1. Check step budget usage
  2. Reduce context size
  3. Use /hes session --save and start fresh

Issue: Context too large

Solution:

  1. Offload large outputs to files
  2. Start a new session
  3. Use /hes session --restore

Git Issues

Issue: Cannot commit during SECURITY phase

Solution:

This is expected. Complete the SECURITY phase first, then commit.

Issue: Merge conflict during phase transition

Solution:

  1. Resolve the conflict manually
  2. Update the state file if needed
  3. Resume with /hes status

Agent Issues

Issue: Agent not responding

Solution:

  1. Check if the AI assistant is running
  2. Restart the session
  3. Try a different command

Issue: Wrong skill loaded

Solution:

  1. Check the current phase: /hes status
  2. Manually load the correct skill: /hes <phase>

Getting Help

If you encounter an issue not listed here:

  1. Check the FAQ
  2. Search GitHub Issues
  3. Open a new issue with:
    • Description of the problem
    • Steps to reproduce
    • .hes/state/current.json contents
    • System information

Last updated: June 2026

Clone this wiki locally