auto

# /ork:auto — Intent Router

The front door to OrchestKit. **You describe a goal in plain English; the router classifies it and hands off to the right specialist.** One entry point, many execution paths.

> **Why this exists:** OrchestKit has 112 skills, but usage telemetry shows users fire only the handful they can name by memory (10 distinct skills across thousands of sessions). The dominant cause of "dead" skills is **no front door** — not low quality. This router turns "you must know the exact `/ork:<name>`" into "describe what you want."

**Core principle:** routing is a *deterministic workflow*, not an autonomous agent (Anthropic, *Building Effective Agents*). Classify → confirm → hand off. The router never does the work itself — it picks who does.

## When to use vs. go direct

| Use `/ork:auto` when… | Go direct when… |
|---|---|
| You describe a goal, not a method | You already know the skill (`/ork:cover`) |
| The right skill isn't obvious | The request maps unambiguously to one |
| You want the agent to choose | You're chaining a known workflow |

## Intent categories → OrchestKit skill

| intent | signal words | routes to |
|---|---|---|
| **fix** | fix, debug, broken, failing, error, crash, regression | `/ork:fix-issue` |
| **diagnose** | why, why isn't, why does, why can't, investigate | `/ork:fix-issue` (investigation-first) |
| **optimize** | faster, reduce, latency, bundle, minimize, below N ms | a **`/goal` optimization loop** (see Gaps) |
| **cover** | coverage, untested, get to N% | `/ork:cover --target N` |
| **design** | design, architect, how should we, explore, idea | `/ork:brainstorm` |
| **build** | build, implement, create, add feature, from ticket | `/ork:implement` |
| **review** | review, PR, MR, pull request, #N | `/ork:review-pr` |
| **verify** | verify, check, make sure, passes, green | `/ork:verify` |
| **improve-skill** | improve the skill, optimize the prompt, SKILL.md | the **skill-evolution / holdout gate** (see Gaps) |
| **(fallback)** | no confident category | clarify with ONE question |

Full per-category parameter extraction + edge cases: `references/routing-rules.md`.

## The flow

```
  CLASSIFY  ->  CONFIRM  ->  HAND OFF
     |            |             |
  reason       show the     invoke the
  out loud     route        target skill;
  (CoT)        + nod        follow ITS phases
```

### 1. Classify (reason out loud first)

State your reasoning **before** committing to a route — this triggers chain-of-thought and is the single biggest accuracy lever (Anthropic, *Writing Effective Tools for Agents*). Example: *"'get latency under 200ms' names a metric + a direction → optimize, not fix."*

Apply the disambiguation rules (most specific wins; explicit verb beats inferred intent):

1. **Explicit verb wins.** "Fix the slow query" → `fix` (not `optimize`).
2. **Metric + direction → optimize.** "Get p95 below 200ms" → `optimize`.
3. **Percentage in a test context → cover.** "Get to 90%" → `cover`.
4. **Question form → design or diagnose.** "How should we…" → `design`; "Why isn't…" → `diagnose`.
5. **PR/MR/#N reference → review.**
6. **Ticket reference → build.**

### 2. Confirm (low ceremony)

Show the chosen route in one line and get a nod before handing off:

```
Goal:   "{original goal}"
Intent: {category}
Route:  {/ork:skill or loop} {extracted args}
        [run] · [adjust] · [cancel]
```

For low-risk single-pass routes (`verify`, `review`), an inline "routing you to /ork:verify — ok?" is enough. Never hand off without a nod.

### 3. Hand off

Invoke the target skill with the extracted parameters and **follow that skill's own phases and guardrails** — do not override them. The router's job ends at the handoff; the specialist owns execution and its own report.

## Fallback + honest gaps

- **Fallback category.** If no category clears a confident threshold, ask exactly ONE clarifying question rather than guessing. A rising fallback rate is the leading indicator that the taxonomy needs work — surface it, don't bury it.
- **`optimize` has no dedicated skill (yet).** OrchestKit's metric-driven optimization runs as a **`/goal` loop** using the loop recipe library (`/ork:prd-to-goal` → `references/recipe-library.md`). Route `optimize` there and say so plainly — don't pretend a `/ork:experiment` skill exists.
- **`improve-skill` routes to the evolution gate.** Self-optimizing a `SKILL.md` goes through the champion/challenger **holdout-promotion gate** (`/ork:assess` evals + `evolution-engine`), not a one-shot edit. It requires a benchmark + holdout set first.

## Guardrails

- **No recursion.** `/ork:auto` must not route to itself, directly or via a spawned agent.
- **No bypass.** Routing does not skip the target skill's guardrails, readonly enforcement, or confirmation steps.
- **Classification quality is the whole job.** A misroute that fails silently is worse than a fallback question. When two categories are equally plausible, ask — don't gamble.

## Validation

Routing accuracy is gateable, not vibes. `routing-benchmark.json` holds 50 labeled `goal → category` pairs (easy + genuinely ambiguous). Validate after any change to the category table or disambiguation rules:

```bash
# isolated classification check via the bare-eval harness
/ork:bare-eval   # grade router output against routing-benchmark.json
```

Target ≥95% category accuracy; track the fallback rate as a degradation alarm as the skill library grows.

## References

- `references/routing-rules.md` — per-category parameter extraction, edge cases, disambiguation
- `routing-benchmark.json` — 50 labeled goal→category pairs for accuracy validation

## Related skills

- `/ork:help` — static categorized directory (browse, don't route)
- `/ork:prd-to-goal` — decompose a spec into a `/goal` line (the `optimize` route's engine)
- `/ork:fix-issue` · `/ork:cover` · `/ork:brainstorm` · `/ork:implement` · `/ork:review-pr` · `/ork:verify` — the route targets
- `/ork:assess` — champion/challenger holdout