Levandor

debug-agents

3 min read

Debug Agent Pipeline

Purpose

A set of 4 specialized Claude Code subagents that transform raw YouTrack tickets or customer complaints into actionable debugging checklists and root cause analyses. Designed for the FaceKom platform.

The Pipeline

graph TD
    Input["YouTrack Ticket / Customer Complaint"]

    subgraph "Step 1 (Parallel)"
        Decoder["Complaint Decoder\n🇭🇺→🇬🇧 + Technical Signal"]
        Triage["Ticket Triage\nSeverity + Checklist"]
    end

    Repro["Reproduction Planner\nStep-by-step plan using\nroom exports & dev env"]
    RCA["RCA Investigator\n5-Whys evidence chain\nSSH + DB + Logs"]
    Output["Fix Proposal + Prevention"]

    Input --> Decoder
    Input --> Triage
    Decoder --> Repro
    Triage --> Repro
    Repro --> RCA
    RCA --> Output

Agent Descriptions

1. Complaint Decoder (complaint-decoder.md)

Input: Raw customer complaint (often in Hungarian) Output: Technical interpretation, affected component, data to request

Key features:

  • Hungarian ↔ English technical glossary (30+ terms)
  • Pattern matching for 10+ common complaint types
  • Generates “data to request” checklist (room ID, logs, exports)

2. Ticket Triage (ticket-triage.md)

Input: Ticket description (decoded or raw) Output: Severity, affected components, debugging checklist

Key features:

  • Symptom-to-component map covering:
    • Video/call issues → WebRTC, Janus, Socket.IO
    • Face recognition → vuer_cv engines, thresholds
    • Document issues → OCR, MRZ, document definitions
    • Self-service → flow engine, SelfServiceV2
    • Export → BackgroundProcess, crawler
    • Auth → Passport strategies, JWT
    • Performance → Redis, session scanning, GPU
    • eSign → signature service, TSA, 2FA
  • P0-P3 severity classification
  • Numbered actionable debugging checklist

3. Reproduction Planner (reproduction-planner.md)

Input: Triaged ticket with initial findings Output: Step-by-step reproduction plan

5 reproduction strategies:

  1. Replay from room export — extract and analyze data_index.json
  2. Re-run CV pipeline — curl commands for all vuer_cv endpoints
  3. Database state reproduction — SQL queries to recreate state
  4. Live session reproduction — manual walkthrough matching export timeline
  5. Customization branch comparison — diff against client’s branch

4. RCA Investigator (rca-investigator.md)

Input: Triage + reproduction findings Output: Root cause with evidence chain, fix, prevention

Key features:

  • 5 Whys × Evidence Chain methodology
  • Investigation tool reference (SSH, supervisorctl, psql, curl, Redis)
  • 6 common root cause patterns:
    1. RabbitMQ connection lost
    2. CV model not loaded
    3. Encryption key mismatch
    4. Flow engine stuck
    5. Export crawler timeout
    6. Customization branch conflict

How to Use

Quick Mode — Single Ticket

# In Claude Code, from the FaceKom project:

# Just spawn the triage agent with the ticket text:
Agent(prompt="""
<Read agents/ticket-triage.md content here>

TICKET: FKITDEV-8427: Face comparison score 0.31 for nusz deployment,
customer photo is clear but system rejects it.
""")

Full Pipeline — Complex Issue

# 1. Decode + Triage in parallel
Agent(name="decoder", prompt="<complaint-decoder.md> TICKET: <text>")
Agent(name="triage", prompt="<ticket-triage.md> TICKET: <text>")

# 2. After both complete, plan reproduction
Agent(name="repro", prompt="<reproduction-planner.md> TRIAGE: <triage output> DECODED: <decoder output>")

# 3. After repro findings, investigate root cause
Agent(name="rca", prompt="<rca-investigator.md> TRIAGE: <triage> REPRO: <repro findings>")

From a Room Export

# If you already have a room export:
Agent(prompt="""
<reproduction-planner.md>

I have room export at /tmp/room-123/
The issue is: face comparison failed during self-service flow.
Client: nusz

Analyze the export and create a reproduction plan.
""")

Agent File Locations

~/.claude/projects/-Users-levander-coding-mnt-Facekom/agents/
├── complaint-decoder.md      # 🇭🇺→🔧 Translation + signal extraction
├── ticket-triage.md          # 🎯 Severity + component + checklist
├── reproduction-planner.md   # 🔬 Step-by-step reproduction
├── rca-investigator.md       # 🔍 Root cause with evidence chain
└── debug-orchestrator.md     # 🎼 Pipeline coordination reference

Graph View

Backlinks