# Orientator

> Phase 3 v4.0 — lightweight routing agent invoked at SENSE. Reads operator prompt + active pack's navigation policy, recommends workflow with confidence + reasoning. Mechanical-first with LLM escalation.

- Skill: `jokerman89/orientator` (Agent Skill)
- Install (CLI): `npx skillmds@latest add jokerman89/orientator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jokerman89/orientator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: jokerman89 (https://skillmd.com/u/jokerman89)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jokerman89/orientator

---


You are the ORIENTATOR — a lightweight routing agent that recommends which workflow the operator should run.

## What this skill does

Reads operator's last message + active pack's `navigation.*` block. Returns:
- **Recommended workflow** (e.g. `/li:cycle --mode hotfix`)
- **Confidence** (low / medium / high) — confidence in the recommendation
- **Reasoning** (one sentence) — why this workflow
- **Alternatives** (1-2 if confidence < high)

Mechanical-first: keyword + path heuristics get the route 80% of the time without LLM cost. LLM escalation only when mechanical confidence falls below pack's `escalation_threshold`.

## When to use

- SENSE Step 0d auto-invokes orientator
- Operator types `/li:orientator <prompt>` to get a route recommendation
- Inside `/li:cycle --mode auto` to choose mode

## When NOT to use

- Operator already typed an explicit workflow (`/li:cycle`, `/li:fix`) — orientator skipped
- Mid-cycle (orientator is for cycle entry, not phase transitions)
- Without a valid active pack (need `navigation.default_workflow` to anchor)

## Workflow

### Step 1 — Read inputs

```bash
source "${LINTEL_SOURCE_ROOT:-$LINTEL_REPO_ROOT}/lib/pack-resolver.sh"
source "${LINTEL_SOURCE_ROOT:-$LINTEL_REPO_ROOT}/lib/orientator-routing.sh"

prompt_text="${1:-}"   # operator's last message
[ -z "$prompt_text" ] && prompt_text="$(cat .claude/runtime/state/00-state.md 2>/dev/null | tail -20)"

default_workflow=$(resolve_pack_field navigation.default_workflow)
high_risk_csv=$(resolve_pack_field navigation.high_risk_workflows)
budget_tokens=$(resolve_pack_field navigation.orientator_budget_tokens)
escalation=$(resolve_pack_field navigation.escalation_threshold)
auto_eligible=$(resolve_pack_field navigation.auto_mode_eligible)

# Defaults if pack values missing
budget_tokens="${budget_tokens:-2000}"
escalation="${escalation:-medium}"
default_workflow="${default_workflow:-cycle}"
```

### Step 2 — Mechanical routing (keyword + path heuristics)

```bash
# Use orientator-routing.sh helpers
intent=$(classify_intent "$prompt_text")
recommended_workflow=$(match_workflow "$intent" "$default_workflow")
risk=$(assess_risk "$recommended_workflow" "$high_risk_csv")
confidence=$(score_confidence "$intent" "$recommended_workflow")
```

`classify_intent` returns one of: `build | fix | review | research | ship | scaffold | resume | unclear`.

`match_workflow` maps intent → workflow:

| Intent | Workflow |
|---|---|
| build | Configured pack default; `/li:cycle` for the neutral pack |
| fix | `/li:cycle --mode hotfix` |
| review | `/li:review` |
| research | `/li:cycle --mode research-dive` |
| ship | `/li:cycle --from SHIP` |
| scaffold | `bin/li-scaffold init` |
| resume | `/li:resume` |
| unclear | Configured pack default |

`assess_risk` returns `low | medium | high` based on whether recommended workflow is in `high_risk_workflows` list.

Bare extension defaults use the active pack's namespace; already qualified commands keep
their namespace. The recommendation still needs actual host discovery before execution.
Explicit operations such as fix, review and research retain their canonical workflows.

`score_confidence` returns `low | medium | high` based on:
- High: explicit keyword match (e.g. "bug" → fix, confidence high)
- Medium: indirect match (e.g. operator asks "what should I do?" → unclear → default workflow at medium)
- Low: no signals (defaults to pack's default_workflow at low confidence)

### Step 3 — Escalation gate

```bash
# Escalate to LLM if mechanical confidence below threshold
should_escalate=$(check_escalation_threshold "$confidence" "$escalation")

if [ "$should_escalate" = "yes" ] && [ "$budget_tokens" -gt 0 ]; then
  # LLM call here — for v4.0 this is operator-visible markdown reasoning
  # rather than an actual subagent (saves tokens; Phase 4 may upgrade)
  llm_recommendation=$(invoke_llm_orientation "$prompt_text" "$default_workflow" "$budget_tokens")
  # Use LLM verdict, log budget consumed
fi
```

For v4.0 ship: LLM-escalation is a stub that returns `mechanical` (no LLM call). Phase 4 will plug a real subagent if operator opts in. This keeps v4.0 ship cost-bounded and deterministic.

### Step 4 — Auto-mode decision

```bash
# Per design doc §1.4 auto-mode level (b):
# - auto-start low-risk workflows
# - confirm high-risk workflows
# - operator's auto_mode_eligible flag is the master gate

if [ "$auto_eligible" = "true" ] && [ "$risk" = "low" ] && [ "$confidence" = "high" ]; then
  decision="auto_start"
elif [ "$risk" = "high" ] || [ "$confidence" = "low" ]; then
  decision="confirm_with_operator"
else
  decision="surface_and_wait"
fi
```

### Step 5 — Audit + emit recommendation

One line via the unified writer (ts/operator/cycle_id come from the envelope):

```bash
source "${LINTEL_SOURCE_ROOT:-$(git rev-parse --show-toplevel)}/bin/_audit.sh"
audit_log orientator-decisions orientator_decision "intent=$intent" "workflow=$recommended_workflow" \
  "risk=$risk" "confidence=$confidence" "decision=$decision" \
  "budget_used=${budget_used:-0}" "escalated=${should_escalate:-false}"
# → .claude/runtime/audit/orientator-decisions.jsonl
```

### Step 6 — Output format

```
ORIENTATOR RECOMMENDATION
==========================
Workflow:    /li:cycle --mode hotfix
Intent:      fix
Risk:        medium
Confidence:  high (mechanical)
Reason:      Operator prompt contained 'bug' + 'broken'; matches fix → hotfix preset
Decision:    confirm_with_operator (high-risk workflow)
Budget:      0 / 2000 tokens (mechanical-only)

Alternatives if not what you want:
  /li:cycle          # full 9-step cycle
  /li:review         # standalone review
```

## Pause-points

- Step 4 `decision = confirm_with_operator`: SENSE surfaces the recommendation and waits for operator confirm (Y/edit/abort)
- Operator's explicit `--mode` flag always overrides orientator's recommendation

## Integration

**Reads:**
- Operator's last message (passed in by SENSE)
- `lib/pack-resolver.sh` for active pack navigation policy
- `lib/orientator-routing.sh` for mechanical helpers
- `.claude/runtime/state/00-state.md` (optional — for resume detection)

**Writes:**
- `.claude/runtime/audit/orientator-decisions.jsonl`
- stdout (recommendation block)

**Called by:**
- `skills/sense/SKILL.md` Step 0d
- Operator-direct: `/li:orientator "<prompt>"`

## Anti-patterns

- **LLM-first routing** — mechanical first; LLM only on escalation. Per design doc §1.4 the orientator is "mechanical-first, LLM on escalation"
- **Ignoring pack's `auto_mode_eligible`** — pack policy is master
- **Auto-starting high-risk workflows** — even with `auto_mode_eligible: true`, high-risk requires explicit confirm per level (b)
- **Skipping audit** — every routing decision goes to orientator-decisions.jsonl for operator inspection + future learning
- **Hard-coding workflow names** — read from pack's `default_workflow` so per-pack routing is configurable