debug
/debug
Debug errors, bugs, and unexpected behavior systematically in Home Assistant integration. Use when investigating errors, analyzing stack traces, fixing bugs, or troubleshooting unexpected behavior.
- Author
- Thank-you-Linus ↗
- Repository
- Linus-Dashboard ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Debug errors, bugs, and unexpected behavior systematically in Home Assistant integration. Use when investigating errors, analyzing stack traces, fixing bugs, or troubleshooting unexpected behavior.
Original author description
Debug errors, bugs, and unexpected behavior systematically in Home Assistant integration. Use when investigating errors, analyzing stack traces, fixing bugs, or troubleshooting unexpected behavior.
How it works
- Context Loading
- Debug Process
- Common Issues and Solutions
- Debug Tools
- Checklist
SKILL.md preview
---
name: debug
description: Debug errors, bugs, and unexpected behavior systematically in Home Assistant integration. Use when investigating errors, analyzing stack traces, fixing bugs, or troubleshooting unexpected behavior.
---
# Debug Errors and Bugs Systematically
Debug errors, bugs, and unexpected behavior in the Linus Dashboard Home Assistant integration.
---
## Context Loading
Before debugging, load:
1. [.aidriven/memorybank.md](.aidriven/memorybank.md) - Project architecture
2. [.aidriven/rules/clean_code.md](.aidriven/rules/clean_code.md) - Code standards
3. [.aidriven/rules/homeassistant_integration.md](.aidriven/rules/homeassistant_integration.md) - HA patterns
4. [.aidriven/rules/async_patterns.md](.aidriven/rules/async_patterns.md) - Async best practices
---
## Debug Process
### Step 1: Understand the Error
**Collect Information:**
- Error message (full stack trace)
- When does it occur? (startup, service call, state change)
- Which file/function is involved?
- User actions that trigger it
- Home Assistant version and logs
**Questions to Ask:**
1. Is this a Python exception or HA-specific error?
2. Does the error occur consistently or randomly?
3. Are there related errors in `home-assistant.log`?
4. What changed recently (code, config, HA version)?
### Step 2: Analyze Root Cause
**Common Error Categories:**
#### 1. Async/Await Issues
```python
# Symptoms:
# - "coroutine was never awaited"
# - Event loop blocking
# - Timeouts
# Check for:
await missing_function() # Missing await
blocking_io_call() # Blocking I/O in async context
```
#### 2. Home Assistant Integration Errors
```python
# Symptoms:
# - Integration fails to load
# - Config flow errors
# - Entity not showing up
# Check for:
# - Missing async_setup_entry/async_unload_entry
# - Incorrect platform registration
# - Missing unique_id on entities
# - Data not stored in hass.data correctly
```
#### 3. API/Network Errors
```python
# Symptoms:
# - Connection refused
# - Timeouts
# - 4xx/5xx HTTP errors
# Check for:
# - Supabase URL/key configuration
# - Network connectivity
# - API rate limits
# - Timeout values
```
### Step 3: Investigate
**Review Code:**
- Read the file where error occurs
- Trace the execution path
- Check function signatures
- Review recent changes with `git log`
**Check Logs:**
```bash
# Home Assistant logs
tail -f /config/home-assistant.log | grep linus
# Check for warnings
grep -i "warning.*linus" /config/home-assistant.log
```
**Add Debug Logging:**
```python
import logging
_LOGGER = logging.getLogger(__name__)
_LOGGER.debug("Variable value: %s", variable)
_LOGGER.info("Entering function with args: %s", args)
```
### Step 4: Fix the Issue
**Apply Fix:**
- Make minimal changes to fix root cause
- Follow code standards from [.aidriven/rules/clean_code.md](.aidriven/rules/clean_code.md)
- Add error handling if missing
- Update documentation if behavior changed
**Test the Fix:**
1. Restart Home Assistant
2. Reproduce the original error scenario
3. Verify error is gone
4. Check logs for new errors
5. Test related functionality
### Step 5: Verify and Document
**Verification:**
- [ ] Error no longer occurs
- [ ] No new errors introduced
- [ ] Related features still work
- [ ] Logs are clean
**Documentation:**
- Update inline comments if needed
- Note the fix in commit message
- Update CHANGELOG if user-facing
---
## Common Issues and Solutions
### Issue: "coroutine was never awaited"
**Solution:** Add `await` before async function calls
```python
# Before
result = async_function()
# After
result = await async_function()
```
### Issue: Integration doesn't load
**Solution:** Check entry setup and platform registration
```python
# Ensure proper setup
async def async_setup_entry(hass, entry):
await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
return True
```
### Issue: Entity not updating
**Solution:** Verify state updates and coordinator refresh
```python
# Ensure coordinator updates
await self.coordinator.async_request_refresh()
```
### Issue: Timeout errors
**Solution:** Increase timeout or optimize slow operations
```python
# Add proper timeout
async with timeout(30):
result = await slow_operation()
```
---
## Debug Tools
**Home Assistant Developer Tools:**
- Services tab - Test service calls
- States tab - Check entity states
- Events tab - Monitor events
- Template tab - Test templates
**Python Debugging:**
```python
# Add breakpoint (if debugging locally)
import pdb; pdb.set_trace()
# Add detailed logging
_LOGGER.debug("State: %s, Attrs: %s", self.state, self.extra_state_attributes)
```
**Git Tools:**
```bash
# Find when bug was introduced
git log --oneline -- path/to/file.py
# Check recent changes
git diff HEAD~5 -- path/to/file.py
```
---
## Checklist
Before completing debug:
- [ ] Root cause identified
- [ ] Fix implemented following code standards
- [ ] Error no longer reproduces
- [ ] Related functionality tested
- [ ] Logs reviewed for new issues
- [ ] Changes documented
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Thank-you-Linus/Linus-Dashboard | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| nicsuzor/academicops | 100 | MIT |
| duronext/jig | 100 | MIT |
| drosam/agents | 100 | MIT |
| rizukirr/vibekit | 100 | MIT |
| DingyangLyu/MatClaw | 100 | Apache-2.0 |
| Kanevry/session-orchestrator | 100 | MIT |
| kdlbs/kandev | 100 | AGPL-3.0 |
Database snapshot: 13.11.2026 · package version 278842d6a10a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90vc:debug
Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation. - 90vc:debug
Debug systematically with root-cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, CI failures, or system investigation. - 100debugging
Systematically diagnose and fix software bugs by analyzing error messages, stack traces, logs, and runtime behavior across multiple languages. Use when the user requests debugging or provides relevant inputs for this workflow. - 90dev-debug
Systematically debug software failures before proposing fixes. Use for test failures, runtime errors, build failures, flaky behavior, performance regressions, integration failures, logs, screenshots, or any unexpected technical behavior where root cause must be established from evidence. - 100debug-root-cause
Systematically find and fix the root cause of bugs, errors, failing tests, and crashes in JavaScript/TypeScript and Python. Use whenever the user pastes an error or stack trace, says something is broken, "not working", "error", "kenapa gagal", "bug", a test fails, or behavior is… - 100systematic-debug
Four-phase debugging framework that finds root causes before attempting fixes. Use when investigating errors, debugging failures, fixing bugs, analyzing test failures, diagnosing unexpected behavior, examining stack traces, or when the user says "it's broken", "this doesn't…