Acp Live Diagnose

ACP Live Diagnose

Turn "my cover is doing something wrong right now" into a filed, root-caused GitHub issue.

The three ACP diagnosis skills differ only in where the evidence comes from:

The distinguishing value here is that the install is live: the recorder can be queried, the code is checked out locally, and the mechanism can be proven by execution rather than argued from reading. Do not skip that proof.

Step 0 — Session Startup

git status && git log --oneline -5

Recent commits often name work in the same subsystem, which is exactly the context that turns "this looks wrong" into "this regressed in #NNNN." When a symptom looks like a known trap rather than a new defect, HANDOFF.md is worth a read — it carries the unfiled gotchas and the "not hotfixable to main" table, and nothing else.

Step 1 — Resolve the Target

Each ACP cover is its own config entry. Match on the title the user used:

ha_get_integration(query="<cover name fragment>")

Zero matches → widen with ha_get_integration(query="adaptive") and show the list. Multiple matches → ask which one; do not guess.

Record the entry_id and, from entry.options, the config that bears on the symptom. Options are the reporter's actual configuration — read them before forming any hypothesis. Watch for keys stored as null that fall back to a DEFAULT_* constant (custom_position_priority_N → DEFAULT_CUSTOM_POSITION_PRIORITY); the effective value is what matters, and it is not in the dump.

Step 2 — Pull Live Diagnostics

ha_get_integration(entry_id=..., include_diagnostics=True,
                   diagnostics_data_path="data.diagnostics",
                   diagnostics_truncate_at_bytes=1200)

That returns available_fields — the section list. Drill in one section at a time:

ha_get_integration(entry_id=..., include_diagnostics=True,
                   diagnostics_data_path="data.diagnostics.<section>",
                   diagnostics_fields=["data"])

⚠️ Always pass diagnostics_fields=["data"] on drill-in calls. Without it every response re-echoes the entire entry.options blob, which is several hundred tokens per call and adds nothing after Step 1.

Sections that carry the most signal, roughly in order:

• decision_trace — the pipeline chain with each handler's match/reason/priority. The starting point for almost every symptom.
• event_timeline — chronological pipeline_evaluated / cover_command_sent / cover_command_skipped records. Paginated, ~250 entries, and the interesting part is nearly always the tail. Probe diagnostics_data_limit=25, diagnostics_data_offset=0 to learn total, then jump to offset=total-30.
• manual_override_history / manual_override_state — engage/reject/reset records with the threshold reasoning.
• cover_commands — per-entity target_call, wait_for_target, retry_count, gave_up.
• last_cover_action, last_skipped_action — the most recent dispatch and the most recent suppression.
• meta — integration_version, cover_type. Always capture; the issue needs it and a develop/alpha build changes what "latest" means.

Diagnostics timestamps are UTC. The HA MCP converts recorder timestamps to the install's local zone. Never compare the two without converting, and state which zone any timestamp in the issue is in.

Step 3 — Corroborate Against the Recorder

Diagnostics say what ACP believed. The recorder says what the hardware did. A root cause is not established until both agree.

ha_get_history(entity_ids="cover.<target>",
               start_time="<UTC iso>", end_time="<UTC iso>",
               minimal_response=False, order="asc")

Bracket the window around the timestamps found in Step 2, plus a few minutes either side. minimal_response=False is required — current_position lives in the attributes.

This step routinely rewrites the hypothesis. It is what distinguishes "ACP computed 40" from "ACP drove the cover from 0 back to 40 thirteen seconds after the user closed it," and only the second is a bug report.

Where relevant, also pull the states of the entities that gate the behavior — trigger input_booleans, sensors named in options, the other covers in a group.

Step 4 — Root-Cause Against the Local Checkout

Read the actual code. Never infer a mechanism from a diagnostics reason string — those strings are rendered from reason_i18n.py templates and can lag or describe a different frame than the value beside them.

Work from the decision trace inward: the winning handler, then the registry composition pass that post-processes the winner, then whatever seam dispatched. CLAUDE.md's architecture map names the layer for each.

Note for shell searches: quote globs, since zsh expands them first.

grep -rn "pattern" --include="*.py" custom_components/    # not --include=*.py

Two recurring shapes worth checking explicitly, because both have produced real defects:

• The same rule stated at two seams. A user-command path and a pipeline path that each independently decide the same question. If one is priority-gated and the other is not, the gated one is defeated one cycle later. Read both; do not assume the one you found first is the only one.
• Values that are not what their name suggests. current_cover_position is the mean across every cover in the entry (_compute_mean_cover_position), not the position of the cover being commanded. Confirm the arithmetic against the observed number before building an argument on it.

Then check whether the behavior is already pinned by a test. If two tests assert opposite contracts for the same input and both pass, that pair is the finding — cite both with file:line.

Step 5 — Prove It With a Reproduction

Mandatory for any defect claim. Reconstruct the live numbers using the existing test fixtures and run it.

Find a test module that already builds the relevant snapshot (for pipeline work, tests/test_pipeline/test_floor_composition.py and its make_snapshot / _cp_state / _registry_with_custom helpers), import those helpers, substitute the values observed on the install, and print the result fields.

⚠️ The scratch test must live inside tests/. Running it from the scratchpad fails on enable_event_loop_debug — the autouse fixtures come from tests/conftest.py. Write it to tests/<subdir>/test_zz_scratch_repro.py, run it, then delete it.

cp <scratchpad>/test_repro.py tests/test_pipeline/test_zz_scratch_repro.py
venv/bin/python -m pytest tests/test_pipeline/test_zz_scratch_repro.py -q -s
rm tests/test_pipeline/test_zz_scratch_repro.py
git status --short          # must be clean before moving on

Use venv/bin/python -m pytest, never source venv/bin/activate. In a linked worktree there is no venv/ — pass the main checkout's absolute interpreter path.

Paste the real printed output into the issue. Do not paraphrase it, and do not write the repro without running it.

Step 6 — Verdict Before Filing

Classify before drafting. Not every live symptom is a defect:

Search the tracker before filing, both states:

gh issue list --repo jrhubott/adaptive-cover-pro --state all --limit 200 \
  --search "<symptom keywords>" --json number,title,state

Read the bodies of the close matches, not just their titles. A closed issue whose fix introduced the current behavior is the most valuable context an issue can carry, and its reporter's configuration usually explains why the fix was written the way it was. An open issue covering the same contract may mean the right move is a comment rather than a new issue — raise that with the user.