Hypergraph-Coding-Agent-Framework: Skill for Claude Code

Troubleshooting

This skill helps diagnose and recover from common failure states in the Hypergraph Coding Agent Framework. Since LLMs are probabilistic engines, they can occasionally fail even with rigid constraints.

When to use this skill

• When the user reports an agent is writing code for rejected features.
• When the /hyper-audit agent fails or /hyper-redteam hallucinates the Blast Radius.
• When the Red Team report suggests new product features instead of vulnerabilities.
• When architecture.yml throws a ParserError or gets corrupted.
• When the Architect Agent asks the same questions repeatedly and won't generate a PRD.
• When the user explicitly runs /hyper-troubleshooting.

How to use it

Step 1: Identify the Symptom

Use AskUserQuestion to identify the symptom:

What symptom are you seeing?

- Option A: Context Bloat / Hallucination — Builder is writing code for rejected features
- Option B: Hypergraph Desync — /hyper-audit or /hyper-redteam fails or has wrong blast radius
- Option C: YAML Corruption or Infinite Loop Interview — architecture.yml parse error, or Architect repeatedly asks the same questions
- Option D: Red Team Scope Creep — Red Team report suggests product features instead of vulnerabilities

If the user selects Option C, ask a brief follow-up to confirm whether it is the YAML corruption or the infinite loop interview before applying the fix.

Step 2: Provide Diagnosis and Fix

Issue 1: Context Bloat & Hallucination

Cause: The agent's context window is polluted with old data. Active specs were not archived. Fix:

1. Halt the Builder Agent.
2. Ensure .agentignore contains spec/archive/.
3. Run python .agents/scripts/archive_specs.py cleanup.
4. Open a completely new agent chat and restart the Builder prompt pointing strictly to the compiled MiniPRD.

Issue 2: Hypergraph Desynchronization

Cause: The Builder forgot or failed to execute hypergraph_updater.py, so architecture.yml is unaware of codebase changes. Fix:

1. Look at the modified files and identify their node_ids in architecture.yml.
2. Manually execute: python .agents/scripts/hypergraph_updater.py spec/compiled/architecture.yml [node_id_1] [node_id_2]
3. Re-run /hyper-audit to perform the semantic update.