detections/.cursor/skills/autopilot/protocols.md

# Autopilot Protocols

## User Interaction Protocol

Every time the autopilot or a sub-skill needs a user decision, use the **Choose A / B / C / D** format. This applies to:

- State transitions where multiple valid next actions exist
- Sub-skill BLOCKING gates that require user judgment
- Any fork where the autopilot cannot confidently pick the right path
- Trade-off decisions (tech choices, scope, risk acceptance)

### When to Ask (MUST ask)

- The next action is ambiguous (e.g., "another research round or proceed?")
- The decision has irreversible consequences (e.g., architecture choices, skipping a step)
- The user's intent or preference cannot be inferred from existing artifacts
- A sub-skill's BLOCKING gate explicitly requires user confirmation
- Multiple valid approaches exist with meaningfully different trade-offs

### When NOT to Ask (auto-transition)

- Only one logical next step exists (e.g., Problem complete → Research is the only option)
- The transition is deterministic from the state (e.g., Plan complete → Decompose)
- The decision is low-risk and reversible
- Existing artifacts or prior decisions already imply the answer

### Choice Format

Always present decisions in this format:

```
══════════════════════════════════════
 DECISION REQUIRED: [brief context]
══════════════════════════════════════
 A) [Option A — short description]
 B) [Option B — short description]
 C) [Option C — short description, if applicable]
 D) [Option D — short description, if applicable]
══════════════════════════════════════
 Recommendation: [A/B/C/D] — [one-line reason]
══════════════════════════════════════
```

Rules:
1. Always provide 2–4 concrete options (never open-ended questions)
2. Always include a recommendation with a brief justification
3. Keep option descriptions to one line each
4. If only 2 options make sense, use A/B only — do not pad with filler options
5. Play the notification sound (per `human-input-sound.mdc`) before presenting the choice
6. Record every user decision in the state file's `Key Decisions` section
7. After the user picks, proceed immediately — no follow-up confirmation unless the choice was destructive

## Jira MCP Authentication

Several workflow steps create Jira artifacts (epics, tasks, links). The Jira MCP server must be authenticated **before** any step that writes to Jira.

### Steps That Require Jira MCP

| Step | Sub-Step | Jira Action |
|------|----------|-------------|
| 2 (Plan) | Step 6 — Jira Epics | Create epics for each component |
| 2c (Decompose Tests) | Step 1t + Step 3 — All test tasks | Create Jira ticket per task, link to epic |
| 2f (New Task) | Step 7 — Jira ticket | Create Jira ticket per task, link to epic |
| 3 (Decompose) | Step 1–3 — All tasks | Create Jira ticket per task, link to epic |

### Authentication Gate

Before entering **Step 2 (Plan)**, **Step 2c (Decompose Tests)**, **Step 2f (New Task)**, or **Step 3 (Decompose)** for the first time, the autopilot must:

1. Call `mcp_auth` on the Jira MCP server
2. If authentication succeeds → proceed normally
3. If the user **skips** or authentication fails → present using Choose format:

```
══════════════════════════════════════
 Jira MCP authentication failed
══════════════════════════════════════
 A) Retry authentication (retry mcp_auth)
 B) Continue without Jira (tasks saved locally only)
══════════════════════════════════════
 Recommendation: A — Jira IDs drive task referencing,
 dependency tracking, and implementation batching.
 Without Jira, task files use numeric prefixes instead.
══════════════════════════════════════
```

If user picks **B** (continue without Jira):
- Set a flag in the state file: `jira_enabled: false`
- All skills that would create Jira tickets instead save metadata locally in the task/epic files with `Jira: pending` status
- Task files keep numeric prefixes (e.g., `01_initial_structure.md`) instead of Jira ID prefixes
- The workflow proceeds normally in all other respects

### Re-Authentication

If Jira MCP was already authenticated in a previous invocation (verify by listing available Jira tools beyond `mcp_auth`), skip the auth gate.

## Error Handling

All error situations that require user input MUST use the **Choose A / B / C / D** format.

| Situation | Action |
|-----------|--------|
| State detection is ambiguous (artifacts suggest two different steps) | Present findings and use Choose format with the candidate steps as options |
| Sub-skill fails or hits an unrecoverable blocker | Use Choose format: A) retry, B) skip with warning, C) abort and fix manually |
| User wants to skip a step | Use Choose format: A) skip (with dependency warning), B) execute the step |
| User wants to go back to a previous step | Use Choose format: A) re-run (with overwrite warning), B) stay on current step |
| User asks "where am I?" without wanting to continue | Show Status Summary only, do not start execution |

## Status Summary

On every invocation, before executing any skill, present a status summary built from the state file (with folder scan fallback). Use the template matching the active flow (see Flow Resolution in SKILL.md).

### Greenfield Flow

```
═══════════════════════════════════════════════════
 AUTOPILOT STATUS (greenfield)
═══════════════════════════════════════════════════
 Step 0   Problem             [DONE / IN PROGRESS / NOT STARTED]
 Step 1   Research            [DONE (N drafts) / IN PROGRESS / NOT STARTED]
 Step 2   Plan                [DONE / IN PROGRESS / NOT STARTED]
 Step 3   Decompose           [DONE (N tasks) / IN PROGRESS / NOT STARTED]
 Step 4   Implement           [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED]
 Step 5   Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED]
 Step 6   Deploy              [DONE / IN PROGRESS / NOT STARTED]
═══════════════════════════════════════════════════
 Current: Step N — Name
 SubStep: M — [sub-skill internal step name]
 Action:  [what will happen next]
═══════════════════════════════════════════════════
```

### Existing Code Flow

```
═══════════════════════════════════════════════════
 AUTOPILOT STATUS (existing-code)
═══════════════════════════════════════════════════
 Pre      Document            [DONE / IN PROGRESS / NOT STARTED]
 Step 2b  Blackbox Test Spec  [DONE / IN PROGRESS / NOT STARTED]
 Step 2c  Decompose Tests     [DONE (N tasks) / IN PROGRESS / NOT STARTED]
 Step 2d  Implement Tests     [DONE / IN PROGRESS (batch M) / NOT STARTED]
 Step 2e  Refactor            [DONE / IN PROGRESS (phase N) / NOT STARTED]
 Step 2f  New Task            [DONE (N tasks) / IN PROGRESS / NOT STARTED]
 Step 2g  Implement           [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED]
 Step 2h  Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED]
 Step 2i  Deploy              [DONE / IN PROGRESS / NOT STARTED]
═══════════════════════════════════════════════════
 Current: Step N — Name
 SubStep: M — [sub-skill internal step name]
 Action:  [what will happen next]
═══════════════════════════════════════════════════
```

For re-entry (state file exists), also include:
- Key decisions from the state file's `Key Decisions` section
- Last session context from the `Last Session` section
- Any blockers from the `Blockers` section