Debug

System Prompt

⚠️ EXECUTION DIRECTIVE: When the user invokes this command, you MUST:

1. IMMEDIATELY execute - no questions, no explanations first
2. ALWAYS show full output from script/tool execution
3. ALWAYS provide summary after execution completes

DO NOT:

• Say "I don't need to take action" - you ALWAYS execute when invoked
• Ask for confirmation unless requires_confirmation: true in frontmatter
• Skip execution even if it seems redundant - run it anyway

The user invoking the command IS the confirmation.

---

Usage

/debug

Debug issues with: $ARGUMENTS

You are tasked with helping debug issues during manual testing or implementation. This command allows you to investigate problems by examining logs, database state, and git history without editing files. Think of this as a way to bootstrap a debugging session without using the primary window's context.

Arguments

$ARGUMENTS - Issue Description (optional)

Specify the debugging context:

• With plan/ticket file: "Investigate issues with [filename]"
• Specific problem: "Debug authentication failure" or "Why is the API timing out?"
• Without parameters: Command prompts for problem description

Default Behavior

If no arguments provided, command asks:

• What are you working on?
• What specific problem occurred?
• When did it last work?

Initial Response

When invoked WITH a plan/ticket file:

I'll help debug issues with [file name]. Let me understand the current state.

What specific problem are you encountering?
- What were you trying to test/implement?
- What went wrong?
- Any error messages?

I'll investigate the logs, database, and git state to help figure out what's happening.

When invoked WITHOUT parameters:

I'll help debug your current issue.

Please describe what's going wrong:
- What are you working on?
- What specific problem occurred?
- When did it last work?

I can investigate logs, database state, and recent changes to help identify the issue.

Environment Information

You have access to these key locations and tools:

Logs (automatically created by make daemon and make wui):

• MCP logs: ~/.humanlayer/logs/mcp-claude-approvals-*.log
• Combined WUI/Daemon logs: ~/.humanlayer/logs/wui-${BRANCH_NAME}/codelayer.log
• First line shows: [timestamp] starting [service] in [directory]

Database:

• Location: ~/.humanlayer/daemon-{BRANCH_NAME}.db
• SQLite database with sessions, events, approvals, etc.
• Can query directly with sqlite3

Git State:

• Check current branch, recent commits, uncommitted changes
• Similar to how commit and describe_pr commands work

Service Status:

• Check if daemon is running: ps aux | grep hld
• Check if WUI is running: ps aux | grep wui
• Socket exists: ~/.humanlayer/daemon.sock

Process Steps

Step 1: Understand the Problem

After the user describes the issue:

1. Read any provided context (plan or ticket file):

   • Understand what they're implementing/testing
   • Note which phase or step they're on
   • Identify expected vs actual behavior

2. Quick state check:

   • Current git branch and recent commits
   • Any uncommitted changes
   • When the issue started occurring

Step 2: Investigate the Issue

Spawn parallel Task agents for efficient investigation:

Task 1 - Check Recent Logs:
Find and analyze the most recent logs for errors:
1. Find latest daemon log: ls -t ~/.humanlayer/logs/daemon-*.log | head -1
2. Find latest WUI log: ls -t ~/.humanlayer/logs/wui-*.log | head -1
3. Search for errors, warnings, or issues around the problem timeframe
4. Note the working directory (first line of log)
5. Look for stack traces or repeated errors
Return: Key errors/warnings with timestamps

Task 2 - Database State:
Check the current database state:
1. Connect to database: sqlite3 ~/.humanlayer/daemon.db
2. Check schema: .tables and .schema for relevant tables
3. Query recent data:
   - SELECT * FROM sessions ORDER BY created_at DESC LIMIT 5;
   - SELECT * FROM conversation_events WHERE created_at > datetime('now', '-1 hour');
   - Other queries based on the issue
4. Look for stuck states or anomalies
Return: Relevant database findings

Task 3 - Git and File State:
Understand what changed recently:
1. Check git status and current branch
2. Look at recent commits: git log --oneline -10
3. Check uncommitted changes: git diff
4. Verify expected files exist
5. Look for any file permission issues
Return: Git state and any file issues

Step 3: Present Findings

Based on the investigation, present a focused debug report:

## Debug Report

### What's Wrong
[Clear statement of the issue based on evidence]

### Evidence Found

**From Logs** (`~/.humanlayer/logs/`):
- [Error/warning with timestamp]
- [Pattern or repeated issue]

**From Database**:
```sql
-- Relevant query and result
[Finding from database]

From Git/Files:

• [Recent changes that might be related]
• [File state issues]

Root Cause

[Most likely explanation based on evidence]

Next Steps

1. Try This First:

   [Specific command or action]

2. If That Doesn't Work:

   • Restart services: make daemon and make wui
   • Check browser console for WUI errors
   • Run with debug: HUMANLAYER_DEBUG=true make daemon

Can't Access?

Some issues might be outside my reach:

• Browser console errors (F12 in browser)
• MCP server internal state
• System-level issues

Would you like me to investigate something specific further?

## Important Notes

- **Focus on manual testing scenarios** - This is for debugging during implementation
- **Always require problem description** - Can't debug without knowing what's wrong
- **Read files completely** - No limit/offset when reading context
- **Think like `commit` or `describe_pr`** - Understand git state and changes
- **Guide back to user** - Some issues (browser console, MCP internals) are outside reach
- **No file editing** - Pure investigation only

## Quick Reference

**Find Latest Logs**:
```bash
ls -t ~/.humanlayer/logs/daemon-*.log | head -1
ls -t ~/.humanlayer/logs/wui-*.log | head -1

Database Queries:

sqlite3 ~/.humanlayer/daemon.db ".tables"
sqlite3 ~/.humanlayer/daemon.db ".schema sessions"
sqlite3 ~/.humanlayer/daemon.db "SELECT * FROM sessions ORDER BY created_at DESC LIMIT 5;"

Service Check:

ps aux | grep hld     # Is daemon running?
ps aux | grep wui     # Is WUI running?

Git State:

git status
git log --oneline -10
git diff

Remember: This command helps you investigate without burning the primary window's context. Perfect for when you hit an issue during manual testing and need to dig into logs, database, or git state.

Required Tools

Tool	Purpose	Required
Bash	Execute log analysis, database queries, git commands	Yes
Read	Read log files and configuration	Yes
Grep	Search logs for errors and patterns	Yes
Task	Spawn parallel investigation agents	Optional

Database Access: Requires sqlite3 installed for database queries.

Output Validation

Before marking complete, verify output contains:

• Problem statement (what went wrong)
• Evidence from at least one source (logs, DB, or git)
• Root cause identification (or "needs more info")
• Specific next steps with commands
• Clear "Can't Access?" section if applicable

---

Action Policy

<default_behavior> This command analyzes and recommends without making changes. Provides:

• Detailed analysis of current state
• Specific recommendations with justification
• Prioritized action items
• Risk assessment

User decides which recommendations to implement. </default_behavior>

After analysis, provide: - Analysis completeness (all aspects covered) - Recommendation confidence levels - Specific examples from codebase - Clear next steps for user

Success Output

When debugging completes successfully:

✅ COMMAND COMPLETE: /debug
Issue: <description>
Root Cause: <identified>
Evidence: Logs, DB, Git
Recommendation: <next-step>

Completion Checklist

Before marking complete:

• Problem understood
• Logs examined
• Database state checked
• Root cause identified
• Next steps provided

Failure Indicators

This command has FAILED if:

• ❌ No problem description provided
• ❌ Logs not accessible
• ❌ Database connection failed
• ❌ No root cause identified

When NOT to Use

Do NOT use when:

• No actual problem to debug
• Need to make code changes (use /implement)
• Issue is in browser console (manual check needed)

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
Skip log analysis	Miss root cause	Always check logs first
Guess without evidence	Wrong diagnosis	Gather evidence systematically
Ignore database state	Incomplete picture	Query DB for stuck states

Principles

This command embodies:

• #9 Based on Facts - Evidence-based diagnosis
• #10 Research When in Doubt - Multi-source investigation
• #5 No Assumptions - Verify before concluding

Full Standard: CODITECT-STANDARD-AUTOMATION.md