Skip to content

Halachic Accuracy

Ensuring halachic accuracy is the paramount concern when encoding content into Mistaber. An incorrectly encoded rule can propagate errors through the reasoning system, potentially affecting practical halachic guidance. This document establishes verification requirements, cross-referencing procedures, and error correction protocols.

Verification Requirements

Minimum Source Consultation

Every encoding must be verified against a minimum set of sources before submission:

Source Level Required Sources Purpose
Primary Original Shulchan Aruch text Verify exact wording
Gloss Rema's commentary (if encoding Ashkenazi) Check for modifications
Commentaries At least 2 Acharonim Verify interpretation
Cross-reference Related simanim Check consistency

Language Requirements

Primary source verification must be done in the original Hebrew. English translations may contain interpretive choices that differ from the original.

Source Hierarchy for Verification

When sources conflict, use this priority order:

graph TD
    A[Shulchan Aruch/Rema] --> B[Taz and Shach]
    B --> C[Pri Megadim]
    C --> D[Mishnah Berurah / Aruch HaShulchan]
    D --> E[Contemporary Poskim]

    style A fill:#e8f5e9
    style B fill:#e3f2fd
    style C fill:#fff3e0
    style D fill:#fce4ec
    style E fill:#f3e5f5

For encoding purposes:

  1. Shulchan Aruch text is the baseline for mechaber world
  2. Rema's gloss is the baseline for rema world
  3. Later commentaries clarify but do not replace primary text
  4. Contemporary poskim inform practical application but are encoded in child worlds

Verification Checklist

Before marking an encoding complete:

  • [ ] Read original SA text in Hebrew
  • [ ] Read Rema's gloss (if any)
  • [ ] Consulted at least 2 standard commentaries
  • [ ] Checked for related content in adjacent seifim
  • [ ] Verified madrega level from explicit source statement
  • [ ] Confirmed machloket exists before encoding multiple positions
  • [ ] Cross-referenced with established halachic databases (Sefaria, Otzar HaHochma)

Cross-Referencing Sources

Primary Source Cross-Reference Table

SA Citation Required Cross-Reference Why
YD 87:1 Gemara Chullin 103b-104a Biblical source for issur
YD 87:3 Gemara Chullin 104a-b Rabbinic source for of/chaya
YD 87:3 (fish) Beit Yosef ad loc Mechaber's sakana reasoning
YD 89:1 Gemara Chullin 105a Waiting time derivation

Cross-Reference Procedure

For each rule encoded:

  1. Identify the Talmudic source: 

    makor(r_bb_beheima_achiila, gemara("Chullin 103b")).

  2. Trace the Rishonim interpretation: 

    makor(r_bb_beheima_achiila, rambam("ma:9:1")).
makor(r_bb_beheima_achiila, tur("yd:87")).

  3. Document the SA codification: 

    makor(r_bb_beheima_achiila, sa("yd:87:1")).

  4. Note Acharonim clarifications: 

    % Commentary: Shach 87:1 clarifies that...
% Commentary: Taz 87:2 adds that...

Handling Discrepancies Between Sources

When sources seem to conflict:

graph TD
    A[Source Conflict Detected] --> B{Is it textual ambiguity?}

    B -->|Yes| C[Consult traditional commentators]
    B -->|No| D{Is it genuine machloket?}

    C --> E{Consensus exists?}
    E -->|Yes| F[Encode consensus interpretation]
    E -->|No| D

    D -->|Yes| G[Encode as multi-world machloket]
    D -->|No| H[Escalate to expert review]

    F --> I[Document reasoning in comments]
    G --> I
    H --> I

Never Resolve Machloket Through Assumption

If two authoritative sources genuinely disagree, encode both positions in appropriate worlds. Never assume one position is "correct" without explicit textual support.

Handling Ambiguity

Types of Halachic Ambiguity

Type Description Resolution
Textual Words can be read multiple ways Check commentaries for accepted reading
Scope Unclear what cases are included Check for explicit examples in sources
Application Unclear how principle applies today Document uncertainty, encode conservatively
Translation Hebrew term has multiple meanings Use Hebrew terminology in comments

Ambiguity Resolution Process

Step 1: Document the Ambiguity

% AMBIGUITY: SA 87:3 states "dagim v'chagavim"
% The term "dagim" (fish) is clear, but the inclusion of specific
% species in "chagavim" (locusts) is debated.
%
% Resolution: Encode the fish ruling explicitly; defer locust
% classification to future encoding when species list is established.

Step 2: Consult Standard Commentaries

Check in order:

  1. Beit Yosef (for understanding Mechaber's intent)
  2. Darkei Moshe (for understanding Rema's intent)
  3. Shach and Taz (for practical clarification)
  4. Pri Megadim (for systematic analysis)

Step 3: Encode Conservatively

When genuine ambiguity remains:

% Conservative encoding - only include clear cases
asserts(mechaber, issur(achiila, M, d_rabanan)) :-
    is_of_chalav_mixture(M),
    of_type(M, chicken).  % Explicitly included species

asserts(mechaber, issur(achiila, M, d_rabanan)) :-
    is_of_chalav_mixture(M),
    of_type(M, turkey).   % Explicitly included species

% Note: Other birds require separate analysis
% See: [ISSUE-123] Classification of exotic birds for basar bechalav

Documenting Unresolved Ambiguity

Use structured comments:

% ============================================================
% UNRESOLVED: YD 87:X - Topic Description
% ============================================================
% STATUS: Deferred pending expert consultation
%
% AMBIGUITY: [Description of the unclear point]
%
% SOURCES CONSULTED:
%   - SA 87:X - says "..."
%   - Shach 87:X - interprets as "..."
%   - Taz 87:X - interprets as "..."
%
% OPTIONS:
%   A) [First interpretation]
%   B) [Second interpretation]
%
% IMPACT: This affects rules r_xxx and r_yyy
%
% TRACKING: Create a tracking issue in the project tracker.
% ============================================================

Expert Review Process

When Expert Review is Required

Expert review is mandatory when:

Scenario Reason
Encoding d_oraita content Biblical commandments have highest stakes
Machloket between major poskim Requires nuanced understanding
Novel predicate creation May affect ontology integrity
Safek resolution Doubt handling has complex rules
Medical/scientific facts Intersects with halachic application

Expert Reviewer Qualifications

Role Requirements
Halachic Reviewer Semicha, familiarity with YD, active learning
Technical Reviewer ASP/logic programming, Mistaber architecture
Domain Expert Specialization in specific area (e.g., kashrut)

Review Request Template

## Expert Review Request

**Encoding**: YD 87:3 Fish and Dairy (machloket Mechaber/Rema)

**Encoder**: @username

**Review Type**: Halachic

**Summary**:
Encoding the machloket regarding fish with dairy. Mechaber
holds sakana applies; Rema holds no sakana. Need verification
that override semantics correctly capture the disagreement.

**Specific Questions**:
1. Is "sakana" correctly classified as non-issur category?
2. Should the override propagate to all Ashkenazi descendants?
3. Are there later poskim who modify either position?

**Sources Consulted**:
- SA YD 87:3
- Beit Yosef ad loc
- Rema ad loc
- Shach 87:5
- Taz 87:4

**Test Cases**:
- test_fish_dairy_mechaber_sakana
- test_fish_dairy_rema_permitted
- test_ashk_mb_inherits_rema

**Files Changed**:
- mistaber/ontology/worlds/mechaber.lp
- mistaber/ontology/worlds/rema.lp
- tests/corpus/yd_87/test_fish_dairy.py

Expert Review Outcomes

Outcome Action
Approved Proceed to merge
Approved with Comments Address comments, re-request if substantive
Revisions Requested Make changes, re-submit for review
Rejected Major issues; requires significant rework
Deferred Requires additional research or consultation

Error Correction Procedures

Error Classification

Severity Description Response Time Example
Critical Incorrect issur/heter 24 hours Encoding forbidden as permitted
High Wrong madrega 48 hours Encoding d_oraita as d_rabanan
Medium Wrong world scope 1 week Rule in wrong world
Low Documentation error 2 weeks Incorrect comment

Error Discovery Protocol

When an error is discovered:

graph TD
    A[Error Discovered] --> B{Severity?}

    B -->|Critical| C[Immediate revert or fix]
    B -->|High| D[Open priority issue]
    B -->|Medium| E[Open standard issue]
    B -->|Low| F[Add to backlog]

    C --> G[Notify stakeholders]
    D --> G
    G --> H[Post-mortem analysis]

    H --> I[Update guidelines if needed]
    H --> J[Add test case to prevent recurrence]

Error Report Template

## Halachic Error Report

**Severity**: [Critical/High/Medium/Low]

**Location**: mistaber/ontology/worlds/mechaber.lp:143

**Rule ID**: r_bb_dag_sakana

**Error Description**:
The rule incorrectly encodes fish+dairy as issur d_oraita instead
of sakana (which is not an issur category but a health concern).

**Correct Interpretation**:
Per Beit Yosef, the prohibition is due to danger (sakana), not
a halachic issur. This distinction affects bitul and other rules.

**Current Encoding**:
```prolog
asserts(mechaber, issur(achiila, M, d_oraita)) :-  % WRONG
    is_dag_chalav_mixture(M).

Corrected Encoding: 

asserts(mechaber, sakana(M)) :-                    % CORRECT
    is_dag_chalav_mixture(M).

asserts(mechaber, issur(achiila, M, sakana)) :-    % CORRECT
    is_dag_chalav_mixture(M).

Source Justification: - Beit Yosef YD 87: "...mitchavel mi-devarim hamazikinim..." - Shach 87:5: Clarifies sakana is distinct category

Tests Affected: - test_fish_dairy_mechaber.py - test_sakana_rules.py

Reporter: @username Date: 2026-01-25 ```

Post-Error Analysis

After every Critical or High severity error:

  1. Root Cause Analysis
  2. Why was the error introduced?
  3. Why was it not caught in review?

  4. What tests would have caught it?

  5. Process Improvement

  6. Add missing test case
  7. Update verification checklist

  8. Add to reviewer training

  9. Documentation Update

  10. Add to "Common Mistakes" section
  11. Update relevant guidelines
  12. Create example of correct pattern

Accuracy Metrics

Tracking Encoding Quality

Metric Target Measurement
Error rate < 1% of rules Errors discovered / Total rules
Review pass rate > 80% first attempt Approvals / Submissions
Source citation depth >= 3 sources Average makor count per rule
Expert review compliance 100% for d_oraita Reviews completed / Required

Quality Gates

Encoding must pass these gates before merge:

  1. Automated Type Check: No errors, no warnings
  2. Test Coverage: Minimum thresholds met
  3. Source Verification: At least 2 sources cited
  4. Human Review: At least 1 technical reviewer
  5. Expert Review: Required for d_oraita content

Common Accuracy Mistakes

Mistake 1: Confusing Madrega Levels

D'oraita vs D'rabanan

The madrega level fundamentally affects safek resolution and other halachic logic.

```prolog % WRONG - of+chalav is NOT d_oraita madrega(r_bb_of_achiila, d_oraita).

% CORRECT - of+chalav is explicitly d_rabanan per SA 87:3 madrega(r_bb_of_achiila, d_rabanan). ```

Mistake 2: Conflating Issur and Sakana

Sakana is a Separate Category

Sakana (danger) is not the same as issur (prohibition).

```prolog % WRONG - sakana is not an issur madrega asserts(mechaber, issur(achiila, M, d_rabanan)) :- is_dag_chalav_mixture(M).

% CORRECT - sakana is its own category asserts(mechaber, sakana(M)) :- is_dag_chalav_mixture(M).

asserts(mechaber, issur(achiila, M, sakana)) :- is_dag_chalav_mixture(M). ```

Mistake 3: Missing Rema Disagreement

Always Check for Rema Gloss

A missing Rema check can lead to encoding only one tradition.

```prolog % INCOMPLETE - only mechaber encoded asserts(mechaber, sakana(M)) :- is_dag_chalav_mixture(M).

% COMPLETE - rema override also encoded override(rema, sakana(M), no_sakana) :- is_dag_chalav_mixture(M). asserts(rema, heter(achiila, M)) :- is_dag_chalav_mixture(M). ```

Mistake 4: Overgeneralizing Rules

Encode Only What the Source States

Do not extend rules beyond their explicit scope.

```prolog % WRONG - overgeneralized (includes non-kosher animals) asserts(mechaber, issur(achiila, M, d_oraita)) :- has_meat(M), has_dairy(M).

% CORRECT - limited to kosher beheima as per source asserts(mechaber, issur(achiila, M, d_oraita)) :- is_beheima_chalav_mixture(M). % Defined to include only kosher ```