Skip to content

Workflow Guide Skill

The workflow-guide skill provides comprehensive documentation of the entire Mistaber encoding pipeline, explaining the phases, checkpoints, and best practices for systematic halachic encoding.

Overview

Attribute Value
Skill Name workflow-guide
Phase N/A (Documentation only)
Checkpoint None
Prerequisites None
Outputs None (informational)
Trigger Phrases "how does encoding work", "what is the workflow", "explain the pipeline", "encoding overview", "workflow help"

Pipeline Architecture

The Mistaber encoding pipeline transforms halachic source texts into formal logical rules through a supervised, checkpoint-based workflow.

+---------------------------------------------------------------------+
|                      ENCODING PIPELINE                               |
+---------------------------------------------------------------------+
|                                                                      |
|  +----------------+    +----------------+    +----------------+      |
|  |   SKILL 1      |--->|   SKILL 2      |--->|   SKILL 3      |      |
|  | corpus-prep    |    | hll-encode     |    |  validate      |      |
|  +-------+--------+    +-------+--------+    +-------+--------+      |
|          |                     |                     |               |
|    [CHECKPOINT 1]        [CHECKPOINT 2]        [CHECKPOINT 3]        |
|    Human reviews         Human reviews         Human reviews         |
|    source chain          encoded rules         test results          |
|                                                                      |
|  +----------------+    +----------------+                            |
|  |   SKILL 4      |--->|   SKILL 5      |                            |
|  |   review       |    |   commit       |                            |
|  +-------+--------+    +----------------+                            |
|          |                                                           |
|    [CHECKPOINT 4]                                                    |
|    Final approval                                                    |
+---------------------------------------------------------------------+

The Five Skills

Skill 1: Corpus Preparation

Purpose: Fetch and organize source texts from Sefaria, build complete derivation chains.

Invocation: mistaber:corpus-prep

Key Activities:

  1. Validate seif reference with Sefaria
  2. Fetch primary text (Hebrew + English)
  3. Fetch commentaries (Shach, Taz, etc.)
  4. Build derivation chain (SA -> Tur -> Rambam -> Gemara -> Torah)
  5. Identify machloket (disputes)
  6. Generate questions for human

Artifacts:

Artifact Purpose
corpus-report.md Human-readable summary
corpus-sources.yaml Machine-readable data
corpus-chain.mermaid Visual derivation chain
corpus-questions.yaml Questions for human

Checkpoint 1: Human reviews source chain, answers questions, approves corpus.

Skill 2: HLL Encoding

Purpose: Transform approved corpus into HLL/ASP rules with proper world scoping.

Invocation: mistaber:hll-encode

Key Activities:

  1. Map statements to predicates
  2. Generate base world rules (universal)
  3. Generate world-specific rules (Mechaber, Rema)
  4. Encode machloket with override mechanism
  5. Attach makor chains to all rules
  6. Pre-compile validation

Artifacts:

Artifact Purpose
base.lp Shared definitions
mechaber.lp Mechaber-specific rules
rema.lp Rema-specific rules
encoding-report.md Encoding summary
encoding-mapping.yaml Statement-rule mapping

Checkpoint 2: Human reviews encoded rules, verifies world scoping, approves encoding.

Skill 3: Validation

Purpose: Compile rules, run semantic checks, execute test scenarios.

Invocation: mistaber:validate

Key Activities:

  1. HLL compilation
  2. ASP grounding test
  3. Satisfiability check (SAT/UNSAT)
  4. Semantic validation (disjointness, inheritance)
  5. Generated test execution
  6. Machloket verification
  7. Regression testing

Artifacts:

Artifact Purpose
validation-report.md Test results summary
validation-results.yaml Machine-readable results
test-scenarios.yaml Test scenarios for regression

Checkpoint 3: Human reviews test results, verifies all tests pass, approves validation.

Skill 4: Review

Purpose: Assemble comprehensive review package for final human approval.

Invocation: mistaber:review

Key Activities:

  1. Assemble executive summary
  2. Present source verification
  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:

Artifact Purpose
review-package.md Complete review package

Checkpoint 4: Human completes both checklists, tests queries, gives final approval.

Skill 5: Commit

Purpose: Finalize and commit approved encoding to repository.

Invocation: mistaber:commit

Key Activities:

  1. Verify all checkpoints cleared
  2. Final validation run
  3. Organize files
  4. Update manifest
  5. Archive session artifacts
  6. Create git commit
  7. Update progress tracking
  8. Suggest next steps

Artifacts:

Output Purpose
Git commit Version-controlled changes
Manifest update Siman metadata
Session archive Historical record

No checkpoint: Commit is the final action after all approvals.

Checkpoint Requirements

What Checkpoints Enforce

Checkpoint Phase Blocks Until
1 Corpus Human approves source chain and answers questions
2 Encode Human approves rule encoding and world scoping
3 Validate Human approves test results (all pass)
4 Review Human completes both checklists

Checkpoint Flow

corpus-prep --- CHECKPOINT 1 ---> hll-encode --- CHECKPOINT 2 --->
                    |                                |
                    v                                v
           "Approve corpus?"              "Approve encoding?"
                    |                                |
                   YES                              YES
                    |                                |
                    v                                v
              Continue                          Continue

validate --- CHECKPOINT 3 ---> review --- CHECKPOINT 4 ---> commit
                 |                            |
                 v                            v
        "Approve tests?"          "Final approval?"
                 |                            |
                YES                          YES
                 |                            |
                 v                            v
            Continue                     COMMIT!

Checkpoint Approval Phrases

Phrase Effect
"Approved" Approve current checkpoint
"Looks good" Approve current checkpoint
"Correct" Approve current checkpoint
"Needs revision: [feedback]" Request changes
"Reject: [reason]" Cancel session

Starting an Encoding Session

Step 1: Invoke Corpus Preparation

User: "Prepare corpus for YD 88:1"

The agent invokes corpus-prep, which will:

  1. Validate the reference
  2. Fetch texts from Sefaria
  3. Build derivation chain
  4. Generate artifacts
  5. Request checkpoint approval

Step 2: Review and Approve Corpus

Review the generated artifacts:

  • Check source accuracy
  • Answer questions in corpus-questions.yaml
  • Verify derivation chain
User: "Approved - corpus looks correct"

Step 3: Continue Through Pipeline

Each subsequent skill is invoked after approval:

User: "Encode the rules"         -> hll-encode skill
User: "Run validation"           -> validate skill
User: "Prepare review"           -> review skill
User: "Commit the encoding"      -> commit skill

Session State Management

Session State File

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

current_phase: hll-encode
target_seif: "YD:88:1"
started: 2026-01-25T10:00:00Z
last_activity: 2026-01-25T14: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

Session Resumption

If a session is interrupted:

User: "Resume encoding YD 88:1"

The system reads .mistaber-session.yaml and continues from the current phase.

Workflow Violations

The hook system prevents workflow violations:

Violation Prevention Hook
Writing .lp without corpus approval BLOCKS phase-gate
Missing @makor in rules BLOCKS encoding-guard
Unknown predicate BLOCKS encoding-guard
Commit without validation BLOCKS git-commit-guard
Commit without review BLOCKS git-commit-guard
Skip checkpoint WARNS checkpoint-enforcement

Work Unit: Single Seif

The encoding pipeline works on one seif at a time:

Why Single Seif?

  • Small enough for thorough human review
  • Large enough to be meaningful
  • Natural halachic unit
  • Clear boundaries in source texts
  • Tractable validation scope

Example Work Units:

Reference Topic
YD 87:1 Beheima + Chalav (d'oraita)
YD 87:3 Dag Bechalav (machloket)
YD 88:1 Bitul Shishim
YD 89:1 Waiting Period

Handling Machloket

When encoding disputes:

  1. corpus-prep identifies all positions
  2. hll-encode creates:
  3. World-specific rules for each position
  4. Override mechanism for disagreements
  5. machloket/4 marker predicate
  6. validate verifies both positions are derivable
  7. review presents side-by-side comparison

Machloket World Mapping

Authority World Inherits From
All agree base -
Mechaber mechaber base
Rema rema base
Gra gra base
Yalkut Yosef sefardi_yo mechaber
Mishnah Berurah ashk_mb rema
Aruch HaShulchan ashk_ah rema, gra

Artifacts Summary

By Phase

Phase Human Review Machine Artifacts
Corpus corpus-report.md corpus-sources.yaml
Encode encoding-report.md *.lp files
Validate validation-report.md test-scenarios.yaml
Review review-package.md -
Commit - git commit

Artifact Locations

.mistaber-artifacts/              # Working (deleted after commit)
docs/encoding-sessions/           # Archive (permanent)
mistaber/ontology/corpus/         # Final ontology files
mistaber/ontology/worlds/         # World-specific rules
mistaber/ontology/tests/          # Test files

Best Practices

Before Starting

  1. Verify prerequisites:
  2. Sefaria MCP available
  3. Mistaber engine working

  4. Clingo installed

  5. Choose work unit carefully:

  6. Start with simpler seifim
  7. Consider dependencies
  8. Check complexity score

During Encoding

  1. Take time at checkpoints:
  2. Don't rush approvals
  3. Review thoroughly

  4. Ask clarifying questions

  5. Answer all questions:

  6. Corpus questions require resolution

  7. Document decisions

  8. Test interactively:

  9. Use review phase testing
  10. Verify expected behavior

After Encoding

  1. Verify commit:
  2. Check git log

  3. Review files committed

  4. Plan next encoding:

  5. Follow suggested order
  6. Consider dependencies

Quick Reference

Trigger Phrases

Skill Triggers
corpus-prep "prepare corpus", "fetch sources", "start encoding"
hll-encode "encode rules", "write HLL", "create ASP"
validate "validate", "run tests", "compile rules"
review "review", "prepare review", "final review"
commit "commit", "finalize", "save encoding"
workflow-guide "how does encoding work", "workflow help"

Command Quick Reference

# Start encoding
"Prepare corpus for YD {siman}:{seif}"

# Approve checkpoint
"Approved"

# Request changes
"Needs revision: [feedback]"

# Resume session
"Resume encoding YD {siman}:{seif}"

# Get workflow help
"What is the encoding workflow?"