memex/notes/org-skill-diagrammer.org

SKILL: Multi-Modal Diagrammer (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
• Phase D: Build (Implementation)
  • Synthesis Logic
• Registration
• Phase B: Blueprint (PROTOCOL)
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
    • 2.1. `synthesize-mermaid`
    • 2.2. `neuro-skill-diagrammer`
    • 2.3. `d2-layout` (Future Enhancement)

Overview

The Multi-Modal Diagrammer enables the agent to communicate complex architectural plans visually using Mermaid.js and D2 synthesis.

Phase A: Demand (PRD)

1. Purpose

Enable visual communication of plans and system states.

2. User Needs

• Mermaid Synthesis: Generate valid Mermaid.js graph code.
• D2 Support: Support D2 for complex layout requirements.
• Org-Integration: Embed results in `#+begin_src mermaid` blocks.

Phase D: Build (Implementation)

Synthesis Logic

(defun synthesize-mermaid (nodes edges)
  "Creates a Mermaid graph string from a list of nodes and edges."
  (let ((header "graph TD"))
    (format nil "~a~%~{  ~a --> ~a~%~}" header 
            (loop for e in edges append (list (car e) (cdr e))))))

(defun neuro-skill-diagrammer (context)
  "Neural stage: Converts a plan description into a visual graph structure."
  (let* ((payload (getf context :payload))
         (plan (getf payload :plan)))
    (format nil "
      Generate a Mermaid.js graph for the following plan:
      ---
      ~a
      ---
      Return only the Mermaid code block.
    " plan)))

Registration

(defskill :skill-diagrammer
  :priority 60
  :trigger (lambda (context) (eq (getf (getf context :payload) :sensor) :visualize))
  :neuro #'neuro-skill-diagrammer
  :symbolic (lambda (action context) action))

Phase B: Blueprint (PROTOCOL)

Phase B: Blueprint (PROTOCOL)

1. Architectural Intent

The Multi-Modal Diagrammer will translate abstract plans and system states into visual representations, primarily using Mermaid.js, and potentially D2 for advanced layouts. The system aims to provide a clear, concise, and easily embeddable visual summary of complex information to improve agent understanding and communication with humans. It separates neural summarization/extraction of the desired diagram content from the construction of a diagram based on that content.

2. Semantic Interfaces

2.1. `synthesize-mermaid`

This function takes a list of nodes and a list of edges and constructs a valid Mermaid.js graph declaration. Edges are represented as pairs, where the `car` is the source node and the `cdr` is the target node.

2.2. `neuro-skill-diagrammer`

This function takes a context plist, extracts the plan description from the `:payload`, and generates a prompt or directive to be used by a neural model to synthesize the graph. The prompt should focus on the content to be visualized, leaving Mermaid syntax details to the `synthesize-mermaid` function. The prompt should instruct the LLM to return only the mermaid code.

2.3. `d2-layout` (Future Enhancement)

This function (potentially implemented later) takes a Mermaid graph string and uses the D2 layout engine to improve the visual arrangement of the diagram. This would likely involve shelling out to a D2 process.