feat(autopilot): pre-flight isolation question on rule 6

[leoluyi]

Summary

• Isolation rules 1-5 are forced by observable git state or an explicit user declaration (already on a non-default branch, already in a worktree, declared solo, dirty tree, unmerged upstream commits) — nothing to decide there.
• Rule 6 (clean tree, on the default branch) is the only rung where worktree and branch-in-place are both legal, and the skill previously picked worktree silently. It now asks — worktree recommended, branch in place the alternative — as a pre-flight question at step 2, before recon or planning touch the repo, while the user is still present to answer. Falls back to worktree (recorded in the final report) when no one is reachable, e.g. a headless/cron run.
• Reordered Sequence: Isolate moved from step 4 to step 2.
• Fixed allowed-tools: git rev-parse, git rev-list, git worktree list were commanded by the Isolation section body but missing from the frontmatter allowlist — the ladder could stall on a permission prompt. Added those plus AskUserQuestion.
• Synced catalog.md and both guide.{en,zh}.md to match: step order, isolation-ladder paragraph, "walk away" line.
• Reconciled the "do not come back to me between steps" promise at three sites (opening paragraph, "What this overrides", "Hard stops") so none contradicts the new pre-flight question.

Decisions

• Ask at invocation-adjacent step 2, not mid-run — keeps the autonomous-mode promise literally true.
• Only rule 6 asks; rules 1-5 stay fully automatic since git state or a prior user statement already settles them.
• No answer available (headless/cron) → falls back to the existing worktree default, not a hard stop.

Review

Dispatched one correctness-review subagent over the full diff (docs-only, no security surface — skill instruction text, no executable code). It found two real issues, both fixed before this commit:

1. "Tool surface" prose section didn't mention the new AskUserQuestion tool, so its "already set to this same surface" claim was stale against the frontmatter.
2. catalog.md's highlight bullet (en + zh) lumped the user-declared "solo" rule in with the four git-state-observable rules — now phrased to match SKILL.md's own distinction.

Verification

• uv run tools/build-docs --check — exit 0, no drift (this repo's docs-check CI gate, which watches exactly these file paths).
• rg '\\u[0-9A-F]{4}' over the changed files — no escaped-unicode violations (repo hard rule).
• Read Sequence / Isolation / What this overrides / Hard stops end to end — no remaining claim that the run never asks anything or that isolation is decided at step 4.
• guide.en.md / guide.zh.md diffed for the three edited spots — same claims in both languages.

Test plan

• Invoke autopilot on a clean checkout, on the default branch, with a small job: confirm it asks worktree-vs-branch before spawning any recon agent, and honours the answer.
• Invoke with a stated preference ("use a worktree, "): confirm no question is asked.

Summary by Sourcery

Introduce a pre-flight isolation choice in autopilot runs while keeping the autonomous execution contract intact, and update tooling and docs to match.

New Features:

• Add a pre-flight isolation question for rule 6 so users can choose between worktree and branch-in-place when both are valid, with worktree as the default recommendation.

Enhancements:

• Move isolation from step 4 to step 2 in the autopilot sequence so isolation is decided before any repo modifications.
• Clarify that the pre-flight isolation question is the sole exception to the no-interruption promise and occurs before the autonomous stretch begins.
• Extend the described tool surface and runtime allowlist to include AskUserQuestion and additional git commands used by the isolation ladder.
• Document in the final report whether the pre-flight isolation question was answered by the user or fell back to the default.
• Align English and Chinese guides and the catalog highlights with the new isolation flow, pre-flight question, and reordered steps.

[sourcery-ai]

Reviewer's Guide

Adds a pre-flight isolation question to the autopilot skill’s isolation ladder (rule 6), runs isolation earlier in the sequence, and updates allowed tools and documentation to keep the autonomous-mode promise consistent with the new interaction.

Sequence diagram for the new pre-flight isolation question in rule 6

sequenceDiagram
    actor User
    participant AutopilotSkill
    participant AskUserQuestionTool

    User->>AutopilotSkill: invoke autopilot

    AutopilotSkill->>AutopilotSkill: [Isolation step 2]
    AutopilotSkill->>AutopilotSkill: Bash(git status:*)
    AutopilotSkill->>AutopilotSkill: Bash(git rev-parse:*)
    AutopilotSkill->>AutopilotSkill: Bash(git rev-list:*)
    AutopilotSkill->>AutopilotSkill: Bash(git worktree list:*)

    alt preference already stated
        AutopilotSkill->>AutopilotSkill: EnterWorktree
        AutopilotSkill->>AutopilotSkill: Bash(git branch:*)
    else headless or no preference
        AutopilotSkill->>AskUserQuestionTool: AskUserQuestion
        AskUserQuestionTool->>User: AskUserQuestion
        User-->>AskUserQuestionTool: answer(worktree|branch)
        AskUserQuestionTool-->>AutopilotSkill: answer(worktree|branch)

        alt answer worktree
            AutopilotSkill->>AutopilotSkill: EnterWorktree
        else answer branch
            AutopilotSkill->>AutopilotSkill: Bash(git branch:*)
        end
    end

    AutopilotSkill->>AutopilotSkill: Agent
    AutopilotSkill->>AutopilotSkill: proceed to recon, plan, build, verify, ship

Loading

File-Level Changes

Change	Details	Files
Introduce pre-flight isolation question for rule 6 and clarify autonomous-mode carve-out in SKILL.md.	Bump skill version from 1.0.0 to 1.1.0. Add AskUserQuestion and missing git commands to the allowed tools list and describe the updated tool surface. Document a single pre-flight isolation question occurring before the autonomous run and explicitly carve it out from the usual no-questions rule. Update the Sequence section to move isolation from step 4 to step 2 and adjust step numbering. Rewrite Isolation rule 6 to ask the user to choose between worktree and branch-in-place, with clear precedence rules, headless fallback behaviour, and harness-dependant degradation. Clarify why rules 1–5 remain automatic and refine explanations for rules 2–5, including behaviour when worktrees are unsupported. Update Hard stops and Final report sections to exclude the pre-flight question from hard stops and to record whether it was asked or defaulted.	skills/autopilot/SKILL.md
Align English usage guide with new step order and isolation ladder behaviour.	Update the seven-step summary to place isolation at step 2 and shift recon/plan steps accordingly. Change the “When to use” section to mention answering a pre-flight question before walking away. Rewrite the isolation-ladder description to emphasise five forced rules plus a sixth interactive rung, with the question asked at invocation and clear defaults for preferences and headless runs. Reaffirm that only four hard stops break the no-interruption rule despite the new pre-flight question.	skills/autopilot/guide.en.md
Align Chinese usage guide with new step order and isolation ladder behaviour.	Update the seven-step summary to place isolation at step 2 and adjust subsequent steps. Change the “何時使用” section to mention answering a pre-flight question before walking away. Rewrite the isolation-ladder description to mirror the English explanation of five forced rules plus an interactive sixth rung, including invocation timing, recommendation rationale, user preference handling, and headless fallback.	skills/autopilot/guide.zh.md
Update catalog highlights to reflect pre-flight-based isolation decision instead of purely automatic ladder.	Replace the English highlight about a six-rule ladder deciding isolation while the tree is clean with text explaining that forced cases are auto-resolved and the remaining choice is handed back as a pre-flight question. Update the Chinese highlight to the same effect, clarifying that isolation is settled up front with a pre-flight question for the one genuinely free choice.	skills/autopilot/catalog.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've left some high level feedback:

• The description of Isolation rule 6 in SKILL.md is quite dense; consider breaking the three governing clauses (prior preference, structured vs plain-text question, headless fallback) into a short bulleted list to make the decision flow easier to scan during implementation.
• Now that step 2 is the isolation pre-flight and step 3+ are the autonomous stretch, it may help to add a brief explicit statement in SKILL.md’s Sequence section about when the “no-interruption” promise starts (i.e., after isolation is settled) to avoid any ambiguity for harness implementers.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The description of Isolation rule 6 in SKILL.md is quite dense; consider breaking the three governing clauses (prior preference, structured vs plain-text question, headless fallback) into a short bulleted list to make the decision flow easier to scan during implementation.
- Now that step 2 is the isolation pre-flight and step 3+ are the autonomous stretch, it may help to add a brief explicit statement in SKILL.md’s Sequence section about when the “no-interruption” promise starts (i.e., after isolation is settled) to avoid any ambiguity for harness implementers.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}