Axiomatic Reasoning for LLMs

Partial Implementation Plan on Bash

1. Introduction

This document defines a partial implementation plan for applying a subset of the Deep Coding methodology to Bash/Shell projects. Full Deep Coding—which assumes strong type systems, language‑enforced dependency control, and generative conformance—is not achievable in Bash due to fundamental language limitations. However, the following core practices can be partially implemented to improve structure, testability, and maintainability:

• Structural specification (interface contracts)
• Four‑layer validation gates
• Skeleton–tissue separation (by convention + CI)
• Recursive refinement with fixed premises

All philosophical framing is omitted. Only technical, executable procedures are described.

2. Core Principles (Technical Translation)

Deep Coding Principle	Bash Technical Equivalent (Partial)
Structural specification	YAML/JSON Schema + comment‑based pseudo‑types
Generative conformance	LLM‑assisted generation + validation gates (no automatic guarantee)
Skeleton–tissue separation	Directory split + CI checks (convention, not enforced)
Recursive refinement	Git tags + fixed premise file + Makefile automation

3. Structural Specification for Bash

3.1 Formats

Layer	Format	Tooling
CLI interface	YAML (clap4shell style)	Custom parser or LLM prompt
Data models	JSON Schema	jsonschema CLI, jq
Function contracts	Comment‑based signatures	Human review + runtime checks

3.2 Example Specification (YAML)

# spec/cli.yaml
module: backup_tool
version: 1.0.0
commands:
  - name: backup
    parameters:
      - name: source
        type: path
        required: true
      - name: dest
        type: path
        required: true
      - name: compression
        type: enum
        values: [gzip, none]
        default: none
    returns: exit_code
    errors: [1, 2]

4. Validation Gates (4‑Layer Model)

All generated or modified code must pass these gates before phase completion.

Layer	Tool	Command	Fail Action
L1: Syntax	bash -n	bash -n script.sh	Reject
L2: Static analysis	ShellCheck	shellcheck --format=gcc script.sh	Warn on style, reject on error
L3: Unit tests	Bats	bats tests/*.bats	Reject if any test fails
L4: Runtime contract	jq + JSON Schema	jsonschema -i data.json spec/types.json	Reject if validation fails

Limitation: L4 only validates data, not function purity or global state changes.

5. Skeleton–Tissue Architecture

5.1 Directory Structure

project/
├── skeleton/               # Manual, immutable (human only)
│   ├── core/
│   │   ├── logger.sh
│   │   └── validator.sh
│   └── templates/
│       └── pipeline.sh     # Template method (hook functions)
├── tissue/                 # Generated or AI‑produced, replaceable
│   ├── commands/
│   └── lib/
├── spec/                   # Structural specifications
├── tests/
├── Makefile
└── FIXED_PREMISE.md

5.2 Dependency Enforcement (CI)

# Check that skeleton does NOT source tissue
if grep -r "source.*tissue/" skeleton/ 2>/dev/null; then
    echo "ERROR: Skeleton cannot depend on tissue"
    exit 1
fi

Note: This is a convention check, not a language‑level guarantee.

6. Recursive Refinement and Fixed Premises

6.1 Phase Workflow

Each phase follows: Plan → Approve → Generate → Validate → Commit → Tag

6.2 Fixed Premise File (FIXED_PREMISE.md)

# Fixed Premise - Phase N
- Phase: N
- Date: YYYY-MM-DD
- Git tag: phase-N-complete
- Spec hash: sha256(spec/)
- Skeleton commit: abc123
- Validation: L1 ✓ L2 ✓ L3 ✓ L4 ✓
- Next allowed changes: [list]

6.3 Makefile Automation

.PHONY: phase-validate phase-complete

phase-validate:
	bash -n skeleton/*.sh tissue/*.sh
	shellcheck skeleton/*.sh tissue/*.sh
	bats tests/*.bats
	jsonschema -i data.json spec/types.json

phase-complete: phase-validate
	git tag -a "phase-$(PHASE)-complete" -m "Phase $(PHASE) done"
	echo "Fixed premise recorded"

6.4 Versioning

Use Bash‑based semantic versioning tools (e.g., svu, sver) to auto‑increment versions from commit messages.

7. Implementation Constraints and Workarounds

Constraint	Workaround
No type system	Use JSON Schema for data; comment‑based contracts for functions
No inheritance	Template method via function hooks + declare -f checks
No dependency direction enforcement	CI grep checks + code review
ShellCheck no custom rules	Accept limitations; supplement with manual review
LLM generation non‑deterministic	Use fixed seeds, re‑generate on failure, limit phase scope

8. Recommended Use Cases and Conclusion

8.1 When to Use This Partial Plan

• Small to medium CLI tools (<1000 lines)
• Teams willing to follow conventions (no technical enforcement)
• Rapid prototyping where some manual verification is acceptable
• Existing Bash codebases that cannot be rewritten

8.2 When Not to Use

• Large or critical systems
• Multiple teams without strict process discipline
• Domains requiring type safety (finance, medical)

8.3 Conclusion

A full Deep Coding implementation is not feasible in Bash due to missing language features (type system, inheritance, encapsulation). However, a partial implementation—focusing on structural specifications, four‑layer validation, skeleton–tissue by convention, and Git‑based recursive refinement—is possible and provides measurable improvements over ad‑hoc scripting. For new projects where Bash is not mandatory, prefer typed languages (Python, Go, TypeScript) for full Deep Coding benefits.

This site is open source. Improve this page.