skills/troubleshoot-automation/SKILL.md

---
name: troubleshoot-automation
description: Diagnose why an Apilio automation did not fire, fired at the wrong time, or produced the wrong result. Use when the user reports that a logicblock is misbehaving, or asks what a logicblock actually does.
---

# Troubleshooting an Apilio automation

Read the configuration before theorising. `list_logicblocks` gives names and UUIDs;
`get_logicblock` gives the whole thing — conditions with their comparison details, whether
they trigger re-evaluation, and the current value of the variable each one reads, plus the
condition logic and the actions for both branches.

## Workflow

1. `list_logicblocks` → find the logicblock the user means, take its UUID.
2. `get_logicblock` → the full configuration. Work through the checks below.
3. `list_log_entries` with `parent_type: "logicblock"` and `parent_uuid` → what actually
   happened, including the linked actions.
4. `get_variable` on a condition's `variable_uuid` when you need more than its current value
   — in particular when it last changed.
5. Report the cause and propose a fix. Make changes only after the user agrees.

## What to check, in order

**Is it active?** `active: false` does not stop the logicblock from evaluating — it stops it
from running any actions. So the symptom is "the logs show it evaluated but nothing
happened". The most common cause by far.

**Which condition is false?** Each condition carries `variable_value` — the current value of
the variable it reads — plus its `comparison`. Work the comparison out yourself: a numeric
condition with `variable_value: "18"` and `comparison: {operator: "greaterthan", constant:
"25"}` is false. With `condition_logic: "and"` a single false condition blocks everything;
with `condition_logic: "complex"`, read `condition_expression` — the names in it are the
condition names — and evaluate it against what you worked out.

Apilio does not persist a per-condition result, so there is no stored true/false to read
back. A `variable_value` of `null` means that variable has never received a value, which is
itself usually the answer.

Time conditions have no variable. Read `cron_expression`, `duration_seconds` and `timezone` and
reason about the schedule directly.

**Is anything triggering it?** There are two automatic paths, and a condition may use
either:

- `triggering: true` — re-evaluate when this condition's **result** flips.
- `trigger_on_content_update: true` — re-evaluate on every **value update**, even when the
  result is unchanged and even when `triggering` is false.

So check both fields on every condition before concluding nothing drives the automation. If
the event the user describes belongs to a condition with both set to false, that event never
starts it. If no condition sets either, it only ever runs when something
else evaluates it explicitly — an `apilio` action of type `logicblock_evaluate` in another
logicblock, a webhook, or a manual run. "It only works when I press the button" is this.

**Is a timing guard suppressing it?** Each condition's `timing` holds `modified_within`
(the value must have been updated within N seconds — a stale sensor makes this false) and
`unmodified_since` (the value must have been stable for N seconds — a flapping sensor makes
this false).

**Did the right branch run?** Actions are split into `positive` and `negative`. An
automation that "does nothing" often has its action on the branch that isn't being reached.

**Was the action delayed?** Each action has a `delay` of `{type: "fixed", seconds: N}` or
`{type: "random", min_seconds:, max_seconds:}`. A long delay looks like a failure.

**Did the action itself fail?** The log entries carry the failure reason. `api_error` and
`connection_error` on a Tado or eWeLink action usually mean the account connection is
broken and needs reconnecting in the Apilio web app.

## Evaluating on purpose

`evaluate_logicblock` runs the logicblock **and fires its actions** — it will switch real
devices (unless the logicblock is inactive, in which case it evaluates but runs nothing).
Ask the user before calling it, and prefer working from `variable_value`,
`last_evaluation_result` and the log entries first.