#+TITLE: Root Cause Analysis: Playwright-Python Bridge (High-Fidelity Browsing)
#+DATE: 2026-04-11
#+FILETAGS: :rca:intelligence:browsing:automation:autonomy:

* Executive Summary
Successfully implemented a high-fidelity browsing bridge using Playwright and Python. This allows the `opencortex` to interact with modern, JavaScript-rendered web applications that were previously inaccessible via simple HTTP clients.

* 1. Architectural Strategy: The I/O Bridge
** Problem
Common Lisp lacks a mature, native Playwright implementation. Direct bindings are complex and fragile.
** Resolution
Implemented a **JSON-over-STDIO Bridge**. 
- A standalone Python script (`browser-bridge.py`) manages the Playwright lifecycle and Chromium instance.
- The Lisp kernel communicates with this script using `uiop:run-program`, passing parameters via `stdin` and receiving structured results via `stdout`. This provides a stable, decoupled interface.

* 2. Environment & Dependency Management
** Issue
Playwright requires a specific version of Chromium and several system-level libraries not present in the base Debian image.
** Resolution
Updated the `Dockerfile` to:
1. Install Python3, pip, and venv.
2. Create a virtual environment for isolated dependency management.
3. Install the `playwright` package and execute `playwright install --with-deps chromium` during the image build. This ensures the production container is ready for high-fidelity browsing immediately upon startup.

* 3. Cognitive Tooling
Created the `:browser` cognitive tool, which exposes three primary capabilities to Probabilistic Engine:
- **Navigation:** Full JS rendering and waiting for network idle.
- **Extraction:** Targeted text retrieval via CSS selectors.
- **Vision:** Base64-encoded screenshot capture for future multimodal processing.

* 4. opencortex Mandate Alignment
** Zero-Bloat (Managed)
While adding Playwright increases the image size, it is a "Complexity Earned" trade-off that dramatically expands the agent's capability frontier.
** Literate Granularity
The `org-skill-playwright.org` file strictly follows the "one definition per block" mandate.

* 5. Permanent Learnings
- **Inter-Process JSON:** JSON is the ideal lingua franca for Lisp-Python bridges.
- **Path Portability:** Always use `uiop:native-namestring` when passing Lisp paths to external shell commands to ensure OS compatibility.