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

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)

# 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:

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

# 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

# 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):

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