passepartout/skills/org-skill-engineering-standards.org

:PROPERTIES:
:ID:       37f2b59f-4537-4cca-ac7f-5c24b9e2e773
:CREATED:  [2026-03-30 Mon 21:16]
:EDITED:   [2026-04-25 Sat]
:END:
#+TITLE: SKILL: Engineering Standards
#+STARTUP: content
#+FILETAGS: :engineering:standards:workflow:lisp:git:tdd:chaos:

* Overview

This skill enforces the Engineering Standards for all development within OpenCortex. It observes agent context and gates actions that violate protocol.

The standards are ordered by lifecycle phase, not priority. An agent must execute them in sequence, not selectively.

* Phase 0: Before You Think

** Skill-First Query Rule

Before any analysis, debugging, or implementation: check if a skill already covers the problem domain.

Query the skill catalog via ~(list-skills)~ or ~(find-skill :keyword)~. If a relevant skill exists:
1. Read the skill's org file
2. Follow its mandates
3. Do not duplicate logic

Rationale: The skill layer is the primary intelligence. Raw LLM reasoning is a fallback, not a starting point. Violating this creates drift, where your solution diverges from the system's encoded wisdom.

* Phase A: Design (Test-First)

** 1. Define Success Criteria First

Before writing code, write the test that proves the feature works. The test defines the contract.

If the change is architectural, write the test as a PROTOCOL document (Plan Mode) and seek approval.

** 2. Break the Design with Chaos

After defining success criteria, run adversarial analysis:

- *Deterministic chaos:* Scripted regression tests that feed the system known-good inputs and verify known-good outputs. Run on every change.
- *Probabilistic chaos:* Randomized fuzzing, property-based testing, and noise injection to discover unknown failure modes. Run on every major release.
- *Stress chaos:* Sustained load, resource starvation, and concurrent access to find edge-case instabilities. Run during hardening sprints.

Rationale: If you cannot break your own design, you have not understood it.

* Phase B: Commit (Recovery Point)

** 3. Commit Before Modify

You MUST commit (and push, if network is available) the current workspace state before initiating new file modifications.

This is not a suggestion. If ~verify-git-clean-p~ returns NIL, the engineering standards gate MAY block high-impact actions.

* Phase C: Build (Implementation)

** 4. Literate Programming (Single Source of Truth)

All system logic and skills MUST be implemented as Literate Org files. Weave documentation and code together. The "Why" (Architectural Intent) is never separated from the "How" (Implementation).

** 5. Function-Block Granularity

Every Lisp function, macro, or variable resides in its own dedicated ~#+begin_src lisp~ block, immediately preceded by its explanatory text.

** 6. Tangle Mandate

You are forbidden from modifying generated ~.lisp~ files directly. All changes MUST be made in the Org file and then tangled.

** 7. Configuration Externalization

Source code MUST be free of hardcoded configuration values. Extract to environment variables and document in ~.env.example~.

** 8. Org as Thinking Medium

When debugging or analyzing issues, document your investigation in the relevant org file BEFORE implementing a fix.

Record: root cause hypothesis, evidence found, options considered, tradeoffs, decision rationale.

* Phase D: Validate (Proof)

** 9. Test Verification

No change is complete without running the test suite. A change that breaks existing tests is not a fix — it is damage.

Run chaotic tests alongside the main suite.

* Phase E: Document (Audit Trail)

** 10. Decision Audit Trail

Every significant fix or architectural decision MUST be documented in an org file with:
- Root cause analysis
- Options considered and tradeoffs
- Why this solution was chosen

** 11. Stop-and-Wait (Turn-Yielding)

For major changes, propose your strategy in plain text, state "Waiting for user feedback," and yield the turn. Do not draft implementation in the same message.

** 12. GTD Synchronization

You are forbidden from considering a task complete without updating ~gtd.org~. Record all major shifts using hierarchical TODO headlines, NOT checkboxes.

* Implementation

** Git Status Check

#+begin_src lisp :tangle ../library/gen/org-skill-engineering-standards.lisp
(defun verify-git-clean-p (&optional (dir *project-root*))
  "Returns T if the git repository at DIR has no uncommitted changes."
  (let ((status (uiop:run-program (list "git" "-C" (namestring dir) "status" "--porcelain")
                                  :output :string
                                  :ignore-error-status t)))
    (string= "" (string-trim '(#\Space #\Newline #\Tab) status))))
#+end_src

** Engineering Standards Gate

#+begin_src lisp :tangle ../library/gen/org-skill-engineering-standards.lisp
(defun engineering-standards-gate (action context)
  "The deterministic gate for the Engineering Standards skill.

  Checks:
  1. Git tree is clean (warn if dirty)
  2. Action has :engineering-standards-compliance note if high-impact

  Returns ACTION unmodified. This is a warning gate, not a blocking gate."
  (declare (ignore context))

  ;; Check 1: Git cleanliness
  (let ((dirty (not (verify-git-clean-p))))
    (when dirty
      (harness-log "ENGINEERING STANDARDS: Warning - Working tree is dirty. Commit before modifying files.")))

  action)
#+end_src

** Skill Registration

#+begin_src lisp :tangle ../library/gen/org-skill-engineering-standards.lisp
(defskill :skill-engineering-standards
  :priority 1000
  :trigger (lambda (ctx) (declare (ignore ctx)) t)
  :probabilistic nil
  :deterministic #'engineering-standards-gate)
#+end_src

* See Also
- [[file:org-skill-literate-programming.org][Literate Programming Skill]] - Structural validation and tangle rules
- [[file:org-skill-policy.org][Policy Skill]] - Constitutional constraints
- [[file:../README.org][opencortex README]]