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 |

## Skill Failure Retry Protocol

Sub-skills can return a **failed** result. Failures are often caused by missing user input, environment issues, or transient errors that resolve on retry. The autopilot auto-retries before escalating.

### Retry Flow

```
Skill execution → FAILED
  │
  ├─ retry_count < 3 ?
  │    YES → increment retry_count in state file
  │         → log failure reason in state file (Retry Log section)
  │         → re-read the sub-skill's SKILL.md
  │         → re-execute from the current sub_step
  │         → (loop back to check result)
  │
  │    NO (retry_count = 3) →
  │         → set status: failed in Current Step
  │         → add entry to Blockers section:
  │             "[Skill Name] failed 3 consecutive times at sub_step [M].
  │              Last failure: [reason]. Auto-retry exhausted."
  │         → present warning to user (see Escalation below)
  │         → do NOT auto-retry again until user intervenes
```

### Retry Rules

1. **Auto-retry immediately**: when a skill fails, retry it without asking the user — the failure is often transient (missing user confirmation in a prior step, docker not running, file lock, etc.)
2. **Preserve sub_step**: retry from the last recorded `sub_step`, not from the beginning of the skill — unless the failure indicates corruption, in which case restart from sub_step 1
3. **Increment `retry_count`**: update `retry_count` in the state file's `Current Step` section on each retry attempt
4. **Log each failure**: append the failure reason and timestamp to the state file's `Retry Log` section
5. **Reset on success**: when the skill eventually succeeds, reset `retry_count: 0` and clear the `Retry Log` for that step

### Escalation (after 3 consecutive failures)

After 3 failed auto-retries of the same skill, the failure is likely not user-related. Stop retrying and escalate:

1. Update the state file:
   - Set `status: failed` in `Current Step`
   - Set `retry_count: 3`
   - Add a blocker entry describing the repeated failure
2. Play notification sound (per `human-input-sound.mdc`)
3. Present using Choose format:

```
══════════════════════════════════════
 SKILL FAILED: [Skill Name] — 3 consecutive failures
══════════════════════════════════════
 Step: [N] — [Name]
 SubStep: [M] — [sub-step name]
 Last failure reason: [reason]
══════════════════════════════════════
 A) Retry with fresh context (new conversation)
 B) Skip this step with warning
 C) Abort — investigate and fix manually
══════════════════════════════════════
 Recommendation: A — fresh context often resolves
 persistent failures
══════════════════════════════════════
```

### Re-Entry After Failure

On the next autopilot invocation (new conversation), if the state file shows `status: failed` and `retry_count: 3`:

- Present the blocker to the user before attempting execution
- If the user chooses to retry → reset `retry_count: 0`, set `status: in_progress`, and re-execute
- If the user chooses to skip → mark step as `skipped`, proceed to next step
- Do NOT silently auto-retry — the user must acknowledge the persistent failure first

## Error Recovery Protocol

### Stuck Detection

When executing a sub-skill, monitor for these signals:

- Same artifact overwritten 3+ times without meaningful change
- Sub-skill repeatedly asks the same question after receiving an answer
- No new artifacts saved for an extended period despite active execution

### Recovery Actions (ordered)

1. **Re-read state**: read `_docs/_autopilot_state.md` and cross-check against `_docs/` folders
2. **Retry current sub-step**: re-read the sub-skill's SKILL.md and restart from the current sub-step
3. **Escalate**: after 2 failed retries, present diagnostic summary to user using Choose format:

```
══════════════════════════════════════
 RECOVERY: [skill name] stuck at [sub-step]
══════════════════════════════════════
 A) Retry with fresh context (new conversation)
 B) Skip this sub-step with warning
 C) Abort and fix manually
══════════════════════════════════════
 Recommendation: A — fresh context often resolves stuck loops
══════════════════════════════════════
```

### Circuit Breaker

If the same autopilot step fails 3 consecutive times across conversations:

- Record the failure pattern in the state file's `Blockers` section
- Do NOT auto-retry on next invocation
- Present the blocker and ask user for guidance before attempting again

## Context Management Protocol

### Principle

Disk is memory. Never rely on in-context accumulation — read from `_docs/` artifacts, not from conversation history.

### Minimal Re-Read Set Per Skill

When re-entering a skill (new conversation or context refresh):

- Always read: `_docs/_autopilot_state.md`
- Always read: the active skill's `SKILL.md`
- Conditionally read: only the `_docs/` artifacts the current sub-step requires (listed in each skill's Context Resolution section)
- Never bulk-read: do not load all `_docs/` files at once

### Mid-Skill Interruption

If context is filling up during a long skill (e.g., document, implement):

1. Save current sub-step progress to the skill's artifact directory
2. Update `_docs/_autopilot_state.md` with exact sub-step position
3. Suggest a new conversation: "Context is getting long — recommend continuing in a fresh conversation for better results"
4. On re-entry, the skill's resumability protocol picks up from the saved sub-step

### Large Artifact Handling

When a skill needs to read large files (e.g., full solution.md, architecture.md):

- Read only the sections relevant to the current sub-step
- Use search tools (Grep, SemanticSearch) to find specific sections rather than reading entire files
- Summarize key decisions from prior steps in the state file so they don't need to be re-read

## Rollback Protocol

### Implementation Steps (git-based)

Handled by `/implement` skill — each batch commit is a rollback checkpoint via `git revert`.

### Planning/Documentation Steps (artifact-based)

For steps that produce `_docs/` artifacts (problem, research, plan, decompose, document):

1. **Before overwriting**: if re-running a step that already has artifacts, the sub-skill's prerequisite check asks the user (resume/overwrite/skip)
2. **Rollback to previous step**: use Choose format:

```
══════════════════════════════════════
 ROLLBACK: Re-run [step name]?
══════════════════════════════════════
 A) Re-run the step (overwrites current artifacts)
 B) Stay on current step
══════════════════════════════════════
 Warning: This will overwrite files in _docs/[folder]/
══════════════════════════════════════
```

3. **Git safety net**: artifacts are committed with each autopilot step completion. To roll back: `git log --oneline _docs/` to find the commit, then `git checkout <commit> -- _docs/<folder>/`
4. **State file rollback**: when rolling back artifacts, also update `_docs/_autopilot_state.md` to reflect the rolled-back step (set it to `in_progress`, clear completed date)

## 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 / FAILED (retry N/3)]
 Step 1   Research            [DONE (N drafts) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2   Plan                [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 3   Decompose           [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 4   Implement           [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED / FAILED (retry N/3)]
 Step 5   Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 5b  Security Audit      [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 6   Deploy              [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
═══════════════════════════════════════════════════
 Current: Step N — Name
 SubStep: M — [sub-skill internal step name]
 Retry:   [N/3 if retrying, omit if 0]
 Action:  [what will happen next]
═══════════════════════════════════════════════════
```

### Existing Code Flow

```
═══════════════════════════════════════════════════
 AUTOPILOT STATUS (existing-code)
═══════════════════════════════════════════════════
 Pre      Document            [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2b  Blackbox Test Spec  [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2c  Decompose Tests     [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2d  Implement Tests     [DONE / IN PROGRESS (batch M) / NOT STARTED / FAILED (retry N/3)]
 Step 2e  Refactor            [DONE / IN PROGRESS (phase N) / NOT STARTED / FAILED (retry N/3)]
 Step 2f  New Task            [DONE (N tasks) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2g  Implement           [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED / FAILED (retry N/3)]
 Step 2h  Run Tests           [DONE (N passed, M failed) / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2hb Security Audit      [DONE / SKIPPED / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
 Step 2i  Deploy              [DONE / IN PROGRESS / NOT STARTED / FAILED (retry N/3)]
═══════════════════════════════════════════════════
 Current: Step N — Name
 SubStep: M — [sub-skill internal step name]
 Retry:   [N/3 if retrying, omit if 0]
 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