Troubleshooting Guide

Category: Reference | Updated: 2026-02-02

Common issues, solutions, and debugging techniques for Triqual.

---

Quick Fixes

---

MCP Connection Issues

Issue: MCP Servers Not Connected

Symptom:

/mcp
# Shows: No MCP servers connected

Diagnosis:

1. Check .mcp.json exists:

ls triqual-plugin/.mcp.json

1. Verify MCP configuration:

cat triqual-plugin/.mcp.json

Should show:

{
  "servers": {
    "quoth": {
      "url": "https://quoth.ai-innovation.site/api/mcp",
      "transport": "sse"
    },
    "exolar-qa": {
      "url": "https://exolar.ai-innovation.site/api/mcp/mcp",
      "transport": "sse"
    }
  }
}

Solutions:

1. Restart Claude Code:

# Exit and restart
claude

1. Re-authenticate MCP servers:

• Visit URLs and authorize
• Quoth: https://quoth.ai-innovation.site/api/mcp
• Exolar: https://exolar.ai-innovation.site/api/mcp/mcp

1. Check plugin installation:

/plugin list
# Should show: triqual-plugin@triqual

Issue: Quoth Search Fails

Symptom:

❌ Error: Quoth search failed - unauthorized

Solution:

1. Re-authenticate:

# Visit Quoth OAuth
open https://quoth.ai-innovation.site/api/mcp

1. Verify connection:

/mcp
# Should show: quoth (connected)

1. Test search:

# Try a simple search
quoth_search_index({ query: "login patterns" })

Issue: Exolar Query Fails

Symptom:

❌ Error: Exolar query failed - unauthorized

Solution:

1. Re-authenticate:

# Visit Exolar OAuth
open https://exolar.ai-innovation.site/api/mcp/mcp

1. Verify project ID:

// triqual.config.ts
export default defineConfig({
  mcp: {
    exolar: {
      enabled: true,
      projectId: 'correct-project-id', // Check this
    },
  },
});

1. Test query:

query_exolar_data({
  dataset: "test_search",
  filters: { search: "login" }
})

---

Hook Issues

Issue: Hooks Not Triggering

Symptom: Can write tests to tests/ directly (should be blocked)

Diagnosis:

1. Check hooks.json syntax:

cat triqual-plugin/hooks/hooks.json | jq

Should show valid JSON, no errors.

1. Verify scripts executable:

ls -l triqual-plugin/hooks/*.sh
# Should show: -rwxr-xr-x (executable)

Solutions:

1. Make scripts executable:

chmod +x triqual-plugin/hooks/*.sh

1. Test hook manually:

echo '{"tool":"Write","parameters":{"file_path":"tests/new.spec.ts"}}' | \
  triqual-plugin/hooks/pre-spec-write.sh

echo $? # Should be 2 (blocked)

1. Enable debug mode:

export TRIQUAL_DEBUG=true

Issue: Hook Blocks Incorrectly

Symptom: Hook blocks action that should be allowed

Diagnosis:

Enable debug mode to see hook logic:

export TRIQUAL_DEBUG=true

Example output:

[DEBUG] pre-spec-write: Checking file path
[DEBUG] File: tests/login.spec.ts
[DEBUG] File already exists: YES
[DEBUG] Allow overwrite: YES
[DEBUG] Exit code: 0 (allow)

Solutions:

1. Check run log exists:

ls .triqual/runs/login.md

1. Verify run log has required stages:

cat .triqual/runs/login.md | grep "Stage:"

Should show:

### Stage: ANALYZE
### Stage: RESEARCH
### Stage: PLAN
### Stage: WRITE

1. Check context files exist:

ls .triqual/context/login/

Should show:

patterns.md
anti-patterns.md
codebase.md
existing-tests.md
failures.md
requirements.md
summary.md

Issue: Hook Exit Code Always 0

Symptom: Hooks never block

Check hook script logic:

# pre-spec-write.sh
if [[ "$file_path" != *".draft/"* ]] && ! file_exists; then
  echo "🚫 BLOCKED: Write to .draft/ instead" >&2
  exit 2  # Should exit 2 to block
fi

Verify:

• exit 2 present (not exit 0 or exit 1)
• Condition logic correct
• >&2 used for stderr

---

Session State Issues

Issue: Session State Stale

Symptom:

• Old hints showing again
• Tool counts incorrect
• Test run tracking wrong

Solution:

# Delete session state
rm -rf ~/.cache/triqual/

# Restart Claude Code
claude

Effect: Fresh session state created

Issue: File Locking Error

Symptom:

❌ Error: Failed to acquire lock on session state

Diagnosis:

Check for stale lock file:

ls ~/.cache/triqual/.lock

Solutions:

1. Remove stale lock:

rm ~/.cache/triqual/.lock

1. Kill hung processes:

# Find processes holding lock
lsof ~/.cache/triqual/.lock

# Kill if necessary
kill <PID>

1. Wait and retry:

# Wait 5 seconds for lock release
sleep 5
# Retry operation

---

Run Log Issues

Issue: Run Logs Not Found

Symptom:

❌ Error: No run log found for "login"

Diagnosis:

# Check directory exists
ls -la .triqual/runs/

Solutions:

1. Create directory:

mkdir -p .triqual/runs/

1. Run /init:

/init

1. Create run log manually:

cat > .triqual/runs/login.md <<'EOF'
# Test Run Log: login

## Session: $(date -Iseconds)

### Stage: ANALYZE
(To be filled)

### Stage: RESEARCH
(To be filled)

### Stage: PLAN
(To be filled)
EOF

Issue: Run Log Missing Stages

Symptom:

🚫 BLOCKED: Missing RESEARCH stage in run log

Solution:

Edit run log to add missing stage:

# Edit run log
cat >> .triqual/runs/login.md <<'EOF'

### Stage: RESEARCH

**Quoth Patterns:**
(To be filled)

**Exolar History:**
(To be filled)

**Existing Code:**
(To be filled)
EOF

---

Agent Issues

Issue: Agent Not Dispatching

Symptom: /test login doesn't start test-planner

Diagnosis:

1. Check agent definition:

ls triqual-plugin/agents/test-planner.md

1. Verify frontmatter:

head -n 10 triqual-plugin/agents/test-planner.md

Should show:

---
model: opus
color: purple
tools:
  - Read
  - Write
---

Solutions:

1. Verify plugin loaded:

/plugin list

1. Check agent accessible:

cat triqual-plugin/agents/test-planner.md

1. Restart Claude Code:

claude

Issue: Agent Loops Infinitely

Symptom: test-healer runs 100+ times, doesn't stop

Diagnosis:

Check run log for attempt count:

grep "Stage: RUN" .triqual/runs/login.md | wc -l

Solutions:

1. Check retry gate hook:

cat triqual-plugin/hooks/pre-retry-gate.sh

Should block at 25 attempts.

1. Manually stop agent:

# Stop current operation (Ctrl+C in terminal)
# Or kill process

1. Mark test as .fixme():

// .draft/tests/login.spec.ts
test.fixme('login flow', async ({ page }) => {
  // Test code
});

---

Test Generation Issues

Issue: Tests Created in Wrong Location

Symptom: Test created at tests/login.spec.ts instead of .draft/tests/login.spec.ts

Diagnosis:

Check pre-spec-write hook:

cat triqual-plugin/hooks/pre-spec-write.sh | grep -A 5 "draft"

Solutions:

1. Move to draft:

mkdir -p .draft/tests/
mv tests/login.spec.ts .draft/tests/

1. Fix hook:

# Ensure hook blocks non-draft writes
# Check exit code 2 present

Issue: Page Objects Not Reused

Symptom: New Page Object created when existing one covers the need

Diagnosis:

Check context files:

cat .triqual/context/login/existing-tests.md

Should list existing Page Objects.

Solutions:

1. Regenerate context:

triqual_load_context({ feature: "login", force: true })

1. Manually verify existing code:

ls pages/
grep -r "LoginPage" pages/

1. Update run log RESEARCH stage:

### Stage: RESEARCH

**Existing Code to Reuse:**
- `pages/LoginPage.ts` ✅

---

Performance Issues

Issue: Context Loading Slow

Symptom: triqual_load_context takes 2+ minutes

Diagnosis:

Large codebase or many Quoth patterns.

Solutions:

1. Use cached context:

# Don't force reload
triqual_load_context({ feature: "login", force: false })

1. Narrow search scope:

// Only search specific patterns
quoth_search_index({ query: "login auth patterns" })

1. Reduce Exolar query range:

query_exolar_data({
  dataset: "test_history",
  filters: { days: 7 } // Last 7 days only
})

Issue: Test Healing Slow

Symptom: test-healer takes 30+ minutes

Diagnosis:

Many test attempts, slow test execution.

Solutions:

1. Run tests in headed mode locally:

npx playwright test --headed .draft/tests/login.spec.ts
# Manually observe failures

1. Add debug logging:

test('login', async ({ page }) => {
  console.log('Starting login test');
  // ... test code
  console.log('Login complete');
});

1. Use .only for faster iteration:

test.only('login', async ({ page }) => {
  // Focus on this test only
});

---

Debug Mode

Enable Debug Logging

export TRIQUAL_DEBUG=true

Debug Output

Hooks:

[DEBUG] SessionStart: Initializing session
[DEBUG] Session state: ~/.cache/triqual/session-state.json
[DEBUG] Active run logs: 2 found

MCP Tools:

[DEBUG] triqual_load_context: Starting subprocess
[DEBUG] Quoth search: "login patterns" (5 results)
[DEBUG] Exolar query: test_history (12 results)
[DEBUG] Context files written: 7 files

Agents:

[DEBUG] test-planner: Reading context files
[DEBUG] test-planner: Creating run log
[DEBUG] test-generator: Reading PLAN stage
[DEBUG] test-healer: Attempt 1 - FAIL (WAIT)
[DEBUG] test-healer: Attempt 2 - PASS

Disable Debug Mode

unset TRIQUAL_DEBUG

---

Getting Help

/help Command

# General help
/help

# Topic-specific
/help installation
/help workflow
/help debugging

Check Documentation

• Installation
• Skills Reference
• Learning Loop
• Hooks System
• Agents Guide

Report Issues

GitHub: https://github.com/Montinou/triqual/issues

Include:

• Triqual version
• Claude Code version
• Error messages
• Debug logs (TRIQUAL_DEBUG=true)
• Steps to reproduce

---

Related Documentation

• Installation - Setup verification
• Hooks System - Hook debugging
• Session State - State management
• API Reference - MCP tool signatures

---

Next Steps: If issue persists, enable debug mode and report with logs. Check Installation for setup verification.