Skip to content
Skills Library
Programming · Analysis

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.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

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

  1. Context Loading
  2. Debug Process
  3. Common Issues and Solutions
  4. Debug Tools
  5. Checklist
Original SKILL.md headings · 210 lines, 683 words
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

RepositoryScoreLicence
This page · Thank-you-Linus/Linus-Dashboard100MIT
ericrisco/rsc-harness100MIT
nicsuzor/academicops100MIT
duronext/jig100MIT
drosam/agents100MIT
rizukirr/vibekit100MIT
DingyangLyu/MatClaw100Apache-2.0
Kanevry/session-orchestrator100MIT
kdlbs/kandev100AGPL-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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.