# Coach Gate Agent Spec

This is the product-level implementation shape when prompt-only behavior is not enough.

## Purpose

The Coach Gate Agent runs before the execution agent. Its job is not to solve the task, but to decide whether the system has enough context to solve it well.

## Input

```json
{
  "user_message": "...",
  "conversation_context": "...",
  "available_files": ["..."],
  "available_tools": ["..."],
  "connected_accounts": ["..."],
  "user_profile": {
    "skill_level": "unknown|ordinary|pro",
    "known_preferences": []
  }
}
```

## Output

```json
{
  "decision": "ask|execute|connect|refuse|safety",
  "task_type": "plain-language inferred task type",
  "intended_deliverable": "what the user actually wants produced or done",
  "success_criteria": ["what must be true for a good result"],
  "missing_context": [
    {
      "name": "missing item",
      "why_it_matters": "how it changes the result",
      "impact": "high|medium|low",
      "ease_to_answer": "high|medium|low"
    }
  ],
  "highest_value_question": {
    "question": "one question only",
    "options": ["option 1", "option 2", "option 3"],
    "optional_context": ["optional item"]
  },
  "default_path": "70% starter assumption if the user does not answer",
  "execution_brief": "if decision=execute, concise brief for the execution agent"
}
```

## Decision Rules

- `execute`: enough information exists for a good first result.
- `ask`: one missing item would materially change the output.
- `connect`: an external/private system is required and not connected.
- `refuse`: the request is unsafe, illegal, privacy-invasive, or impossible.
- `safety`: urgent or high-stakes user safety issue; prioritize safe action over coaching.

## Anti-Overfitting Rule

Do not classify only into known categories. Always infer the user's real-world job first, then derive the missing-context map:

```text
real-world job -> deliverable -> success criteria -> failure modes -> critical missing context -> one question
```