Amr Gharbeia
31acf347de
- Add org-skill-literate-programming: enforce Org discipline - One function per block, pre-tangle check, .lisp is derived - Extend org-skill-engineering-standards with Phase 0-5 lifecycle - Test-first design, three chaos tiers - Literate programming rules, decision audit trail
5.7 KiB
SKILL: Engineering Standards
- Overview
- Phase 0: Before You Think
- Phase A: Design (Test-First)
- Phase B: Commit (Recovery Point)
- Phase C: Build (Implementation)
- Phase D: Validate (Proof)
- Phase E: Document (Audit Trail)
- Implementation
- See Also
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:
- Read the skill's org file
- Follow its mandates
- 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
(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))))Engineering Standards Gate
(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)Skill Registration
(defskill :skill-engineering-standards
:priority 1000
:trigger (lambda (ctx) (declare (ignore ctx)) t)
:probabilistic nil
:deterministic #'engineering-standards-gate)See Also
- Literate Programming Skill - Structural validation and tangle rules
- Policy Skill - Constitutional constraints
- opencortex README