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