Skip to content

Getting Started with Encoding

This guide walks you through setting up the mistaber-skills Claude Code plugin and starting your first encoding session. By the end, you'll understand the complete workflow and be ready to encode halachic content into Mistaber.

Prerequisites

Before starting, ensure you have:

  • Claude Code installed and configured (see Anthropic documentation)
  • Mistaber repository cloned locally with a working development environment
  • Python 3.11+ with the Mistaber package installed
  • Basic familiarity with HLL syntax (see HLL Language Reference)

Step 1: Install the mistaber-skills Plugin

The mistaber-skills plugin provides the skills, hooks, and templates needed for the encoding workflow.

Clone the Plugin

# Create plugins directory if it doesn't exist
mkdir -p ~/.claude/plugins

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

Verify Installation

After installation, the plugin directory should contain:

~/.claude/plugins/mistaber-skills/
├── .claude-plugin/
│   └── plugin.json            # Plugin manifest
├── skills/
│   ├── corpus-prep/           # Source text preparation
│   ├── hll-encode/            # Rule encoding
│   ├── validate/              # Compilation and testing
│   ├── review/                # Review package assembly
│   ├── commit/                # Git finalization
│   └── workflow-guide/        # Overview skill
├── hooks/
│   ├── session-init.yaml      # Load workflow state
│   ├── phase-gate.yaml        # Enforce phase ordering
│   ├── encoding-guard.yaml    # Validate HLL content
│   ├── sefaria-logger.yaml    # Log source fetches
│   ├── validation-handler.yaml # Parse test results
│   ├── checkpoint-enforcement.yaml # Ensure approvals
│   └── git-commit-guard.yaml  # Require review
├── agents/
│   └── encoding-orchestrator.md
└── templates/
    ├── corpus-report.md
    ├── encoding-report.md
    └── review-package.md

Enable the Plugin

Claude Code should automatically detect plugins in ~/.claude/plugins/. Verify the plugin is loaded:

# In Claude Code, the skills should be available
# You can invoke them directly or ask about the workflow

Step 2: Configure Sefaria MCP Server

The encoding workflow uses the Sefaria MCP (Model Context Protocol) server to fetch halachic source texts directly from the Sefaria library.

Install the Sefaria MCP Server

# Using uvx (recommended)
uvx sefaria-mcp

# Or install globally
pip install sefaria-mcp

Configure Claude Code MCP

Add the Sefaria server to your Claude Code MCP configuration. Create or edit ~/.claude/mcp_config.json:

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

Verify Sefaria Tools

Once configured, these Sefaria tools become available:

Tool Purpose
get_text Fetch text by reference (Hebrew + English)
get_english_translations Get all translation versions
get_links_between_texts Find cross-references and commentaries
text_search Full-text search across library
english_semantic_search Conceptual similarity search
search_in_book Search within specific text
search_in_dictionaries Look up technical terms
get_topic_details Get topic information
clarify_name_argument Validate and complete references
get_text_or_category_shape Get text structure

Test the Configuration

User: "Use the Sefaria MCP to fetch Shulchan Arukh, Yoreh De'ah 87:1"

You should see the Hebrew and English text of the seif returned.

Step 3: Understand the Workflow Phases

The encoding workflow consists of five sequential phases, each with specific inputs, outputs, and checkpoint requirements.

Phase 1: Corpus Preparation

Skill: mistaber:corpus-prep

Purpose: Fetch and organize all source texts needed to encode a seif.

Activities:

  1. Validate the seif reference
  2. Fetch primary text (Shulchan Aruch) in Hebrew and English
  3. Fetch commentaries (Shach, Taz, Rema gloss, etc.)
  4. Build the derivation chain (SA → Tur → Rambam → Gemara → Torah)
  5. Identify all machloket (disputes) between authorities
  6. Generate questions for human review
  7. Score encoding complexity

Artifacts Generated:

  • corpus-report-YD-{siman}-{seif}.md - Human-readable summary
  • corpus-sources-YD-{siman}-{seif}.yaml - Machine-readable sources
  • corpus-chain-YD-{siman}-{seif}.mermaid - Visual derivation chain
  • corpus-questions-YD-{siman}-{seif}.yaml - Questions for human

Checkpoint 1 Criteria:

  • [ ] Primary source text accurate and complete
  • [ ] TIER 1 commentaries fetched and classified
  • [ ] Derivation chain reaches authoritative source
  • [ ] All machloket identified with both positions
  • [ ] Questions formulated for ambiguities

Phase 2: HLL Encoding

Skill: mistaber:hll-encode

Purpose: Transform the approved corpus into formal HLL/ASP rules.

Activities:

  1. Load approved corpus and ontology context
  2. Map atomic statements to predicates
  3. Generate base world rules (universal rulings)
  4. Generate world-specific rules (Mechaber, Rema)
  5. Encode machloket with override mechanism
  6. Attach makor chains to all rules
  7. Run pre-compile validation

Artifacts Generated:

  • Updates to mistaber/ontology/corpus/yd_{siman}/base.lp - Shared definitions
  • Updates to mistaber/ontology/worlds/*.lp - World-specific rules
  • encoding-report-YD-{siman}-{seif}.md - Human-readable summary
  • encoding-mapping-YD-{siman}-{seif}.yaml - Statement-to-rule mapping
  • encoding-validation-YD-{siman}-{seif}.yaml - Pre-compile results

Checkpoint 2 Criteria:

  • [ ] All atomic statements have corresponding rules
  • [ ] Predicates correctly chosen and applied
  • [ ] World scoping accurate
  • [ ] Machloket properly encoded with both positions
  • [ ] Makor chain complete for all rules
  • [ ] Pre-compile validation passes

Phase 3: Validation

Skill: mistaber:validate

Purpose: Compile rules and verify correctness through automated testing.

Activities:

  1. Compile HLL to ASP
  2. Test grounding with Clingo
  3. Verify satisfiability (SAT/UNSAT)
  4. Run semantic validation checks
  5. Execute generated test scenarios
  6. Verify machloket encoding (both positions derivable)
  7. Run regression tests on all existing rules

Artifacts Generated:

  • validation-report-YD-{siman}-{seif}.md - Results summary
  • validation-results-YD-{siman}-{seif}.yaml - Machine-readable results
  • test-scenarios-YD-{siman}-{seif}.yaml - Test cases
  • performance-metrics-YD-{siman}-{seif}.yaml - Timing data

Checkpoint 3 Criteria:

  • [ ] Compilation successful (no syntax errors)
  • [ ] Program is SAT (no contradictions)
  • [ ] All semantic checks pass
  • [ ] All generated tests pass
  • [ ] Machloket verification correct
  • [ ] No regression failures

Phase 4: Review

Skill: mistaber:review

Purpose: Assemble comprehensive review package for final human approval.

Activities:

  1. Create executive summary
  2. Present source verification with texts
  3. Display encoded rules with highlighting
  4. Show validation evidence
  5. Present halachic accuracy checklist
  6. Present technical accuracy checklist
  7. Enable interactive query testing

Artifacts Generated:

  • review-package-YD-{siman}-{seif}.md - Complete review document

Checkpoint 4 Criteria:

  • [ ] Halachic accuracy checklist complete
  • [ ] Technical accuracy checklist complete
  • [ ] Interactive queries behave as expected
  • [ ] All questions answered or documented
  • [ ] Ready for permanent inclusion

Phase 5: Commit

Skill: mistaber:commit

Purpose: Finalize and commit approved encoding to the repository.

Activities:

  1. Verify all checkpoints cleared
  2. Run final validation
  3. Organize files in correct locations
  4. Update siman manifest
  5. Archive session artifacts
  6. Create git commit with conventional message
  7. Update progress tracking
  8. Suggest next seif to encode

Artifacts Generated:

  • Git commit with full metadata
  • Updated siman manifest
  • Archived session in docs/encoding-sessions/

No checkpoint - commit is the final action after all approvals.

Step 4: Start Your First Encoding Session

Let's walk through starting an actual encoding session.

Choose a Target Seif

For your first encoding, choose a seif that is:

  • Simple: Low machloket count, clear ruling
  • Self-contained: Minimal dependencies on other seifim
  • Accessible: Familiar halachic content

Recommended first targets:

  • YD 87:1 - Basic beheima (domesticated animal) + chalav prohibition
  • YD 89:1 - Waiting time after meat (simpler structure)

Invoke the Corpus Preparation Skill

Start the workflow by requesting corpus preparation:

User: "Prepare corpus for YD 87:1"

The corpus-prep skill will:

  1. Validate the reference "Shulchan Arukh, Yoreh De'ah 87:1"
  2. Fetch the primary text from Sefaria
  3. Fetch commentaries (Shach, Taz, Rema)
  4. Build the derivation chain
  5. Present artifacts for your review

Review the Corpus

You'll receive:

  1. Corpus Report - Read this carefully to understand:
  2. The primary text and translation
  3. Commentary classifications
  4. Machloket identification

  5. Derivation chain visualization

  6. Questions - Answer any questions the skill has generated: 

    questions:
  - id: q1
    question: "Does 'beheima' include all domesticated animals?"
    options:
      - "All domesticated kosher animals"
      - "Only cattle specifically"
    default: 0

Approve the Checkpoint

Once satisfied with the corpus, approve it:

User: "Approved - corpus looks correct. Beheima includes all domesticated kosher animals."

Continue Through the Pipeline

After each checkpoint approval, the workflow progresses:

User: "Encode the rules"         # Invokes hll-encode skill
[Review encoding-report.md]
User: "Approved - encoding looks correct"

User: "Run validation"           # Invokes validate skill
[Review validation-report.md]
User: "Approved - all tests pass"

User: "Prepare review"           # Invokes review skill
[Complete checklists in review-package.md]
User: "Approved - checklists complete"

User: "Commit the encoding"      # Invokes commit skill
[Encoding committed to repository]

Step 5: Resuming Sessions

If you need to pause work, the session state is preserved.

Check Session State

The current state is stored in .mistaber-session.yaml:

current_phase: hll-encode
target_seif: "YD:87: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

Resume the Session

User: "Resume encoding session"

The workflow-guide skill will: 1. Read the session state 2. Report the current phase 3. Continue from where you left off

Clean Start

To abandon a session and start fresh:

User: "Start new encoding session for YD 87:3"

This archives the previous session and begins a new one.

What to Expect at Each Checkpoint

Checkpoint 1 (After Corpus Preparation)

You'll review:

  • Source texts - Are they accurate? Complete?
  • Derivation chain - Does it reach Torah/Rabbinic source?
  • Machloket - Are all opinions captured?
  • Questions - Answer any ambiguities

Common issues:

  • Missing commentary that affects the ruling
  • Incomplete derivation chain
  • Unidentified machloket

Checkpoint 2 (After HLL Encoding)

You'll review:

  • Rule accuracy - Do rules match the source?
  • Predicate usage - Are predicates appropriate?
  • World scoping - Correct assignment of opinions?
  • Makor chains - Complete source attribution?

Common issues:

  • Wrong predicate selected
  • Rule in wrong world
  • Missing makor citation

Checkpoint 3 (After Validation)

You'll review:

  • Test results - All passing?
  • Machloket verification - Both positions derivable?
  • Regression - No existing tests broken?
  • Performance - Acceptable query times?

Common issues:

  • UNSAT (contradictory rules)
  • Failed machloket verification
  • Regression in existing rules

Checkpoint 4 (Final Review)

You'll complete:

  • Halachic checklist - 8 verification items
  • Technical checklist - 8 verification items
  • Interactive testing - Run queries to verify behavior

Common issues:

  • Checklist item unverified
  • Query produces unexpected result

Helpful Commands

Workflow Control

Command Effect
"Prepare corpus for YD XX:Y" Start new encoding session
"Resume encoding session" Continue from current phase
"What is the current phase?" Show session status
"Skip to review" NOT ALLOWED - checkpoints enforced

Checkpoint Phrases

Phrase Effect
"Approved", "Looks correct" Approve current checkpoint
"Needs changes", "Incorrect" Request revision
"Question about X" Discuss before approving

Query Testing (During Review)

from pathlib import Path
from mistaber.engine import HsrsEngine

engine = HsrsEngine(Path("mistaber/ontology"))

# Test your scenario
result = engine.analyze("""
    food(beef). food_type(beef, beheima).
    food(milk). food_type(milk, chalav).
    mixture(m1). contains(m1, beef). contains(m1, milk).
""", world="mechaber")

print([a for a in result["atoms"] if "issur" in a])

Troubleshooting

"Sefaria MCP tools not available"

  1. Verify MCP configuration in ~/.claude/mcp_config.json
  2. Check that sefaria-mcp is installed
  3. Restart Claude Code

"Phase-gate hook blocked my write"

You attempted to write to ontology files without completing the required checkpoint. Complete the current phase and get approval first.

"Unknown predicate X"

The predicate you're using isn't in the registry. Check Predicate Registry for valid predicates, or add the predicate to base.yaml if it's genuinely needed.

"Session state not found"

The .mistaber-session.yaml file is missing. Start a new session with "Prepare corpus for YD XX:Y".

Next Steps

Now that you understand the workflow:

  1. Read Corpus Preparation - Deep dive into Phase 1
  2. Study HLL Encoding - Learn rule transformation
  3. Review Predicate Registry - Know your vocabulary
  4. Try encoding YD 87:1 - Simple first target

Quick Reference Card

ENCODING WORKFLOW
=================

Phase 1: corpus-prep
  Trigger: "Prepare corpus for YD XX:Y"
  Output: corpus-report.md, corpus-sources.yaml
  Checkpoint: Source accuracy, machloket ID

Phase 2: hll-encode
  Trigger: "Encode the rules"
  Output: .lp files, encoding-report.md
  Checkpoint: Rule accuracy, world scoping

Phase 3: validate
  Trigger: "Run validation"
  Output: validation-report.md, test-scenarios.yaml
  Checkpoint: Test passing, no regression

Phase 4: review
  Trigger: "Prepare review"
  Output: review-package.md
  Checkpoint: Both checklists complete

Phase 5: commit
  Trigger: "Commit the encoding"
  Output: git commit, progress update
  No checkpoint - final action