Axiomatic Reasoning for LLMs

Implementation Plan on Ruby

1. Overview

This document defines a technical implementation plan for applying a specification‑driven, human–AI collaborative development methodology (referred to as Deep Coding) to Ruby software projects. The plan translates four core principles into concrete Ruby constructs, toolchains, and phase‑based workflows:

All steps, evaluation metrics, and verification gates are defined in Ruby‑native terms, avoiding philosophical framing.

2. Core Technical Components

2.1 Structural Specification Layer

The specification is expressed using Ruby’s official type definition language RBS (standard library since Ruby 3.0).

Example RBS specification:

interface _Entity
  def update: (Float delta_time) -> void
  def render: (untyped surface) -> void
end

class GameLoopSkeleton
  def initialize: () -> void
  def run: () -> void
end

2.2 Skeleton–Tissue Architecture

2.3 Generative Conformance Loop

For each module or feature:

  1. Specification update – Modify RBS files (the structural specification).
  2. Generation request – AI generates implementation code that conforms to the updated RBS.
  3. Static verification – Run steep check to verify type conformance.
  4. Runtime validation – Run unit tests (RSpec) to verify behaviour.
  5. Commit – If all gates pass, commit the new specification and generated code.

If verification fails, regeneration is attempted. The phase does not proceed until all gates pass.

2.4 Fixed Premise Management

After each development phase, a structured summary is committed as a fixed premise:

Stored as FIXED_PREMISE.md (or YAML) in version control. Subsequent phases treat this summary as immutable.

3. Phase‑Based Workflow

Development proceeds in phases, each with the following steps:

Step Action
1. Plan Define specification changes (RBS deltas).
2. Approve Human reviews and approves the delta.
3. Generate AI generates tissue code from the updated RBS.
4. Static Gate steep check passes with zero errors.
5. Test Gate rspec passes all tests.
6. Dependency Gate packwerk (or custom RuboCop) checks dependency direction.
7. Summary Commit the fixed premise and tag the phase.

Example Phase Sequence for a Ruby Game Engine

Phase Focus Specification Change Generated Output
1 Core skeleton Define GameLoopSkeleton RBS interface Manual skeleton code (no generation)
2 Player & input Add Player protocol, InputState RBS AI‑generated Player implementation
3 Enemies & collision Add Enemy protocol, CollisionDetector interface AI‑generated enemy types and collision logic
4 Data‑driven stages Define Stage RBS model with spawn patterns AI‑generated stage loader
5 Editor integration Add StageEditor protocol, JSON serialization spec AI‑generated editor UI or API
6 Optimisation Add performance constraints (frame time) AI‑optimised rendering loops

4. Technical Verification Gates

All generated code must pass the following automated checks before phase completion:

Gate Tool Command Pass Condition
Type safety Steep steep check 0 errors
Linting RuboCop rubocop 0 offenses
Dependency direction Packwerk (Rails) / custom RuboCop packwerk check 0 violations
Unit tests RSpec rspec --format documentation 100% passing
Coverage SimpleCov rspec --coverage ≥ 80%

These gates are implemented as pre‑commit hooks and CI pipelines.

5. AI Integration Interface

The AI (LLM) is invoked with a structured prompt containing:

The AI output is restricted to:

The AI cannot modify:

6. LLM Integration Advantages (Technical)

Compared to conventional AI‑assisted Ruby development (e.g. GitHub Copilot), this specification‑driven approach provides measurable advantages:

Factor Conventional AI Specification‑driven (this plan)
Context efficiency Entire codebase often required Only RBS specification (few KB)
Type information Implicit, inferred from code Explicit, defined in RBS
Hallucination mitigation None Steep validation rejects non‑conforming code
Change propagation Manual or error‑prone Regenerate tissue from updated RBS
Dependency enforcement None Packwerk / RuboCop static checks

These advantages are most significant for medium‑to‑large projects and Rails applications, where context length and architectural consistency become bottlenecks.

7. Toolchain Requirements

Optional:

8. Boundary Conditions and Limitations

Condition Required Notes
Specification completeness Yes Incomplete RBS leads to correct‑but‑wrong code
Generation correctness High LLM must produce code that passes steep check; multi‑agent validation helps
Skeleton enforceability Partial Template method works; functional paradigms need different mechanisms
Non‑Rails projects Partial Packwerk unavailable; use custom RuboCop cops for dependency direction
Metaprogramming Limited Heavy use of method_missing or DSLs is not RBS‑friendly; move such code to tissue

When these conditions are not met, the methodology applies only to the specifiable subset, and conventional practices handle the remainder.

9. Directory Structure

project-root/
├── sig/                    # RBS specification files
│   ├── skeleton/
│   └── tissue/             # generated RBS (optional)
├── lib/
│   ├── skeleton/           # manual, immutable
│   ├── tissue/             # AI‑generated, regenerable
│   └── domain/             # manual entities
├── test/
│   ├── unit/
│   ├── integration/
│   └── type_check/
├── Gemfile
├── Steepfile
├── .rubocop.yml
├── package.yml             # Packwerk config (Rails)
├── Rakefile
├── FIXED_PREMISE.md
└── .github/workflows/ci.yml

10. Conclusion

The implementation plan defines a specification‑driven, AI‑collaborative workflow for Ruby projects using:

When applied, the workflow reduces context window usage (only RBS needs to be loaded), enables automatic verification of generated code, and allows specification‑only updates without manual propagation across modules. For medium‑to‑large projects and Rails applications, these characteristics provide measurable advantages over conventional AI‑assisted Ruby coding.

This site is open source. Improve this page.