passepartout/docs/rca/rca-gateway-telegram.org

Root Cause Analysis: Telegram Gateway & Channel-Aware Chat

• Executive Summary
• 1. Issue: Undefined Foundational Functions
  • Symptoms
  • Root Cause
  • Resolution
• 2. Issue: Hardcoded Chat UI
  • Symptoms
  • Root Cause
  • Resolution
• 3. Side-Issue: UIOP Portability
  • Symptoms
  • Root Cause
  • Resolution
• 4. PSF Mandate Alignment
  • Sovereign Boundary
  • Homoiconic Memory
• 5. Permanent Learnings

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 `communication.lisp` (the foundation).
2. Reordering: Adjusted `org-agent.asd` to load `core.lisp` (containing the stimulus loop) immediately after the deterministic 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.