# Agent Tick Decision Gate × ask_user Interaction Spec

## Purpose

This document defines a minimal decision-gating protocol for using the `agent-tick-decision-gate` skill with Pi's Agent Tick-backed `agent_tick_ask_user` tool (or compatibility `ask_user` alias).

Goal: require explicit human decisions at high-impact or ambiguous boundaries before implementation continues. When Agent Tick is configured, the same decision prompt can be answered locally in Pi or remotely through Agent Tick.

---

## 1) Trigger Matrix (When to Call `agent_tick_ask_user`)

| Scenario | Must Ask? | Why |
|---|---:|---|
| Architecture trade-off (e.g., queue vs cron, SQL vs KV) | Yes | Preference-sensitive, high blast radius |
| Data schema / migration path selection | Yes | Costly to reverse |
| Security/compliance posture trade-off | Yes | Risk ownership is human |
| Requirements conflict or ambiguity | Yes | Need explicit intent |
| Non-trivial scope cut/prioritization | Yes | Product decision, not purely technical |
| Purely local refactor with identical behavior | Usually no | No policy-level decision |
| Formatting-only edits | No | Trivial |
| User already gave explicit choice for exact trade-off | No (unless new ambiguity) | Decision already captured |

---

## 2) Decision Handshake

Use this protocol whenever the trigger matrix says to ask.

1. **Detect boundary**
   - classify as `high_stakes`, `ambiguous`, `both`, or `clear`
2. **Gather evidence**
   - read code/docs/logs first; do not ask blindly
3. **Summarize context**
   - prepare concise trade-off context (3–7 bullets or short paragraph)
4. **Ask one focused question**
   - call `agent_tick_ask_user` for one decision at a time
   - include structured options and descriptions when useful
   - omit display-mode overrides unless there is a clear reason
5. **Commit and proceed**
   - restate chosen option and implement accordingly

### Agent Tick behavior

The extension preserves the local Pi popup/dialog UX. If Agent Tick config exists, the prompt is also mirrored remotely and the first valid local or remote answer wins.

- Single-select options become Agent Tick choices.
- Option `flags` are forwarded for mobile-visible cues; mark exactly one recommended choice with `favorite` when the agent has a recommendation.
- Multi-select options become Agent Tick structured questions when supported.
- Remote Agent Tick responses are choice-only; arbitrary phone-entered text is not passed back to the agent.
- Cancel, timeout, or no usable response should be treated as blocked for high-stakes decisions.

### Retry/cancel policy

- Max **2** `agent_tick_ask_user` attempts for the same decision boundary.
- Attempt 1: normal structured question.
- Attempt 2: narrower question with recommendation and explicit options.
- After attempt 2:
  - `high_stakes` / `both`: stop and report blocked.
  - `ambiguous` only: proceed only if user delegates (e.g., “your call”), using the most reversible default.

---

## 3) Example Payloads

### Architecture decision

```json
{
  "question": "Which implementation path should we use for v1?",
  "context": "Path A is faster to ship but less extensible. Path B takes longer but supports plugin-style growth. Existing deadline is 2 weeks.",
  "options": [
    { "title": "Path A (ship fast)", "description": "Lowest scope, revisit architecture later", "flags": ["fastest", "reversible"] },
    { "title": "Path B (extensible)", "description": "Higher initial effort, cleaner long-term composition", "flags": ["favorite", "thorough"] }
  ],
  "allowMultiple": false,
  "allowFreeform": true
}
```

### Display mode (optional)

The `agent_tick_ask_user` tool accepts an optional `displayMode` parameter:

- `"overlay"`: centered modal; covers the conversation underneath.
- `"inline"`: rendered in the conversation flow; preceding messages stay visible.

Guidance:

- Omit `displayMode` to respect the user's configured preference.
- Pass `"inline"` only when the immediately preceding assistant message is the primary context for the decision and must remain visible.
- Pass `"overlay"` only to explicitly force the modal style (rare).

### Requirement-priority decision

```json
{
  "question": "Which requirement should be prioritized first?",
  "context": "Current request mixes performance tuning and UI redesign. Doing both now risks delaying delivery.",
  "options": [
    "Performance first",
    "UI redesign first",
    "Do a minimal pass on both"
  ],
  "allowMultiple": false,
  "allowFreeform": true
}
```