executing-plans-preflight

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Executing Plans Preflight

开发计划预检查

Semi-automatic git state gate. Detects issues, proposes fixes, executes on confirmation. Run this before any implementation work begins — it ensures git state is ready so you start from a clean, correct baseline.

Not in a git repo? Say

Not a git repository — skipping preflight.

and move on.

半自动化的git状态校验工具。检测问题、提出修复方案，经确认后执行。在任何开发工作开始前运行此工具——它能确保git状态就绪，让你从干净、正确的基线开始工作。

若不在git仓库中？则提示「Not a git repository — skipping preflight.」并继续后续流程。

Checks

检查项

Run in order. Pass silently when nothing is wrong — only speak up when there is something to fix.

按顺序执行检查。无问题时静默通过——仅在存在需修复的问题时发出提示。

1. Branch Context

1. 分支上下文

Detect default branch via

origin/HEAD

. Fallback: treat

main

master

as default if detection fails.

Detached HEAD → ask which branch to switch to (cannot infer).
On default branch → infer a branch name from the plan in conversation (title → kebab-case, prefix with conventional commit type:
```
feat/
```
,
```
fix/
```
,
```
docs/
```
,
```
refactor/
```
,
```
perf/
```
,
```
test/
```
,
```
chore/
```
,
```
ci/
```
,
```
build/
```
; default
```
feat/
```
). Propose it, let user confirm or rename, then
```
git switch -c
```
. No plan in conversation? Ask directly — don't guess from filesystem.
Otherwise → silent pass.

通过

origin/HEAD

检测默认分支。如果检测失败，默认将

main

master

视为默认分支。

分离HEAD状态 → 询问要切换到哪个分支（无法自动推断）。
当前为默认分支 → 从对话中的计划推断分支名称（标题转为短横线分隔格式，前缀使用约定式提交类型：
```
feat/
```
、
```
fix/
```
、
```
docs/
```
、
```
refactor/
```
、
```
perf/
```
、
```
test/
```
、
```
chore/
```
、
```
ci/
```
、
```
build/
```
；默认使用
```
feat/
```
）。提出建议分支名，让用户确认或重命名，然后执行
```
git switch -c
```
。对话中无计划？直接询问——不要从文件系统猜测。
其他情况 → 静默通过。

2. Worktree Clean

2. 工作树清洁度

Run

git status --porcelain

. Everything counts as dirty (staged, unstaged, untracked).

Clean → silent pass.
Dirty → list paths, ask user to resolve or say "continue" to override. Record the override — Check 3 needs to know. Don't help with commit/stash; that's the user's call, because commit scope and message are conscious decisions that shouldn't be buried inside preflight.

执行

git status --porcelain

。所有状态都视为未提交（已暂存、未暂存、未追踪）。

工作树清洁 → 静默通过。
存在未提交内容 → 列出文件路径，询问用户解决问题或输入「continue」跳过检查。记录跳过操作——检查项3需要知晓此情况。不要协助提交/暂存；这是用户的决策，因为提交范围和信息是需要明确考量的事项，不应被预检查流程掩盖。

3. Remote Sync

3. 远程同步

Run

git fetch

. If fetch fails, warn and continue with local info — don't claim remote state is fresh when it isn't.

No upstream / ahead / up-to-date → silent pass.
Upstream gone → ask: clear tracking or recreate?
Behind/diverged → propose
```
git pull --rebase
```
. If dirty files were overridden in Check 2, warn that pull may conflict and offer to skip sync.

New branches from Check 1 have no upstream — that's expected, don't push.

执行

git fetch

。如果fetch失败，发出警告并基于本地信息继续——不要在远程状态不新鲜时声称其是最新的。

无上游分支 / 本地领先 / 与远程同步 → 静默通过。
上游分支已删除 → 询问：清除追踪还是重新创建？
本地落后/与远程分叉 → 建议执行
```
git pull --rebase
```
。如果在检查项2中跳过了未提交文件的处理，需警告拉取可能引发冲突，并提供跳过同步的选项。

检查项1中新创建的分支没有上游分支——这是预期情况，无需推送。

Report

报告

One-line conclusion after all checks. Each fix gets its own line before it.

Switched to `feat/add-auth` (was on main)
Preflight passed. Ready to go.

If dirty files were overridden, end with

Proceeding with uncommitted changes.

instead of

Ready to go.

所有检查完成后输出一行总结。每项修复操作单独占一行显示在总结之前。

Switched to `feat/add-auth` (was on main)
Preflight passed. Ready to go.

如果跳过了未提交文件的处理，结尾显示

Proceeding with uncommitted changes.

而非

Ready to go.

Why these guardrails exist

设置这些防护规则的原因

Confirm before executing — git operations are hard to undo; one wrong
```
switch -c
```
or
```
pull --rebase
```
on the wrong branch can cost real work.
Allow dirty override — blocking unconditionally was v2's biggest friction point. The user knows their working state better than preflight does.
Never push — preflight manages local state only. Publishing is a separate, deliberate step.

执行前确认 —— git操作难以撤销；在错误分支上执行
```
switch -c
```
或
```
pull --rebase
```
可能会导致实际工作成果丢失。
允许跳过未提交内容检查 —— 无条件阻止是v2版本最大的痛点。用户比预检查工具更了解自己的工作状态。
绝不自动推送 —— 预检查仅管理本地状态。推送是一个独立的、需主动触发的步骤。