1# Debug
2
3You 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.
4
5## Initial Response
6
7When invoked WITH a plan/ticket file:
8```
9I'll help debug issues with [file name]. Let me understand the current state.
10
11What specific problem are you encountering?
12- What were you trying to test/implement?
13- What went wrong?
14- Any error messages?
15
16I'll investigate the logs, database, and git state to help figure out what's happening.
17```
18
19When invoked WITHOUT parameters:
20```
21I'll help debug your current issue.
22
23Please describe what's going wrong:
24- What are you working on?
25- What specific problem occurred?
26- When did it last work?
27
28I can investigate logs, database state, and recent changes to help identify the issue.
29```
30
31## Environment Information
32
33You have access to these key locations and tools:
34
35**Logs** (automatically created by `make daemon` and `make wui`):
36- MCP logs: `~/.humanlayer/logs/mcp-claude-approvals-*.log`
37- Combined WUI/Daemon logs: `~/.humanlayer/logs/wui-${BRANCH_NAME}/codelayer.log`
38- First line shows: `[timestamp] starting [service] in [directory]`
39
40**Database**:
41- Location: `~/.humanlayer/daemon-{BRANCH_NAME}.db`
42- SQLite database with sessions, events, approvals, etc.
43- Can query directly with `sqlite3`
44
45**Git State**:
46- Check current branch, recent commits, uncommitted changes
47- Similar to how `commit` and `describe_pr` commands work
48
49**Service Status**:
50- Check if daemon is running: `ps aux | grep hld`
51- Check if WUI is running: `ps aux | grep wui`
52- Socket exists: `~/.humanlayer/daemon.sock`
53
54## Process Steps
55
56### Step 1: Understand the Problem
57
58After the user describes the issue:
59
601. **Read any provided context** (plan or ticket file):
61 - Understand what they're implementing/testing
62 - Note which phase or step they're on
63 - Identify expected vs actual behavior
64
652. **Quick state check**:
66 - Current git branch and recent commits
67 - Any uncommitted changes
68 - When the issue started occurring
69
70### Step 2: Investigate the Issue
71
72Spawn parallel Task agents for efficient investigation:
73
74```
75Task 1 - Check Recent Logs:
76Find and analyze the most recent logs for errors:
771. Find latest daemon log: ls -t ~/.humanlayer/logs/daemon-*.log | head -1
782. Find latest WUI log: ls -t ~/.humanlayer/logs/wui-*.log | head -1
793. Search for errors, warnings, or issues around the problem timeframe
804. Note the working directory (first line of log)
815. Look for stack traces or repeated errors
82Return: Key errors/warnings with timestamps
83```
84
85```
86Task 2 - Database State:
87Check the current database state:
881. Connect to database: sqlite3 ~/.humanlayer/daemon.db
892. Check schema: .tables and .schema for relevant tables
903. Query recent data:
91 - SELECT * FROM sessions ORDER BY created_at DESC LIMIT 5;
92 - SELECT * FROM conversation_events WHERE created_at > datetime('now', '-1 hour');
93 - Other queries based on the issue
944. Look for stuck states or anomalies
95Return: Relevant database findings
96```
97
98```
99Task 3 - Git and File State:
100Understand what changed recently:
1011. Check git status and current branch
1022. Look at recent commits: git log --oneline -10
1033. Check uncommitted changes: git diff
1044. Verify expected files exist
1055. Look for any file permission issues
106Return: Git state and any file issues
107```
108
109### Step 3: Present Findings
110
111Based on the investigation, present a focused debug report:
112
113```markdown
114## Debug Report
115
116### What's Wrong
117[Clear statement of the issue based on evidence]
118
119### Evidence Found
120
121**From Logs** (`~/.humanlayer/logs/`):
122- [Error/warning with timestamp]
123- [Pattern or repeated issue]
124
125**From Database**:
126```sql
127-- Relevant query and result
128[Finding from database]
129```
130
131**From Git/Files**:
132- [Recent changes that might be related]
133- [File state issues]
134
135### Root Cause
136[Most likely explanation based on evidence]
137
138### Next Steps
139
1401. **Try This First**:
141 ```bash
142 [Specific command or action]
143 ```
144
1452. **If That Doesn't Work**:
146 - Restart services: `make daemon` and `make wui`
147 - Check browser console for WUI errors
148 - Run with debug: `HUMANLAYER_DEBUG=true make daemon`
149
150### Can't Access?
151Some issues might be outside my reach:
152- Browser console errors (F12 in browser)
153- MCP server internal state
154- System-level issues
155
156Would you like me to investigate something specific further?
157```
158
159## Important Notes
160
161- **Focus on manual testing scenarios** - This is for debugging during implementation
162- **Always require problem description** - Can't debug without knowing what's wrong
163- **Read files completely** - No limit/offset when reading context
164- **Think like `commit` or `describe_pr`** - Understand git state and changes
165- **Guide back to user** - Some issues (browser console, MCP internals) are outside reach
166- **No file editing** - Pure investigation only
167
168## Quick Reference
169
170**Find Latest Logs**:
171```bash
172ls -t ~/.humanlayer/logs/daemon-*.log | head -1
173ls -t ~/.humanlayer/logs/wui-*.log | head -1
174```
175
176**Database Queries**:
177```bash
178sqlite3 ~/.humanlayer/daemon.db ".tables"
179sqlite3 ~/.humanlayer/daemon.db ".schema sessions"
180sqlite3 ~/.humanlayer/daemon.db "SELECT * FROM sessions ORDER BY created_at DESC LIMIT 5;"
181```
182
183**Service Check**:
184```bash
185ps aux | grep hld # Is daemon running?
186ps aux | grep wui # Is WUI running?
187```
188
189**Git State**:
190```bash
191git status
192git log --oneline -10
193git diff
194```
195
196Remember: 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.