#+TITLE: Root Cause Analysis: Telegram Gateway & Channel-Aware Chat
#+DATE: 2026-04-11
#+FILETAGS: :rca:gateway:telegram:chat:psf:

* Executive Summary
Successfully implemented the first external communication channel (Telegram) and decoupled the Chat Agent from its Emacs-centric roots. Resolved significant load-order and dependency issues identified during integration.

* 1. Issue: Undefined Foundational Functions
** Symptoms
During compilation, `gateway-telegram.lisp` failed with `UNDEFINED-FUNCTION` for `register-actuator` and `harness-log`.
** Root Cause
Poorly scoped foundational functions. These were defined in `core.lisp` (the loop orchestrator), which was loaded *after* the gateways in `org-agent.asd`. This created a "Circular Intention" where the gateways needed the harness to exist before the harness could load the gateways.
** Resolution
1. **Relocation:** Moved `*actuator-registry*` and `register-actuator` to `protocol.lisp` (the foundation).
2. **Reordering:** Adjusted `org-agent.asd` to load `core.lisp` (containing the stimulus loop) immediately after the symbolic gates but before the physical sensors (gateways).

* 2. Issue: Hardcoded Chat UI
** Symptoms
The `Chat Agent` could only respond via Emacs buffer insertion, rendering it useless for external channels like Telegram.
** Root Cause
Architectural myopia. The original chat skill assumed the user was always in front of Emacs.
** Resolution
Refactored `org-skill-chat` to be **Channel-Aware**:
- It now extracts `:channel` and `:chat-id` from the inbound stimulus.
- It dynamically generates the Probabilistic Engine mandate, instructing the LLM to use the appropriate `:target` (e.g., `:telegram`) based on the conversation context.

* 3. Side-Issue: UIOP Portability
** Symptoms
Tests failed with `Symbol "SETENV" not found in the UIOP/DRIVER package`.
** Root Cause
Misinterpretation of the `UIOP` API. `setenv` is not a standard export; the portable way is using `(setf (uiop:getenv ...) ...)`.
** Resolution
Updated all test environment setup to use the `setf` accessor.

* 4. PSF Mandate Alignment
** Sovereign Boundary
By moving the Telegram API logic to a user-space skill and communicating with the core via standard stimuli, we have respected the microkernel boundary.
** Homoiconic Memory
All Telegram interactions are now logged as `:chat-message` events, ensuring the agent's history is unified regardless of the platform.

* 5. Permanent Learnings
- **Foundation First:** Registries and logging macros must reside in the most foundational layers (`protocol` or `package`) to avoid load-order fragility.
- **Instruct the Actuator:** When adding new channels, always update the Chat Agent's neural prompt so it knows how to "speak" back through the new interface.