Encoding Tutorials

This section provides hands-on tutorials for encoding halachic content into Mistaber's formal reasoning system. Each tutorial builds on the previous, taking you from your first encoding through complex machloket handling, conditional rules, testing strategies, and the review process.

What You Will Learn

By completing these tutorials, you will master:

• Workflow Execution: Running the complete encoding pipeline with checkpoint approvals
• HLL Encoding: Transforming halachic source texts into formal ASP rules
• Machloket Modeling: Representing disputes between authorities using override semantics
• Complex Conditions: Encoding lechatchila/bedieved, hefsed exceptions, and context-sensitive rules
• Testing Strategies: Writing comprehensive test suites that verify correctness
• Review Navigation: Understanding what reviewers look for and how to address feedback

Prerequisites

Before starting these tutorials, ensure you have:

Technical Prerequisites

• Claude Code installed and configured
• mistaber-skills plugin installed in ~/.claude/plugins/mistaber-skills
• Sefaria MCP server configured for source text access
• Mistaber repository cloned with development environment active
• Familiarity with basic ASP/Prolog syntax

Knowledge Prerequisites

• Understanding of the HLL Language Reference
• Familiarity with the Predicate Registry
• Basic understanding of Kripke Semantics
• Completion of the core tutorials (especially "Understanding Worlds")

Halachic Background

While not strictly required, these tutorials are significantly easier with:

• Familiarity with Shulchan Aruch structure (Siman/Seif organization)
• Understanding of Ashkenazi/Sefardi distinctions
• Ability to read Hebrew source texts
• Knowledge of basic halachic terms (issur, heter, d'oraita, d'rabanan)

The Seven Kripke Worlds

All encoding tutorials work within Mistaber's seven-world structure:

graph TD
    base["base<br/>(Shulchan Aruch shared)"]

    base --> mechaber["mechaber<br/>(Sefardi)"]
    base --> rema["rema<br/>(Ashkenazi)"]
    base --> gra["gra<br/>(Vilna Gaon)"]

    mechaber --> sefardi_yo["sefardi_yo<br/>(Yalkut Yosef)"]
    rema --> ashk_mb["ashk_mb<br/>(Mishnah Berurah)"]
    rema --> ashk_ah["ashk_ah<br/>(Aruch HaShulchan)"]
    gra --> ashk_ah

    style base fill:#f0f0f0
    style mechaber fill:#e3f2fd
    style rema fill:#fce4ec
    style gra fill:#fff3e0
    style sefardi_yo fill:#e3f2fd
    style ashk_mb fill:#fce4ec
    style ashk_ah fill:#fff8e1

World	Authority	Tradition	Inherits From
base	Shulchan Aruch (shared)	Universal	None (root)
mechaber	R' Yosef Karo	Sefardi	base
rema	R' Moshe Isserles	Ashkenazi	base
gra	Vilna Gaon	Lithuanian	base
sefardi_yo	Yalkut Yosef	Modern Sefardi	mechaber
ashk_mb	Mishnah Berurah	Modern Ashkenazi	rema
ashk_ah	Aruch HaShulchan	Lithuanian Ashkenazi	rema + gra

Tutorial Progression

Difficulty Levels

Level	Meaning
Beginner	No prior encoding experience required
Intermediate	Requires completion of beginner tutorials
Advanced	Requires solid understanding of multi-world encoding

Learning Path

graph LR
    T1[01: Your First Encoding<br/>Beginner] --> T2[02: Handling Machloket<br/>Intermediate]
    T2 --> T3[03: Complex Conditions<br/>Intermediate]
    T3 --> T4[04: Testing Strategies<br/>Intermediate]
    T4 --> T5[05: Review Process<br/>Advanced]

    style T1 fill:#c8e6c9
    style T2 fill:#fff9c4
    style T3 fill:#fff9c4
    style T4 fill:#fff9c4
    style T5 fill:#ffccbc

Tutorial Summaries

01: Your First Encoding

Difficulty: Beginner | Duration: 2-3 hours | Target: YD 89:1 (Waiting Time)

Complete step-by-step walkthrough of encoding a single seif using the mistaber-skills workflow:

• Session setup and prerequisites verification
• Running the corpus-prep skill and reviewing the corpus report
• Running the hll-encode skill and understanding generated rules
• Running the validate skill and interpreting test results
• Running the review skill and completing checklists
• Running the commit skill and finalizing the encoding

What You Build: A complete encoding of the "waiting between meat and dairy" rule (YD 89:1), with all metadata, tests, and documentation.

---

02: Handling Machloket

Difficulty: Intermediate | Duration: 2 hours | Target: YD 87:3 (Fish & Dairy)

Tutorial on encoding disputes between authorities using Mistaber's override mechanism:

• Understanding the Mechaber vs Rema dispute on fish and dairy
• Encoding the Mechaber's position (sakana for fish + dairy)
• Encoding the Rema's override (no sakana, permitted)
• Using the override/3 predicate with descriptive values
• Verifying inheritance in child worlds (sefardi_yo, ashk_mb, ashk_ah)
• Writing tests for both positions

What You Build: Complete machloket encoding with override semantics, inheritance verification, and multi-world tests.

---

03: Complex Conditions

Difficulty: Intermediate | Duration: 1.5 hours

Tutorial on encoding context-sensitive halachic rules:

• Lechatchila vs Bedieved modifiers (ideal vs after-the-fact)
• Hefsed (financial loss) exceptions and their scope
• Shaat hadchak (pressing circumstances) considerations
• Combining multiple conditions in complex rules
• Real examples from the corpus with context sensitivity
• Testing conditional logic across different scenarios

What You Build: Conditional rules that behave differently based on context, with appropriate test coverage.

---

04: Testing Strategies

Difficulty: Intermediate | Duration: 1.5 hours

Tutorial on writing comprehensive test suites for encoded rules:

• Test file organization and naming conventions
• Writing positive tests (expected permits/prohibits)
• Writing negative tests (boundary conditions)
• Edge case identification and testing
• Multi-world tests for inheritance verification
• Machloket verification tests for both positions
• Pytest fixtures and parameterized tests
• CI integration and coverage requirements

What You Build: A complete test suite following Mistaber's testing standards.

---

05: Review Process

Difficulty: Advanced | Duration: 1 hour

Tutorial on navigating the review process successfully:

• What technical reviewers look for
• What halachic reviewers verify
• Common rejection reasons and how to avoid them
• Responding to review comments effectively
• Revision workflow and re-review requests
• Getting expert halachic review when needed
• Final approval criteria

What You Learn: How to submit PRs that pass review on the first attempt.

The Encoding Workflow

All tutorials use the mistaber-skills five-phase workflow:

Phase 1: corpus-prep   -->  Checkpoint 1: Source Review
Phase 2: hll-encode    -->  Checkpoint 2: Encoding Review
Phase 3: validate      -->  Checkpoint 3: Validation Review
Phase 4: review        -->  Checkpoint 4: Final Approval
Phase 5: commit        -->  Complete

Each phase requires human approval before proceeding to the next. This ensures halachic accuracy and technical correctness at every step.

Quick Reference: Rule Patterns

Basic Rule with Metadata

% Rule declaration
rule(r_bb_beheima_achiila).
makor(r_bb_beheima_achiila, sa("yd:87:1")).
madrega(r_bb_beheima_achiila, d_oraita).
scope(r_bb_beheima_achiila, mechaber).

% The actual rule
asserts(mechaber, issur(achiila, M, d_oraita)) :-
    is_beheima_chalav_mixture(M).

Override Pattern

% Override with DESCRIPTIVE value (never 'invalid')
override(rema, sakana(M), no_sakana) :-
    is_dag_chalav_mixture(M).

% Explicit assertion of the alternative
asserts(rema, heter(achiila, M)) :-
    is_dag_chalav_mixture(M).

Machloket Marker

% Document the dispute
machloket(dag_chalav_sakana, mechaber, rema, M) :-
    is_dag_chalav_mixture(M).

Critical Rules

Never Use 'invalid' in Override/3

The third argument of override/3 must be a descriptive value:

% WRONG
override(rema, sakana(M), invalid).

% CORRECT
override(rema, sakana(M), no_sakana).

Never Use Siman:Seif as Rule Names

Rule identifiers must be semantic, topic-based names:

% WRONG
rule(r_87_3).

% CORRECT
rule(r_bb_dag_sakana).

Every Normative Rule Needs Makor

All rules that make halachic assertions must cite sources:

rule(r_example).
makor(r_example, sa("yd:87:1")).  % Required!
madrega(r_example, d_oraita).      % Required for normative rules!

Getting Help

If you get stuck during a tutorial:

1. Check the Glossary: Explanation > Glossary
2. Review the Reference: HLL Language Reference
3. Consult Guidelines: Encoding Guidelines
4. Ask in Discussion: GitHub Discussions

Start Your First Tutorial

Ready to begin? Start with Your First Encoding to learn the complete workflow from source to commit.