Plugin Troubleshooting¶

This guide covers common issues, error messages, and their solutions when working with the Mistaber encoding plugin.

Quick Diagnostics¶

Before diving into specific issues, run these diagnostic commands:

#!/bin/bash
# quick-diagnose.sh - Run quick diagnostics

echo "=== Mistaber Plugin Diagnostics ==="

# Check session state
if [ -f ".mistaber-session.yaml" ]; then
    echo "[Session] Active session found"
    grep "current_phase:" .mistaber-session.yaml
    grep "target_seif:" .mistaber-session.yaml
else
    echo "[Session] No active session"
fi

# Check artifacts
if [ -d ".mistaber-artifacts" ]; then
    echo "[Artifacts] $(ls .mistaber-artifacts | wc -l) files in artifacts"
else
    echo "[Artifacts] No artifacts directory"
fi

# Check Python
python3 --version 2>/dev/null || echo "[Python] NOT FOUND"

# Check PyYAML
python3 -c "import yaml; print('[PyYAML] OK')" 2>/dev/null || echo "[PyYAML] NOT FOUND"

# Check Clingo
clingo --version 2>/dev/null | head -1 || echo "[Clingo] NOT FOUND"

# Check Mistaber
python3 -c "from mistaber.engine import HsrsEngine; print('[Mistaber] OK')" 2>/dev/null || echo "[Mistaber] NOT FOUND"

BLOCKED: No Active Encoding Session¶

Error Message:

BLOCKED: No Active Encoding Session

Cannot write to ontology file: mistaber/ontology/corpus/yd_87/base.lp

You must start an encoding session first:
1. Invoke the corpus-prep skill
2. Complete corpus preparation
3. Get human approval at checkpoint

Start with: "Prepare corpus for YD {siman}:{seif}"

Cause: The phase-gate hook detected an attempt to write to ontology files without an active encoding session.

Solutions:

Start a proper encoding session:
```
User: "Prepare corpus for YD 87:3"
```

If session exists but state is corrupted:

# Check session state
cat .mistaber-session.yaml

# Reset if needed (caution: loses progress)
rm .mistaber-session.yaml

If writing non-ontology files: Verify the file path does not match the ontology pattern (*ontology*corpus*.lp).

BLOCKED: Checkpoint Not Approved¶

Error Message:

BLOCKED: Checkpoint Not Approved

Cannot write to: mistaber/ontology/corpus/yd_87/seif_3.lp

Required checkpoint: corpus-prep
Current status: pending_review

The encoding workflow requires human approval at each checkpoint.
Complete the corpus-prep phase and get approval before proceeding.

Cause: The phase-gate hook detected an attempt to proceed past an unapproved checkpoint.

Solutions:

Review and approve the pending checkpoint:

User: "Show me the corpus preparation for review"
[Review the artifacts]
User: "Approved"

Check current checkpoint status:

grep -A 3 "corpus-prep:" .mistaber-session.yaml

If checkpoint was approved but state not updated: Manually update .mistaber-session.yaml:

checkpoints:
  corpus-prep:
    status: approved
    approved_by: human
    timestamp: "2026-01-25T12:00:00Z"

BLOCKED: HLL Encoding Validation Failed¶

Error Message:

BLOCKED: HLL Encoding Validation Failed

File: mistaber/ontology/corpus/yd_87/seif_3.lp

Issues Found:
  - Rule 'r_bb_dag_sakana' uses normative predicate but has no makor
  - Unknown world referenced: 'mechaver' (typo of 'mechaber')

Please fix these issues before writing the file.

Encoding Requirements:
- All normative rules must have @makor attribution
- All worlds must be valid (base, mechaber, rema, etc.)
- All predicates must exist in the registry

Cause: The encoding-guard hook found validation errors in the HLL content.

Solutions:

Add missing makor attribution:

rule(r_bb_dag_sakana).
makor(r_bb_dag_sakana, sa("yd:87:3")).  % Add this
scope(r_bb_dag_sakana, mechaber).

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

Fix typos in world names:

% Wrong: mechaver
% Correct: mechaber
asserts(mechaber, sakana(M)) :-
    is_dag_chalav_mixture(M).

Register new predicates if needed: Add to mistaber/ontology/schema/sorts.lp before using.

BLOCKED: Commit Without Approval¶

Error Message:

BLOCKED: Review Not Approved

Cannot commit ontology files without approved review.

Staged ontology files:
  - mistaber/ontology/corpus/yd_87/seif_3.lp
  - mistaber/ontology/worlds/mechaber.lp

Current checkpoint status:
  - corpus-prep: approved
  - hll-encode: approved
  - validate: approved
  - review: pending_review

Complete the remaining checkpoints before committing.

Cause: The git-commit-guard hook detected a commit attempt without all required approvals.

Solutions:

Complete the review checkpoint:

User: "Show me the review package"
[Review all checklists]
User: "Final approval granted"

Check which checkpoints are missing:

grep -E "status:" .mistaber-session.yaml

If committing non-ontology files: The guard only blocks when .lp files in ontology/ are staged. To commit other files:
```
git add -A -- ':!mistaber/ontology'
git commit -m "Non-ontology changes"
```

Session State Issues¶

Corrupted Session File¶

Symptoms: - Hooks produce parsing errors - Inconsistent checkpoint statuses - Skills don't recognize session state

Diagnostic:

# Validate YAML syntax
python3 -c "import yaml; yaml.safe_load(open('.mistaber-session.yaml'))"

Solutions:

Fix YAML syntax errors:

# Common issues: bad indentation, special characters
# Use a YAML linter
pip install yamllint
yamllint .mistaber-session.yaml

Reset to known good state:

# Minimal valid session
current_phase: corpus-prep
target_seif: "YD:87:3"
started: "2026-01-25T10:00:00Z"
checkpoints:
  corpus-prep:
    status: not_started
  hll-encode:
    status: not_started
  validate:
    status: not_started
  review:
    status: not_started

Complete reset (loses all progress):

rm .mistaber-session.yaml
rm -rf .mistaber-artifacts

Session State Lost Between Sessions¶

Symptoms: - Session appears new when resuming work - Previous progress not recognized

Cause: Session file not persisted or deleted.

Solutions:

Verify file persistence:
```
ls -la .mistaber-session.yaml
```

Check for gitignore:

grep mistaber .gitignore
# Remove if .mistaber-session.yaml is ignored

Add to git tracking (optional):

git add .mistaber-session.yaml
git commit -m "Track encoding session state"

Multiple Concurrent Sessions¶

Symptoms: - Session state conflicts - Unexpected checkpoint statuses

Cause: Multiple encoding sessions or concurrent users.

Solutions:

Use one session at a time: Complete or archive current session before starting new one.

Check for orphaned sessions:

find . -name ".mistaber-session.yaml" -type f

Archive completed sessions:

mkdir -p .mistaber-archive
mv .mistaber-session.yaml .mistaber-archive/session-$(date +%Y%m%d-%H%M%S).yaml

Sefaria MCP Issues¶

MCP Server Not Running¶

Symptoms: - Sefaria tool calls fail - "Connection refused" errors

Solutions:

Check MCP configuration:

cat .mcp.json
# or
cat ~/.config/claude-code/.mcp.json

Verify MCP server package:
```
npx -y @sefaria/mcp-server --help
```
Restart Claude Code session: Exit and restart to reinitialize MCP connections.

Invalid Reference Format¶

Symptoms: - "Reference not found" errors - Empty text returned

Solutions:

Validate reference format:
```
User: "Validate reference 'Yoreh Deah 87:3'"
```
Use the clarify_name_argument tool to get canonical format.

Common format issues:

Wrong: "YD 87:3"
Right: "Shulchan Arukh, Yoreh De'ah 87:3"

Wrong: "Shulchan Aruch"
Right: "Shulchan Arukh"

Check available versions: Some texts may not have English translations.

Source Logging Not Working¶

Symptoms: - source-chain-log.yaml not updated - No logging messages

Solutions:

Verify sefaria-logger hook:

grep "sefaria-logger" mistaber-skills/hooks/hooks.json

Check artifacts directory:

mkdir -p .mistaber-artifacts
ls -la .mistaber-artifacts/

Test logger manually:

python mistaber-skills/hooks/scripts/sefaria-logger.py "mcp__sefaria_texts__get_text" '{"reference": "test"}'

Validation Issues¶

UNSAT (Unsatisfiable Rules)¶

Symptoms: - Clingo returns "UNSATISFIABLE" - No answer sets found

Cause: The encoded rules contain a logical contradiction.

Solutions:

Identify conflicting rules:

clingo mistaber/ontology/corpus/yd_87/seif_3.lp --opt-mode=optN -n 0 2>&1 | grep -i unsat

Check for direct contradictions:

% Problem: Same mixture is both permitted and forbidden
asserts(base, issur(achiila, M, d_oraita)) :- ...
asserts(base, heter(achiila, M)) :- ...  % Conflict!

Check for circular negation:

% Problem: Mutual negation
a :- not b.
b :- not a.
% Without choice rule, this may be UNSAT

Use debugging output:

clingo --trace=asp mistaber/ontology/corpus/yd_87/seif_3.lp

Grounding Errors¶

Symptoms: - "Grounding error" messages - "Unsafe variable" warnings

Solutions:

Fix unsafe variables:

% Wrong: X is unsafe
asserts(W, issur(achiila, X, L)) :- world(W).

% Right: X is bound
asserts(W, issur(achiila, X, L)) :- world(W), food(X), level(L).

Check infinite recursion:

% Problem: May cause infinite grounding
related(X, Y) :- related(Y, X).

Add domain bounds:

#const max_depth = 5.
chain(X, Y, D) :- link(X, Y), D = 1.
chain(X, Y, D) :- chain(X, Z, D-1), link(Z, Y), D <= max_depth.

Test Failures¶

Symptoms: - Pytest reports failures - Unexpected query results

Solutions:

Review test expectations:

cat .mistaber-artifacts/test-scenarios-YD-87-3.yaml

Run tests verbosely:
```
pytest tests/ontology/ -v --tb=long
```

Test individual queries:

from mistaber.engine import HsrsEngine
engine = HsrsEngine(Path("mistaber/ontology"))
result = engine.query("holds(sakana(M), mechaber)")
print(result)

Check world inheritance:

# Verify base rules propagate
base_result = engine.query("asserts(base, X)")
world_result = engine.query("holds(X, mechaber)")

Encoding Issues¶

Missing Predicates¶

Symptoms: - "Unknown predicate" errors - Validation failures

Solutions:

Check predicate registry:

grep "predicate_name" mistaber/ontology/schema/sorts.lp

Add predicate definition:

% In sorts.lp
#script (python)
def predicate_info():
    return {
        "sakana": {"arity": 1, "description": "Health danger"},
        ...
    }
#end.

Update encoding-guard NORMATIVE_PREDICATES:

NORMATIVE_PREDICATES = {
    "issur": 3,
    "heter": 2,
    "chiyuv": 3,
    "sakana": 1,
    "new_predicate": 2,  # Add here
}

World Scoping Errors¶

Symptoms: - Rules not inheriting correctly - Override not taking effect

Solutions:

Verify world hierarchy:

% Check accessible/2 definitions
accessible(mechaber, base).
accessible(rema, base).
accessible(sefardi_yo, mechaber).

Check override syntax:

% Correct: Third argument is new descriptive value
override(rema, sakana(M), no_sakana) :-
    is_dag_chalav_mixture(M).

% Wrong: Using 'invalid' as third argument
override(rema, sakana(M), invalid) :- ...

Verify world exists:

grep "world(mechaber)" mistaber/ontology/worlds/kripke_rules.lp

Makor Chain Incomplete¶

Symptoms: - "Chain doesn't reach authoritative source" warnings - Missing Torah terminus

Solutions:

Complete the chain:

makor(r_bb_achiila, sa("yd:87:1")).
makor(r_bb_achiila, tur("yd:87")).
makor(r_bb_achiila, rambam("maachalot:9:1")).
makor(r_bb_achiila, gemara("chullin:104b")).
makor(r_bb_achiila, mishnah("chullin:8:1")).
makor(r_bb_achiila, torah("shemot:23:19")).  % Terminus

For d'rabanan rules:

% Rabbinic rules may terminate at Mishnah or Takana
makor(r_rule, mishnah("avot:1:1")).  % Valid terminus
makor(r_rule, takana("chazal")).     % Valid terminus

Performance Issues¶

Slow Grounding¶

Symptoms: - Validation takes >10 seconds - Timeout errors

Solutions:

Reduce rule complexity:

% Avoid: Cartesian products
combo(A, B, C) :- a(A), b(B), c(C).

% Better: Constrain early
combo(A, B, C) :- a(A), related(A, B), b(B), depends(B, C), c(C).

Use projection:
```
#project asserts/2.
#project holds/2.
```

Limit answer sets:

clingo ontology.lp -n 1  # Just find one model

Memory Issues¶

Symptoms: - "Out of memory" errors - System slowdown

Solutions:

Ground incrementally:

clingo --ground-incremental ontology.lp

Use Clingo memory limits:

clingo --configuration=frugal ontology.lp

Split large ontologies: Load only relevant portions during validation.

Debug Mode¶

Enabling Debug Output¶

For Hook Scripts:

export MISTABER_DEBUG=1

This enables verbose logging in hook scripts:

import os
DEBUG = os.environ.get("MISTABER_DEBUG", "0") == "1"

if DEBUG:
    print(f"[DEBUG] Phase gate checking: {file_path}", file=sys.stderr)

For Validation:

# Verbose Clingo output
clingo --verbose=2 ontology.lp

# Trace ASP execution
clingo --trace=asp ontology.lp

Log File Locations¶

Log	Location	Content
Session log	`.mistaber-artifacts/session.log`	Session events
Source log	`.mistaber-artifacts/source-chain-log.yaml`	Sefaria fetches
Validation log	`.mistaber-artifacts/validation.log`	Test results
Hook output	stderr	Hook debug messages

Getting Help¶

Collecting Diagnostic Information¶

#!/bin/bash
# collect-diagnostics.sh

echo "=== Mistaber Diagnostics ===" > diagnostics.txt
echo "" >> diagnostics.txt

echo "## Environment" >> diagnostics.txt
python3 --version >> diagnostics.txt 2>&1
clingo --version >> diagnostics.txt 2>&1
echo "" >> diagnostics.txt

echo "## Session State" >> diagnostics.txt
cat .mistaber-session.yaml >> diagnostics.txt 2>&1 || echo "No session" >> diagnostics.txt
echo "" >> diagnostics.txt

echo "## Recent Artifacts" >> diagnostics.txt
ls -la .mistaber-artifacts/ >> diagnostics.txt 2>&1 || echo "No artifacts" >> diagnostics.txt
echo "" >> diagnostics.txt

echo "## Plugin Structure" >> diagnostics.txt
find mistaber-skills -name "*.md" -o -name "*.json" -o -name "*.py" | head -20 >> diagnostics.txt
echo "" >> diagnostics.txt

echo "Diagnostics collected in diagnostics.txt"

Reporting Issues¶

When reporting issues, include:

Error message: Complete error output
Session state: Contents of .mistaber-session.yaml
Reproduction steps: How to trigger the issue
Environment: Python version, Clingo version, OS
Diagnostics output: Run collect-diagnostics.sh

Community Resources¶

GitHub Issues: github.com/BrainyBlaze/mistaber-skills/issues
Documentation: github.com/BrainyBlaze/mistraber/docs
Discussions: github.com/BrainyBlaze/mistraber/discussions

Plugin Troubleshooting¶

Quick Diagnostics¶

Hook-Related Issues¶

BLOCKED: No Active Encoding Session¶

BLOCKED: Checkpoint Not Approved¶

BLOCKED: HLL Encoding Validation Failed¶

BLOCKED: Commit Without Approval¶

Session State Issues¶

Corrupted Session File¶

Session State Lost Between Sessions¶

Multiple Concurrent Sessions¶

Sefaria MCP Issues¶

MCP Server Not Running¶

Invalid Reference Format¶

Source Logging Not Working¶

Validation Issues¶

UNSAT (Unsatisfiable Rules)¶

Grounding Errors¶

Test Failures¶

Encoding Issues¶

Missing Predicates¶

World Scoping Errors¶

Makor Chain Incomplete¶

Performance Issues¶

Slow Grounding¶

Memory Issues¶

Debug Mode¶

Enabling Debug Output¶

Log File Locations¶

Getting Help¶

Collecting Diagnostic Information¶

Reporting Issues¶

Community Resources¶