:PROPERTIES:
:ID:       d2ec6e07-c1ee-43fb-8eae-9900e073a24f
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-07 Tue 13:42]
:END:
#+TITLE: SKILL: Technical Analyst Agent (Universal Literate Note)
#+STARTUP: content
#+FILETAGS: :analyst:testing:tdd:psf:

* Overview
The *Technical Analyst Agent* defines the *Success Criteria* for a project. It generates a failing test suite immediately after the architecture is signed, enforcing a strict TDD mandate within the PSF Consensus Loop.

* Phase A: Demand (PRD)
:PROPERTIES:
:STATUS: FROZEN
:END:

** 1. Purpose
Define automated testing behaviors for the PSF Consensus Loop.

** 2. User Needs
- *Protocol Perception:* Monitor for `SIGNED` Protocols.
- *TDD Inception:* Translate interfaces into executable test cases.
- *Edge Case Coverage:* Mandatory testing of failure modes and malformed input.
- *Structural Enforcement:* Ensure the `tests/` directory is correctly initialized.

** 3. Success Criteria
*** TODO Trigger Accuracy
*** TODO TDD Suite Generation Verification
*** TODO Edge Case Coverage Verification

* Phase B: Blueprint (PROTOCOL)
:PROPERTIES:
:STATUS: SIGNED
:END:

** 1. Architectural Intent
Interfaces for TDD suite actuation and protocol perception. Source of truth is the project's SIGNED Protocol.

** 2. Semantic Interfaces
"Checks if a project has a SIGNED PROTOCOL."
"Physically writes the TDD suite to tests/."

* Phase D: Build (Implementation)

** Protocol Perception
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun tech-analyst-perceive-signed-protocol (note-path)
  "Checks if a master note has a SIGNED PROTOCOL and lacks a TDD suite in the material project."
  (let* ((content (uiop:read-file-string note-path))
         (filename (pathname-name note-path))
         (project-name (subseq filename 10)) ; Extract 'name' from 'org-skill-name'
         (projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/"))
         (test-path (format nil "~aorg-skill-~a/tests/test-suite.lisp" projects-dir project-name)))
    (when (and (search "* Phase B: Blueprint (PROTOCOL)" content)
               (search ":STATUS: SIGNED" content)
               (not (uiop:file-exists-p test-path)))
      `(:project-name ,project-name :note-path ,note-path :content ,content))))

(defun tech-analyst-scan-all-notes ()
  "Scans all org-skill-*.org notes for blueprints ready for testing."
  (let ((notes-dir (or (uiop:getenv "MEMEX_NOTES") "notes/"))
        (ready-notes '()))
    (dolist (file (uiop:directory-files notes-dir "org-skill-*.org"))
      (let ((status (tech-analyst-perceive-signed-protocol file)))
        (when status (push status ready-notes))))
    ready-notes))
#+end_src

** Cognitive Trigger
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun trigger-skill-tech-analyst (context)
  "Triggers on heartbeat if any master note is in a SIGNED PROTOCOL state."
  (let ((type (getf context :type))
        (payload (getf context :payload)))
    (when (and (eq type :EVENT) (eq (getf payload :sensor) :heartbeat))
      (let ((ready (tech-analyst-scan-all-notes)))
        (when ready
          (setf (getf (getf context :payload) :ready-blueprints) ready)
          t)))))
#+end_src

** Neuro-Cognitive Prompt
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun neuro-skill-tech-analyst (context)
  (let* ((payload (getf context :payload))
         (note (car (getf payload :ready-blueprints)))
         (name (getf note :project-name))
         (protocol-content (getf note :content)))
    (format nil "
      You are the PSF Technical Analyst. 
      The Master Note for project '~a' has a SIGNED PROTOCOL and needs a TDD Suite. 
      
      PROTOCOL CONTENT:
      ---
      ~a
      ---
      
      TASK:
      Generate a comprehensive Common Lisp test suite (failing/RED).
      1. Use FiveAM for testing.
      2. Match function signatures exactly as defined in the PROTOCOL.
      
      Return a Lisp plist: (:target :analyst :action :actuate :name \"~a\" :content \"...test code...\")
    " name protocol-content name)))
#+end_src

** TDD Suite Actuation
#+begin_src lisp :tangle ../projects/org-skill-tech-analyst/src/analyst-logic.lisp
(defun tech-analyst-actuate (action context)
  (let* ((payload (getf action :payload))
         (project-name (getf payload :name))
         (test-content (getf payload :content))
         (projects-dir (or (uiop:getenv "PROJECTS_DIR") "projects/"))
         (project-dir (format nil "~aorg-skill-~a/" projects-dir project-name))
         (test-dir (format nil "~atests/" project-dir))
         (test-path (format nil "~atests/test-suite.lisp" project-dir)))
    
    (org-agent:kernel-log "ANALYST - Actuating TDD Suite for ~a" project-name)
    (ensure-directories-exist test-dir)
    (with-open-file (out test-path :direction :output :if-exists :supersede)
      (format out ";;; TDD Suite for ~a~%~a" project-name test-content))
    (format nil "SUCCESS - Technical Analyst established TDD Suite for ~a" project-name)))
#+end_src

* Registration
#+begin_src lisp
(defskill :skill-tech-analyst
  :priority 120
  :trigger #'trigger-skill-tech-analyst
  :neuro #'neuro-skill-tech-analyst
  :symbolic #'tech-analyst-actuate)
#+end_src