> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modusbrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Operational skills workflow

> A comprehensive walkthrough of the compilation, approval, execution gating, audit tracking, and feedback loop phases of the ModusBrain lifecycle.

ModusBrain operational skills follow a structured, five-phase lifecycle. This workflow ensures that agent actions are safe, conformant to policies, and fully auditable. The following guide walks through a real-world **refund handling** scenario to demonstrate how agents and operators interact with these phases.

***

## Phase 1 — Compile

The compilation phase reads your unstructured company documentation—such as markdown wikis, support policies, and ticketing procedures—and compiles them into a versioned, static draft skill.

```bash theme={null}
# Optional: Ingest the raw markdown policy document into the brain first
modusbrain capture --file ./docs/refund-policy.md

# Compile the policy into a versioned draft skill runbook
modusbrain opskill compile "refund handling" \
  --risk-tier high_stakes \
  --owner support-lead
```

Every compiled operational skill version captures three core layers:

* **Prose Judgment** — Semantic, context-aware guidelines extracted from natural language text to steer agent behavior in complex scenarios.
* **Structured Policy Rules** — Executable logic constraints (e.g. `if amount < 500 => auto_approve`) parsed from documentation to enforce strict boundaries.
* **Lineage and Provenance** — A secure mapping back to the source files, compiler identity, and timestamps.

***

## Phase 2 — Approve

When an operational skill is newly compiled, it is held in a `draft` status. Active agents are restricted from executing draft skills until an owner promotes them:

```bash theme={null}
# Display the details and version history of the compiled skill
modusbrain opskill show refund-handling

# Approve the draft version, making it the active version for runtime execution
modusbrain opskill approve refund-handling --by alice@company.com
```

### Approval Tokens

For high-stakes tasks that fall below the automatic confidence threshold, operators can issue a temporary 1-hour approval token to safely override the gate:

```bash theme={null}
modusbrain opskill approve-token refund-handling
```

***

## Phase 3 — Execute (with Gating)

During agent runtime, the agent requests the execution of an active operational skill. ModusBrain evaluates the request against the active policy parameters and calculates a confidence score:

```bash theme={null}
modusbrain opskill execute refund-handling \
  --task "Process $300 refund for order #4521" \
  --context '{"amount":300}'
```

The execution query is allowed or blocked based on its risk tier threshold:

| Risk Tier       | Confidence Threshold | Action if Below Threshold                                                           |
| :-------------- | :------------------: | :---------------------------------------------------------------------------------- |
| `informational` |       **0.50**       | Warnings are logged for analysis, and execution is permitted to proceed.            |
| `low_stakes`    |       **0.70**       | Execution is blocked unless a force flag is set.                                    |
| `high_stakes`   |       **0.85**       | Hard-blocked; execution is refused unless a valid human approval token is provided. |

***

## Phase 4 — Audit

ModusBrain logs all execution attempts and outcomes to a secure, queryable audit ledger. This allows organizations to monitor compliance and debug agent decisions:

```bash theme={null}
modusbrain opskill audit --slug refund-handling --json
```

Audit entries record the executing agent's identifier, the specific skill version used, calculated confidence scores, parameters evaluated, and the final output.

***

## Phase 5 — Feedback Loop

If an agent action is incorrect or needs refinement, operators submit corrections. This writes feedback files back to the database, which influences subsequent skill compilations:

```bash theme={null}
modusbrain opskill correct refund-handling \
  --original "auto_approve" \
  --correction "Amounts over $400 require manager sign-off" \
  --by bob@company.com
```

***

## Conflict Handling

If multiple source documents contain contradicting instructions, ModusBrain flags the conflict in the review queue to prevent execution issues:

```bash theme={null}
# Flag a conflict manually for owner review
modusbrain opskill flag-conflict refund-handling \
  --description "Policy docs disagree on the $500 threshold" \
  --sources wiki/policies/refund-policy,wiki/policies/old-refund

# Resolve the conflict and trigger automatic re-compilation of a new draft
modusbrain opskill resolve 1 --by alice@company.com --note "Use the newer $400 threshold"
```