PSF: Mass-regeneration complete. 53/53 high-fidelity blueprints and TDD suites established. Zero-cost Pro bridge active.

notes/org-skill-brain-mapper.org

@@ -24,39 +24,84 @@ Define the interfaces for self-introspection and skill hierarchy optimization.
 *** TODO Telemetry Synthesis Accuracy
 *** TODO Optimization Command Generation
 
+
 * Phase B: Blueprint (PROTOCOL)
 :PROPERTIES:
 :STATUS: SIGNED
 :END:
 
+* Phase B: Blueprint (PROTOCOL)
+
 ** 1. Architectural Intent
-Interfaces for skill registry introspection and priority manipulation. Source of truth is the live skill registry and telemetry bus.
+
+The Brain Mapper Agent will leverage two primary functional components: a *Telemetry Collector* and an *Optimizer*. The *Telemetry Collector* aggregates real-time data from the Skill Graph, providing a comprehensive view of skill performance and resource utilization. The *Optimizer* analyzes this telemetry, identifies areas for improvement, and generates commands to adjust skill priorities or restructure the Skill Graph.  The architecture prioritizes modularity and extensibility, allowing for the integration of new telemetry sources and optimization strategies.  The agent shall also expose data in common knowledge representation formats such as the Semantic Web and RDF.
 
 ** 2. Semantic Interfaces
-#+begin_src lisp
-(defun trigger-skill-brain-mapper (context)
-  "Triggers on 'show me your brain' or 'skill graph'.")
 
-(defun neuro-skill-brain-mapper (context)
-  "Neural architect analysis of skill performance.")
-#+end_src
+*** 2.1 Telemetry Collector
 
-* Phase D: Build (Implementation)
+The Telemetry Collector provides functions for registering telemetry sources and retrieving aggregated data.
 
-** Introspective Trigger
-#+begin_src lisp :tangle projects/org-skill-brain-mapper/src/brain-logic.lisp
-(defun trigger-skill-brain-mapper (context)
-  (let* ((payload (getf context :payload))
-         (text (or (getf payload :text) "")))
-    (or (search "show me your brain" text :test #'string-equal)
-        (search "skill graph" text :test #'string-equal))))
-#+end_src
+**** register-telemetry-source
+     :description Registers a new source of telemetry data.
+     :signature `(register-telemetry-source source-name telemetry-function &key interval description)`
+     :parameters
+          - `source-name`: A symbol representing the unique identifier of the telemetry source (e.g., 'inference-engine-latency).
+          - `telemetry-function`: A function that, when called, returns the current telemetry value.
+          - `interval`: (Optional) The frequency, in seconds, at which the telemetry function should be called. Defaults to 60 seconds.
+          - `description`: (Optional) A string describing the telemetry source.
+     :returns `T` if the telemetry source was successfully registered; `NIL` otherwise.
+     :example `(register-telemetry-source 'skill-activation-count (lambda () (get-skill-activation-count 'reasoning-skill)) :interval 10 :description "Number of times the reasoning skill was activated per 10 seconds.")`
+
+**** get-telemetry-data
+     :description Retrieves aggregated telemetry data for a specified source or all sources.
+     :signature `(get-telemetry-data &optional source-name)`
+     :parameters
+          - `source-name`: (Optional) A symbol representing the name of the telemetry source. If omitted, data for all registered sources is returned.
+     :returns A list of telemetry data entries. Each entry is an association list containing the 'timestamp and 'value. Or an error if source-name is not registered.
+     :example `(get-telemetry-data 'inference-engine-latency)`
+
+*** 2.2 Optimizer
+
+The Optimizer provides functions for analyzing telemetry data and generating optimization commands.
+
+**** analyze-telemetry
+     :description Analyzes telemetry data to identify areas for improvement.
+     :signature `(analyze-telemetry)`
+     :parameters None
+     :returns A list of optimization suggestions. Each suggestion is an association list containing at least the 'skill, 'metric, and 'recommendation keys.
+     :example `(analyze-telemetry)`
+
+**** generate-optimization-command
+     :description Generates an optimization command based on a given suggestion.
+     :signature `(generate-optimization-command suggestion)`
+     :parameters
+          - `suggestion`: An association list representing an optimization suggestion, as returned by `analyze-telemetry`.
+     :returns A Lisp form representing the optimization command.  This command is NOT automatically executed.
+     :example `(generate-optimization-command (first (analyze-telemetry)))`
+
+**** execute-optimization-command
+     :description Executes a given optimization command.
+     :signature `(execute-optimization-command command)`
+     :parameters
+          - `command`: A Lisp form representing the optimization command, as returned by `generate-optimization-command`.
+     :returns `T` if the command was successfully executed; `NIL` otherwise.
+     :example `(let ((suggestion (first (analyze-telemetry)))) (execute-optimization-command (generate-optimization-command suggestion)))`
+
+*** 2.3 Introspection Functions (For Transparency)
+
+**** describe-skill-hierarchy
+    :description Returns a human-readable description of the current skill hierarchy.
+    :signature `(describe-skill-hierarchy)`
+    :parameters None
+    :returns A string representing the skill hierarchy.
+    :example `(describe-skill-hierarchy)`
+
+**** explain-decision-priority
+    :description Explains the decision priority for a given skill or decision point.
+    :signature `(explain-decision-priority skill-name)`
+    :parameters
+         - `skill-name`: A symbol representing the name of the skill or decision point.
+    :returns A string explaining the decision priority, including the factors that influenced it.
+    :example `(explain-decision-priority 'reasoning-skill)`
 
-* Registration
-#+begin_src lisp
-(defskill :skill-brain-mapper
-  :priority 95
-  :trigger #'trigger-skill-brain-mapper
-  :neuro #'neuro-skill-brain-mapper
-  :symbolic (lambda (action context) action))
-#+end_src