Skip to content

Encoding Halachic Content

This section guides you through the process of encoding halachic source texts into Mistaber's formal reasoning system using the mistaber-skills Claude Code plugin. The encoding workflow transforms traditional halachic literature into machine-readable HLL (Halachic Logic Language) rules while maintaining complete source traceability and human expert oversight.

The Encoding Pipeline

The mistaber-skills plugin implements a five-phase, checkpoint-based workflow that ensures accuracy, completeness, and halachic fidelity:

flowchart LR
    subgraph Phase1["Phase 1"]
        CP[corpus-prep]
    end
    subgraph Phase2["Phase 2"]
        HE[hll-encode]
    end
    subgraph Phase3["Phase 3"]
        VA[validate]
    end
    subgraph Phase4["Phase 4"]
        RE[review]
    end
    subgraph Phase5["Phase 5"]
        CO[commit]
    end

    CP -->|Checkpoint 1| HE
    HE -->|Checkpoint 2| VA
    VA -->|Checkpoint 3| RE
    RE -->|Checkpoint 4| CO

    style CP fill:#e1f5fe
    style HE fill:#fff3e0
    style VA fill:#e8f5e9
    style RE fill:#fce4ec
    style CO fill:#f3e5f5

Phase Overview

Phase Skill Purpose Human Review Focus
1. Corpus Preparation corpus-prep Fetch and organize source texts from Sefaria, build derivation chains Source accuracy, machloket identification
2. HLL Encoding hll-encode Transform corpus into formal HLL rules with world scoping Rule accuracy, predicate usage
3. Validation validate Compile rules, run semantic checks and behavioral tests Test coverage, no regressions
4. Review review Assemble comprehensive review package Halachic and technical checklists
5. Commit commit Finalize and commit to repository Commit message, file organization

The Four Checkpoint Model

The encoding workflow enforces mandatory human approval at four critical junctures. This ensures that AI-assisted encoding never proceeds without expert validation:

Checkpoint 1: Corpus Approval

After corpus preparation, before encoding:

  • Verify source texts are accurate and complete
  • Confirm derivation chain reaches authoritative sources
  • Review machloket identification (all opinions captured)
  • Answer clarifying questions about ambiguous terms

Checkpoint 2: Encoding Approval

After HLL encoding, before validation:

  • Verify rules accurately represent the source
  • Confirm predicate selection is appropriate
  • Check world scoping (which authorities hold which positions)
  • Validate makor (source) chain attachment

Checkpoint 3: Validation Approval

After testing, before final review:

  • Confirm all tests pass (positive, negative, edge cases)
  • Verify machloket encoding produces both positions
  • Check for regressions in existing rules
  • Review performance metrics

Checkpoint 4: Final Approval

After comprehensive review, before commit:

  • Complete halachic accuracy checklist
  • Complete technical accuracy checklist
  • Test interactive queries
  • Confirm ready for permanent inclusion

Why Human Supervision Matters

Encoding halacha into formal logic requires expert judgment that AI cannot make alone:

  1. Interpretation Decisions: Many halachic texts have multiple valid interpretations. The human expert selects the authoritative reading.

  2. Machloket Boundaries: Determining what constitutes a genuine dispute vs. different applications of the same principle requires halachic expertise.

  3. Practical Psak: The encoding must align with how the halacha is actually practiced, not just theoretical constructs.

  4. Source Validation: While AI can fetch texts from Sefaria, only a human can verify the texts are correctly identified and complete.

  5. Priority Decisions: When multiple valid encoding approaches exist, the expert chooses based on project goals and halachic considerations.

Work Unit: Single Seif

The encoding pipeline operates on one seif at a time. This granularity provides:

  • Tractable Scope: Small enough for thorough human review
  • Meaningful Unit: Large enough to represent complete halachic concepts
  • Natural Boundaries: Follows the traditional structure of Shulchan Aruch
  • Clear Dependencies: Easy to track what has been encoded

Example Work Units:

  • YD 87:1 - Beheima (domesticated animal) meat with milk
  • YD 87:3 - Dag (fish) with dairy (machloket Mechaber/Rema)
  • YD 88:1 - Bitul (nullification) rules for basar bechalav

Prerequisites

Before starting encoding work, ensure you have:

Technical Requirements

  • Claude Code: Anthropic's CLI tool installed and configured
  • mistaber-skills plugin: Installed in your Claude Code plugins directory
  • Sefaria MCP server: Configured for source text access
  • Mistaber repository: Cloned with development environment set up

Knowledge Requirements

Halachic Background

While not strictly required for technical contributors, encoding work benefits greatly from:

  • Familiarity with Shulchan Aruch structure
  • Understanding of commentary layers (Shach, Taz, etc.)
  • Knowledge of Ashkenazi/Sefardi distinctions
  • Ability to read Hebrew source texts

Quick Start

Ready to start encoding? Here's the fastest path:

1. Install the Plugin

# Clone the plugin repository
git clone https://github.com/BrainyBlaze/mistaber-skills.git ~/.claude/plugins/mistaber-skills

2. Configure Sefaria MCP

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "sefaria-texts": {
      "command": "uvx",
      "args": ["sefaria-mcp"]
    }
  }
}

3. Start Your First Encoding Session

User: "Prepare corpus for YD 87:1"

This invokes the corpus-prep skill, which will guide you through the entire workflow.

Session State Management

The workflow maintains state in .mistaber-session.yaml, enabling:

  • Resumable Sessions: Pause and resume encoding work
  • Progress Tracking: See current phase and checkpoint status
  • Artifact Management: Track generated files and reports

Example session state:

current_phase: hll-encode
target_seif: "YD:88:1"
started: 2026-01-25T10:00:00Z
checkpoints:
  corpus-prep:
    status: approved
    approved_by: human
    timestamp: 2026-01-25T10:30:00Z
  hll-encode:
    status: pending_review
  validate:
    status: not_started
  review:
    status: not_started
complexity_score: 6

Workflow Enforcement

The mistaber-skills plugin includes hooks that prevent workflow violations:

Violation Prevention
Writing HLL without corpus approval phase-gate hook blocks
Missing @makor in rules encoding-guard hook blocks
Unknown predicate usage encoding-guard hook blocks
Commit without validation git-commit-guard hook blocks
Commit without review approval git-commit-guard hook blocks

These hooks ensure the encoding workflow cannot be circumvented, maintaining the integrity of the halachic encoding.

Documentation Structure

This section contains detailed documentation for each phase:

  • Getting Started

    Install the plugin, configure Sefaria, and understand the workflow phases

  • Corpus Preparation

    Fetch sources from Sefaria, build derivation chains, identify machloket

  • HLL Encoding

    Transform corpus into formal rules with world scoping and makor chains

  • Validation & Testing

    Compile rules, run semantic checks, execute behavioral tests

  • Review & Approval

    Assemble review package, complete halachic and technical checklists

  • Commit & Finalization

    Organize files, create git commit, prepare for next encoding cycle

Artifact Flow

The encoding pipeline produces structured artifacts at each phase:

INPUT                    SKILL              OUTPUT (Human Review)
-----                    -----              ---------------------
Seif reference    -->    corpus-prep   -->  corpus-report.md
                                            corpus-sources.yaml
                                            corpus-chain.mermaid

Approved corpus   -->    hll-encode    -->  encoding-report.md
                                            encoding-mapping.yaml
                                            world-specific .lp files

Encoded rules     -->    validate      -->  validation-report.md
                                            test-scenarios.yaml

Validated rules   -->    review        -->  review-package.md
                                            (interactive queries)

Approved package  -->    commit        -->  git commit
                                            progress update

Success Metrics

A successful encoding session achieves:

  1. Traceability: Every rule traceable to sources via makor/2 facts
  2. Completeness: All machloket positions encoded with opposing rules
  3. Validation: All generated tests pass without regression
  4. Accuracy: Human expert approves all four checkpoints
  5. Performance: Queries complete in acceptable time (<100ms average)