org-agent-contrib/org-skill-tech-analyst.org

SKILL: Technical Analyst Agent (Universal Literate Note)

• Overview
• Phase A: Demand (PRD)
  • 1. Purpose
  • 2. User Needs
  • 3. Success Criteria
    • Trigger Accuracy
    • TDD Suite Generation Verification
    • Edge Case Coverage Verification
• Phase B: Blueprint (PROTOCOL)
  • 1. Architectural Intent
  • 2. Semantic Interfaces
• Phase D: Build (Implementation)
  • Protocol Perception
  • Cognitive Trigger
  • Neuro-Cognitive Prompt
  • TDD Suite Actuation
• Registration

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)

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)

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

(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))

Cognitive Trigger

(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)))))

Neuro-Cognitive Prompt

(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)))

TDD Suite Actuation

(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)))
    
    (opencortex: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)))

Registration

(defskill :skill-tech-analyst
  :priority 120
  :trigger #'trigger-skill-tech-analyst
  :neuro #'neuro-skill-tech-analyst
  :symbolic #'tech-analyst-actuate)