[EPIC] Behavior debugger — causal explanations, conversational policy patches, and replay #335

New issue

Open

opened 2026-09-08 02:03:34 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-08 02:03:34 +00:00

Owner

Parent architecture: #624
Builds on: #626 causal effect journal and #628 conversational policy programming. Integrates with structured runtime/Prolog diagnostics.

Goal

Make Zara's behavior debuggable by the user rather than mysterious.

Target interaction:

User: Why did you interrupt me?
Zara: build failure event -> critical priority -> focus policy allowed interruption -> threshold crossed.
User: Don't do that while I'm in Emacs unless master is broken.
Zara: proposes policy diff.
User: Replay what just happened.
OLD: interrupt
NEW: queue until focus ends

This is explanation of system decisions and causal evidence, not hidden LLM chain-of-thought.

Explanation contract

Expose a bounded structured decision trace containing only product-owned/runtime evidence such as:

triggering event/observation;
relevant typed facts and evidence classes;
applicable policy/rule IDs;
capability/authorization decision;
priority/attention decision;
selected action/provider;
causal effect IDs;
failure/degraded states.

Never manufacture a post-hoc explanation when required evidence was not recorded.

Conversational debugging

Support questions such as:

why did you do/not do X?;
what rule caused this?;
what would have happened if rule Y were disabled?;
show the relevant policy;
change this behavior;
replay this event under the proposed policy;
revert that policy change.

Policy mutations go through #628's validated/versioned authoring flow.

Replay

Historical replay operates on a privacy-safe recorded projection of relevant events/facts, never by re-running real side effects. The replay engine evaluates old/new policy and reports decision differences. External facts that were unavailable at the original decision are clearly marked if injected for simulation.

Tests

Cover exact causal explanations, missing evidence, conflicting rules, policy priority, stale facts, old/new replay, irreversible action simulation, cross-principal isolation, redaction, restart persistence and malicious attempts to use the debugger as an arbitrary Prolog/tool execution surface.

Acceptance

For supported runtime decisions Zara can show a machine-grounded causal explanation, let the user propose a safe policy change, replay the same situation without real side effects, and prove how the decision would change.

Parent architecture: #624 Builds on: #626 causal effect journal and #628 conversational policy programming. Integrates with structured runtime/Prolog diagnostics. ## Goal Make Zara's behavior **debuggable by the user** rather than mysterious. Target interaction: ```text User: Why did you interrupt me? Zara: build failure event -> critical priority -> focus policy allowed interruption -> threshold crossed. User: Don't do that while I'm in Emacs unless master is broken. Zara: proposes policy diff. User: Replay what just happened. OLD: interrupt NEW: queue until focus ends ``` This is explanation of system decisions and causal evidence, not hidden LLM chain-of-thought. ## Explanation contract Expose a bounded structured decision trace containing only product-owned/runtime evidence such as: - triggering event/observation; - relevant typed facts and evidence classes; - applicable policy/rule IDs; - capability/authorization decision; - priority/attention decision; - selected action/provider; - causal effect IDs; - failure/degraded states. Never manufacture a post-hoc explanation when required evidence was not recorded. ## Conversational debugging Support questions such as: - why did you do/not do X?; - what rule caused this?; - what would have happened if rule Y were disabled?; - show the relevant policy; - change this behavior; - replay this event under the proposed policy; - revert that policy change. Policy mutations go through #628's validated/versioned authoring flow. ## Replay Historical replay operates on a privacy-safe recorded projection of relevant events/facts, never by re-running real side effects. The replay engine evaluates old/new policy and reports decision differences. External facts that were unavailable at the original decision are clearly marked if injected for simulation. ## Tests Cover exact causal explanations, missing evidence, conflicting rules, policy priority, stale facts, old/new replay, irreversible action simulation, cross-principal isolation, redaction, restart persistence and malicious attempts to use the debugger as an arbitrary Prolog/tool execution surface. ## Acceptance For supported runtime decisions Zara can show a machine-grounded causal explanation, let the user propose a safe policy change, replay the same situation without real side effects, and prove how the decision would change.