Skills Overview¶

The Mistaber encoding plugin provides six specialized skills that guide the AI through the complete halachic encoding pipeline. Each skill handles a specific phase of the encoding process, with mandatory human checkpoints ensuring quality and accuracy.

Skill Architecture¶

graph TB
    subgraph "Encoding Pipeline Skills"
        direction LR
        CP[corpus-prep] -->|Checkpoint 1| HE[hll-encode]
        HE -->|Checkpoint 2| VA[validate]
        VA -->|Checkpoint 3| RE[review]
        RE -->|Checkpoint 4| CO[commit]
    end

    subgraph "Documentation Skill"
        WG[workflow-guide]
    end

    WG -.->|Documents| CP
    WG -.->|Documents| HE
    WG -.->|Documents| VA
    WG -.->|Documents| RE
    WG -.->|Documents| CO

The Six Skills¶

1. Corpus Preparation (`corpus-prep`)¶

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

Checkpoint: Source Review (Checkpoint 1)

Aspect	Details
Phase	1 of 5
Trigger Phrases	"prepare corpus", "fetch sources", "start encoding", "begin encoding"
Prerequisites	Sefaria MCP available, valid seif reference
Outputs	corpus-report.md, corpus-sources.yaml, corpus-chain.mermaid, corpus-questions.yaml
Requires Approval	Yes - before proceeding to encoding

Full Documentation

2. HLL Encoding (`hll-encode`)¶

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

Checkpoint: Rule Review (Checkpoint 2)

Aspect	Details
Phase	2 of 5
Trigger Phrases	"encode rules", "write HLL", "create ASP rules", "translate to HLL"
Prerequisites	Checkpoint 1 approved, corpus artifacts available
Outputs	base.lp (shared), world-specific .lp files, encoding-report.md, encoding-mapping.yaml
Requires Approval	Yes - before proceeding to validation

Full Documentation

3. Validation (`validate`)¶

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

Checkpoint: Test Review (Checkpoint 3)

Aspect	Details
Phase	3 of 5
Trigger Phrases	"validate encoding", "run tests", "compile rules", "check rules"
Prerequisites	Checkpoint 2 approved, encoded .lp files exist
Outputs	validation-report.md, validation-results.yaml, test-scenarios.yaml
Requires Approval	Yes - before proceeding to review

Full Documentation

4. Review (`review`)¶

Purpose: Assemble comprehensive review package for final human approval.

Checkpoint: Final Approval (Checkpoint 4)

Aspect	Details
Phase	4 of 5
Trigger Phrases	"review encoding", "prepare review", "final review", "create review package"
Prerequisites	Checkpoint 3 approved, all tests passing
Outputs	review-package.md (comprehensive)
Requires Approval	Yes - before proceeding to commit

Full Documentation

5. Commit (`commit`)¶

Purpose: Finalize and commit approved encoding to the repository.

Checkpoint: None (Terminal Skill)

Aspect	Details
Phase	5 of 5
Trigger Phrases	"commit encoding", "finalize encoding", "save encoding", "complete encoding"
Prerequisites	All checkpoints (1-4) approved
Outputs	Git commit, updated manifest, archived session
Requires Approval	N/A - all approvals already obtained

Full Documentation

6. Workflow Guide (`workflow-guide`)¶

Purpose: Provide comprehensive documentation of the entire encoding pipeline.

Checkpoint: None (Documentation Only)

Aspect	Details
Phase	N/A
Trigger Phrases	"how does encoding work", "what is the workflow", "explain pipeline"
Prerequisites	None
Outputs	None (informational only)
Requires Approval	N/A

Full Documentation

Skill Invocation¶

Invocation Patterns¶

Skills are invoked automatically when the AI recognizes trigger phrases in user messages:

User: "Prepare corpus for YD 87:3"
→ corpus-prep skill invoked

User: "Encode the rules"
→ hll-encode skill invoked

User: "Run validation"
→ validate skill invoked

User: "Prepare the review package"
→ review skill invoked

User: "Commit the encoding"
→ commit skill invoked

Explicit Invocation¶

Skills can be explicitly invoked using the plugin prefix:

User: "Use mistaber:corpus-prep for YD 87:3"
User: "Invoke mistaber:validate"

Invocation via Orchestrator¶

The encoding-orchestrator agent coordinates all skills automatically:

User: "Encode YD 87:3"
→ encoding-orchestrator activates
→ Guides through corpus-prep → hll-encode → validate → review → commit
→ Pauses at each checkpoint for human approval

Skill Dependencies¶

Linear Pipeline¶

Skills form a strict linear pipeline with checkpoint enforcement:

graph LR
    A[Start] --> B{corpus-prep}
    B -->|Checkpoint 1| C{hll-encode}
    C -->|Checkpoint 2| D{validate}
    D -->|Checkpoint 3| E{review}
    E -->|Checkpoint 4| F{commit}
    F --> G[Complete]

    style B fill:#90EE90
    style C fill:#87CEEB
    style D fill:#DDA0DD
    style E fill:#F0E68C
    style F fill:#98FB98

Checkpoint Requirements¶

Transition	Requires
Start → corpus-prep	None
corpus-prep → hll-encode	Checkpoint 1 approved
hll-encode → validate	Checkpoint 2 approved
validate → review	Checkpoint 3 approved
review → commit	Checkpoint 4 approved

Hook Enforcement¶

The phase-gate hook enforces dependencies:

# Attempting hll-encode without corpus-prep approval
# → BLOCKED: Checkpoint Not Approved

# Attempting commit without review approval
# → BLOCKED: Review Not Approved

Skill Artifacts¶

Artifacts by Phase¶

Phase	Working Artifacts	Final Output
corpus-prep	corpus-report.md, corpus-sources.yaml, corpus-chain.mermaid, corpus-questions.yaml	-
hll-encode	encoding-report.md, encoding-mapping.yaml	corpus/yd_{siman}/base.lp, worlds/*.lp
validate	validation-report.md, validation-results.yaml, test-scenarios.yaml	-
review	review-package.md	-
commit	-	Git commit, manifest update

Artifact Locations¶

.mistaber-artifacts/                    # Working artifacts
├── corpus-report-YD-{siman}-{seif}.md
├── corpus-sources-YD-{siman}-{seif}.yaml
├── corpus-chain-YD-{siman}-{seif}.mermaid
├── corpus-questions-YD-{siman}-{seif}.yaml
├── encoding-report-YD-{siman}-{seif}.md
├── encoding-mapping-YD-{siman}-{seif}.yaml
├── validation-report-YD-{siman}-{seif}.md
├── validation-results-YD-{siman}-{seif}.yaml
├── test-scenarios-YD-{siman}-{seif}.yaml
├── review-package-YD-{siman}-{seif}.md
└── source-chain-log.yaml

mistaber/ontology/                      # Final output
├── corpus/yd_{siman}/
│   ├── base.lp                         # Shared definitions
│   └── manifest.yaml                   # Siman metadata
├── worlds/
│   ├── mechaber.lp                     # Updated with new rules
│   └── rema.lp                         # Updated with new rules
└── tests/yd_{siman}/
    ├── seif_{seif}_test.yaml
    └── seif_{seif}_metadata.yaml

docs/encoding-sessions/                 # Archive
└── yd_{siman}_{seif}_{date}/
    └── [all working artifacts]

Session State Integration¶

State Tracking¶

Each skill updates .mistaber-session.yaml:

current_phase: hll-encode
target_seif: "YD:87:3"
started: 2026-01-25T10:00:00Z
checkpoints:
  corpus-prep:
    status: approved
    approved_by: human
    timestamp: 2026-01-25T10:30:00Z
    artifacts:
      - .mistaber-artifacts/corpus-report-YD-87-3.md
    complexity_score: 6

  hll-encode:
    status: pending_review
    artifacts:
      - mistaber/ontology/corpus/yd_87/base.lp

  validate:
    status: not_started

  review:
    status: not_started

Status Values¶

Status	Meaning
`not_started`	Phase not yet begun
`in_progress`	Phase actively executing
`pending_review`	Awaiting human approval
`approved`	Human approved, can proceed
`tests_passed`	(validate only) Tests completed successfully
`tests_failed`	(validate only) Tests have failures

Skill Communication¶

Inter-Skill Data Flow¶

Skills communicate through artifacts:

graph TD
    CP[corpus-prep] -->|corpus-sources.yaml| HE[hll-encode]
    CP -->|corpus-questions.yaml| HE
    HE -->|*.lp files| VA[validate]
    HE -->|encoding-mapping.yaml| VA
    CP -->|All artifacts| RE[review]
    HE -->|All artifacts| RE
    VA -->|All artifacts| RE
    RE -->|review-package.md| CO[commit]

Template System¶

Skills use templates from templates/:

Template	Used By	Purpose
corpus-report.md	corpus-prep	Human-readable source summary
encoding-report.md	hll-encode	Encoding summary
validation-report.md	validate	Test results summary
review-package.md	review	Complete review package

Best Practices¶

Starting an Encoding Session¶

Verify prerequisites:
Sefaria MCP available
Mistaber engine working
Clingo installed
Start with corpus-prep:
```
User: "Prepare corpus for YD 87:3"
```
Review thoroughly at each checkpoint:
Don't rush approvals
Answer all questions
Verify source accuracy

Handling Revisions¶

If issues are found after approval:

Minor fixes: Request revision

User: "Needs revision: Rule r_bb_dag_sakana should use sakana/1 not sakana/2"

Major issues: May need to return to earlier phase

User: "Reject - source interpretation is incorrect"

Resuming Sessions¶

User: "Resume encoding YD 87:3"

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

Quick Reference¶

Trigger Phrase Summary¶

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

Checkpoint Approval Phrases¶

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

Skills Overview¶

Skill Architecture¶

The Six Skills¶

1. Corpus Preparation (corpus-prep)¶

2. HLL Encoding (hll-encode)¶

3. Validation (validate)¶

4. Review (review)¶

5. Commit (commit)¶

6. Workflow Guide (workflow-guide)¶

Skill Invocation¶

Invocation Patterns¶

Explicit Invocation¶

Invocation via Orchestrator¶

Skill Dependencies¶

Linear Pipeline¶

Checkpoint Requirements¶

Hook Enforcement¶

Skill Artifacts¶

Artifacts by Phase¶

Artifact Locations¶

Session State Integration¶

State Tracking¶

Status Values¶

Skill Communication¶

Inter-Skill Data Flow¶

Template System¶

Best Practices¶

Starting an Encoding Session¶

Handling Revisions¶

Resuming Sessions¶

Quick Reference¶

Trigger Phrase Summary¶

Checkpoint Approval Phrases¶

1. Corpus Preparation (`corpus-prep`)¶

2. HLL Encoding (`hll-encode`)¶

3. Validation (`validate`)¶

4. Review (`review`)¶

5. Commit (`commit`)¶

6. Workflow Guide (`workflow-guide`)¶