#+TITLE: SKILL: Brain Mapper Agent (Meta-Cognition)
#+ID: skill-brain-mapper-agent
#+STARTUP: content

* Overview
The **Brain Mapper Agent** provides the system with meta-cognitive capabilities. It allows the agent (and the user) to visualize, reason about, and optimize the internal "Skill Graph" by analyzing real-time performance telemetry.

* The Meta-Cognitive Mandate
1. **Transparency:** The agent must be able to explain its own cognitive hierarchy and decision-making priorities.
2. **Self-Optimization:** Based on execution telemetry, the agent should proactively suggest priority adjustments to resolve bottlenecks.
3. **Introspection:** The agent identifies "Heavy" or "Failing" skills to maintain system health.

* Symbolic Implementation (The Logic)
The implementation below handles the introspection of the skill registry and the generation of optimization strategies.

** Architectural Intent: Introspective Trigger
Triggers when the user requests insight into the system's internal logic, priorities, or overall "thought" process.

#+begin_src 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)
        (search "how do you think" text :test #'string-equal)
        (search "optimize priorities" text :test #'string-equal))))
#+end_src

** Architectural Intent: Neuro-Cognitive Analysis
The neural layer is tasked with analyzing the gathered telemetry. It identifies patterns of failure or inefficiency and generates human-readable explanations alongside symbolic optimization commands.

#+begin_src lisp
(defun neuro-skill-brain-mapper (context)
  (let* ((skills (org-agent:context-list-all-skills))
         ;; Gather telemetry for each skill
         (telemetry (mapcar (lambda (s) 
                              (let ((name (getf s :name)))
                                (list :name name :stats (org-agent:context-get-skill-telemetry name))))
                            skills)))
    (format nil "
      You are the Cognitive Architect of this Lisp Machine.
      The user wants to see your current internal logic graph and performance.
      
      CURRENT SKILLS, PRIORITIES & TELEMETRY -
      ~a
      
      TASK -
      1. Explain your cognitive hierarchy. 
      2. Identify any 'Heavy' skills (high total-time) or 'Failing' skills (high failures).
      3. If a skill is underperforming, suggest a new priority to optimize the loop.
      
      Return a Lisp plist - (:target :emacs :action :message :text \"your analysis\")
      If optimization is needed, also return a (:target :system :action :set-priority :skill \"...\" :priority N) action.
    " telemetry)))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-brain-mapper
  :priority 95 ; High priority meta-cognition
  :trigger #'trigger-skill-brain-mapper
  :neuro #'neuro-skill-brain-mapper
  :symbolic (lambda (action context) action))
#+end_src