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

# Intent recognition and routing

> Intent recognition and slot extraction are the core of /comet routing: learn how Comet identifies your intent, extracts routing slots, and scores them with a fixed-priority order to produce an explainable route.

Every time you type `/comet` plus a sentence, Comet has to answer one question: which workflow should this request use? That decision is driven by two things: **intent recognition** and **slot extraction**.

**Intent recognition** answers "what do you want to do": start a new change, fix an existing bug, make a light adjustment, resume an in-progress change, or just ask a question? **Slot extraction** breaks your utterance and repository state into structured routing signals — action, workflow candidate, risk flags — each labeled with its source, ready for the runtime to score with a fixed priority order.

Starting in 0.4.0, this mechanism (implemented as `CometIntentFrame`) replaces the natural-language heuristics in Skill text and makes routing **explainable, reviewable, and recoverable**. In our baseline tests, this also improved Comet's recovery behavior for interrupted workflows.

<p align="center">
  <img src="https://mintcdn.com/comet-bb5f5294/NUwmZ5EiD7zTi99y/assets/intent-routing-illustrations/01-routing-context-triage.png?fit=max&auto=format&n=NUwmZ5EiD7zTi99y&q=85&s=29c28a87d5a7b7811ab66bc34abcab69" alt="Xiaoyu checks the utterance, repository state, and risk signals on a routing-context triage board before selecting the final route" width="800" data-path="assets/intent-routing-illustrations/01-routing-context-triage.png" />
</p>

<p align="center">Routing context turns the request and repository evidence into a decision the runtime can review.</p>

## Why routing context exists

<Note>
  In one sentence: routing context makes <code>/comet</code> routing <strong>explainable, reviewable, and recoverable</strong> instead of a black-box guess.
</Note>

Before routing context, `/comet` relied on prose rules such as “if this is a bug, use hotfix; if this is a copy tweak, use tweak.” That created three problems:

| Problem             | What it felt like                                                           |
| ------------------- | --------------------------------------------------------------------------- |
| **Not explainable** | Users and agents could not tell why a route was selected.                   |
| **Not reviewable**  | There was no structured record of the signals that drove the decision.      |
| **Not recoverable** | After interruption, the agent had to read the prompt again and guess again. |

Routing context turns “what the user wants” into structured data with fields, evidence, and confidence. The runtime does not blindly trust the agent's proposed route. It rescores the context, returns the final route, and writes disagreements into diagnostics.

## Route results

| Route          | Meaning                                                            | Next Skill                     | Requires confirmation |
| -------------- | ------------------------------------------------------------------ | ------------------------------ | --------------------- |
| `full`         | Run the full open -> design -> build -> verify -> archive workflow | `comet-open`                   | No                    |
| `hotfix`       | Fix existing behavior quickly, skipping brainstorming              | `comet-hotfix`                 | No                    |
| `tweak`        | Use the OpenSpec-backed medium-change path                         | `comet-tweak`                  | No                    |
| `resume`       | Resume an active change                                            | Depends on that change's phase | No                    |
| `ask_user`     | Evidence is insufficient or conflicting                            | None                           | **Yes**               |
| `out_of_scope` | The user is asking a question, not starting work                   | None                           | **Yes**               |

Comet asks when it cannot prove a path is safe. It does not force an uncertain request into `full`, `hotfix`, or `tweak`.

## Intent recognition and slot extraction

The two core inputs to the routing decision are `intent` (intent recognition) and `slots` (slot extraction), together with supporting fields in `CometIntentFrame` — the structure the runtime scores to produce a final route:

```mermaid theme={null}
flowchart LR
    U["Your utterance<br/>utterance"] --> F["Routing context<br/>CometIntentFrame"]
    R["Repository state<br/>active changes"] --> F
    F --> I["intent<br/>name + confidence"]
    F --> S["slots<br/>routing signals"]
    F --> C["context<br/>repo context"]
    F --> E["evidence<br/>supporting snippets"]
    F --> P["proposed_route<br/>agent suggestion"]
    I --> RT{"Runtime scoring"}
    S --> RT
    C --> RT
    E --> RT
    RT --> O["Final route"]
```

| Part             | Purpose                                                             |
| ---------------- | ------------------------------------------------------------------- |
| `utterance`      | The original user request that triggered `/comet`.                  |
| `intent`         | High-level intent and confidence.                                   |
| `slots`          | Normalized routing slots: action, workflow candidate, risk signals. |
| `context`        | Repository-derived context, not text extracted from the request.    |
| `evidence`       | Source-labeled snippets that support key judgments.                 |
| `proposed_route` | The agent's candidate route. The runtime still reviews it.          |

### Intent recognition (`intent`)

`intent` has two sub-fields:

* **`name`**: intent type. `start_new_change` / `fix_bug` / `make_tweak` / `resume_change` / `ask_question` / `unknown`
* **`confidence`**: a 0-1 score. When confidence falls below 0.7, the runtime routes directly to `ask_user` — it will not gamble on an ambiguous intent.

### Slot extraction (`slots`)

| Slot                        | Routing tendency                   |
| --------------------------- | ---------------------------------- |
| `existing_behavior: true`   | Bug fix -> `hotfix`                |
| `new_capability: true`      | New capability -> `full`           |
| `public_api_change: true`   | External contract change -> `full` |
| `schema_change: true`       | Structured data change -> `full`   |
| `cross_module_change: true` | Cross-boundary change -> `full`    |

<Warning>
  Risk signals take precedence over casual wording. If you ask for a hotfix but the request changes a public API, Comet stops at <code>ask\_user</code> instead of silently allowing a risky lightweight path.
</Warning>

## Runtime scoring order

<Note>
  **This fixed-priority order is the core of explainable routing.** Each step has a clear condition, and disagreements are written to diagnostics for later review.
</Note>

1. Low confidence -> `ask_user`.
2. Multiple active changes with no target -> `ask_user`.
3. Valid resume target -> `resume`.
4. Question-only request -> `out_of_scope`.
5. Explicit workflow conflicts with risk signals -> `ask_user`.
6. Risk signals -> `full`.
7. Existing bug with evidence -> `hotfix`.
8. Tweak with evidence -> `tweak`.
9. Not enough evidence -> `ask_user`.

Diagnostics record normalization, for example when an agent proposes `hotfix` but the runtime normalizes to `full`.

## What this means for users

You do not write routing context by hand. `/comet` builds and scores it internally. Describe the work clearly, expect Comet to ask when evidence is weak, and use diagnostics to understand why a route was selected.

Advanced users can route a context JSON directly:

```bash theme={null}
node "$COMET_INTENT" route '{"schema_version":"comet.intent.v1", ...}'
node "$COMET_INTENT" route --stdin < frame.json
```

## Relationship to /comet-tweak

`/comet` is the general entry point. It uses routing context to choose `full`, `hotfix`, `tweak`, `resume`, or a pause.

`/comet-tweak` is the dedicated OpenSpec action path for medium changes when you already know tweak is the correct workflow.

## Next steps

* [Workflow concepts](/en/concepts/workflow)
* [Decision points](/en/concepts/decision-points)
* [Core scripts overview](/en/scripts/overview)