Skip to content

Encoding Guidelines

This section provides comprehensive guidelines for contributors encoding halachic content into Mistaber's formal representation. These guidelines ensure consistency, accuracy, and maintainability across the entire corpus.

Purpose

Encoding halachic literature into a formal logic system requires careful attention to both halachic accuracy and technical correctness. These guidelines serve as the authoritative reference for:

  1. Halachic Integrity - Ensuring encoded rules faithfully represent source material
  2. Technical Consistency - Maintaining uniform patterns across the corpus
  3. Multi-World Correctness - Properly handling machloket and world inheritance
  4. Source Traceability - Complete attribution chains from derivation to primary sources

Guideline Categories

Methodology and Process

Guideline Purpose When to Consult
Encoding Methodology Core principles and step-by-step process Before starting any encoding task
Contributing Encodings Workflow from claim to merge When joining a project or starting new work
Review Standards Quality checklist and review criteria Before submitting and during review

Halachic Content

Guideline Purpose When to Consult
Halachic Accuracy Verification and correctness standards When encoding normative rules
Halachic Concepts Authority levels, safek, and context When encoding complex halachic logic
Source Attribution Makor chain requirements When citing sources for rules
Machloket Handling Encoding disputes and disagreements When Mechaber/Rema or other poskim disagree

Technical Implementation

Guideline Purpose When to Consult
World Scoping When to use which Kripke world When deciding where to place rules
Predicate Selection Choosing and creating predicates When writing rule heads and bodies
Testing Requirements Required test coverage Before submitting any PR

Quick Reference Decision Tree

Use this decision tree to find the right guideline for your situation:

graph TD
    A[Starting Encoding Task] --> B{New contributor?}
    B -->|Yes| C[Read Contributing Encodings]
    B -->|No| D{What type of content?}

    C --> D

    D -->|Basic fact| E[Encoding Methodology]
    D -->|Normative rule| F{Is there machloket?}
    D -->|Complex scenario| G[Halachic Concepts]

    F -->|Yes| H[Machloket Handling]
    F -->|No| I{Which world?}

    H --> I

    I -->|Shared rule| J[World Scoping - base]
    I -->|Tradition-specific| K[World Scoping - specific world]

    J --> L{What predicates?}
    K --> L

    L --> M[Predicate Selection]

    M --> N{Sources needed?}
    N -->|Yes| O[Source Attribution]
    N -->|No| P[Testing Requirements]

    O --> P

    P --> Q[Review Standards]
    Q --> R[Submit PR]

The Seven Kripke Worlds

Mistaber uses a directed acyclic graph (DAG) of seven worlds to represent different halachic traditions:

graph TD
    base[base<br/>Shulchan Aruch shared rules]

    base --> mechaber[mechaber<br/>Sefardi position]
    base --> rema[rema<br/>Ashkenazi position]
    base --> gra[gra<br/>Vilna Gaon position]

    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:#e1f5fe
    style mechaber fill:#fff3e0
    style rema fill:#f3e5f5
    style gra fill:#e8f5e9
    style sefardi_yo fill:#fff3e0
    style ashk_mb fill:#f3e5f5
    style ashk_ah fill:#f3e5f5
World Tradition Inherits From Primary Use
base Common ground None (root) Rules all traditions share
mechaber Sefardi base Shulchan Aruch author's rulings
rema Ashkenazi base Rema's glosses
gra Vilna Gaon base GRA's distinctive positions
ashk_mb Mishnah Berurah rema Litvish Ashkenazi practice
ashk_ah Aruch HaShulchan rema, gra Russian/Lithuanian practice
sefardi_yo Yalkut Yosef mechaber Modern Sefardi practice

Critical Rules Summary

Override Semantics

The override/3 predicate uses descriptive values in the third argument:

% CORRECT - third argument describes the overriding position
override(dag_bechalav_is_sakana, mechaber, sakana_fish_dairy).
override(dag_bechalav_is_sakana, rema, no_sakana).

% WRONG - never use 'invalid' as the third argument
% override(some_rule, world, invalid).  % DO NOT DO THIS

Rule Naming Convention

Rules use topic-based naming with r_ prefix:

% CORRECT - descriptive topic-based names
r_bb_dag_sakana        % fish danger in bb laws
r_bb_beheima_achiila   % meat eating rule
r_bb_of_bishul_mutar   % poultry cooking permission

% WRONG - siman-seif based naming
% r_87_3                 % DO NOT DO THIS
% r_yd87_seif3           % DO NOT DO THIS

Mandatory Source Attribution

Every normative rule requires a @makor directive:

% CORRECT - every normative rule has source
@rule(r_bb_beheima_achiila)
@makor([sa("YD:87:1")])
@madrega(d_oraita)
asserts(mechaber, issur(achiila, M, d_oraita)) :-
    is_beheima_chalav_mixture(M).

% WRONG - missing @makor for normative rule
% @rule(r_bb_something)
% @madrega(d_rabanan)
% forbidden(W, achiila, F, ctx_normal) :- ...  % REJECTED

Minimum Test Requirements

Every encoding must include:

Test Type Minimum Count Purpose
Positive cases 5 Verify rule fires correctly
Negative cases 3 Verify rule does not fire incorrectly
Edge cases 2 Test boundary conditions
Multi-world If applicable Verify inheritance and overrides

File Organization Reference

mistaber/
  ontology/
    corpus/
      yd_XX/           # Yoreh Deah siman XX
        base.lp        # Shared definitions
    worlds/
      base.lp          # Root world
      mechaber.lp      # Sefardi tradition
      rema.lp          # Ashkenazi tradition
      gra.lp           # Vilna Gaon
      ashk_mb.lp       # Mishnah Berurah
      ashk_ah.lp       # Aruch HaShulchan
      sefardi_yo.lp    # Yalkut Yosef

tests/
  corpus/
    yd_XX/
      test_*.py        # Python test files

Getting Started Checklist

Before your first encoding:

Essential Reading

Tutorials

Development

Version History

Version Date Changes
0.2.0 2026-01-25 Initial comprehensive guidelines