Back to Details

planning-preflight

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Planning Preflight (internal)

规划预检（内部）

The single owner of the planning-side repository gates. 
plan-feature
and 
plan-fix
consume this one contract instead of each internal repeating its own normalized-state read and architectural classification.
This skill uses a two-stage contract to resolve the tension between: (1) the need for planners to read the NRS early (architecture discovery is read-only and required to inform the plan), and (2) the requirement that the final architectural classification only happens after the complete engineering plan exists.
规划端仓库门控的唯一所有者。
plan-feature
和
plan-fix
使用这一份协议，而非各自重复执行规范化状态读取和架构分类操作。
该技能使用两阶段协议来解决以下两者之间的矛盾： (1) 规划人员需要提前读取NRS（架构探索为只读操作，且是制定计划的必要步骤），以及 (2) 最终架构分类必须在完整工程计划确定后才能进行的要求。

When to use

使用场景

Any planner route that can write planning artifacts:
  • plan-feature
    — every route that will scaffold (scoped, issue, 
    --next
    ).
  • plan-fix
    — every fix-SPEC draft.
Composed internals (
plan-feature-from-issue
, 
plan-feature-scaffold
) consume the same result via the in-turn planning context the router creates; they never re-run discovery or classification.
任何可写入规划工件的规划路由：
  • plan-feature
    — 所有将执行脚手架操作的路由（限定范围、问题、
    --next
    ）。
  • plan-fix
    — 所有修复SPEC草案。
组合内部组件（
plan-feature-from-issue
、
plan-feature-scaffold
）通过路由创建的规划上下文复用相同结果；它们不会重新执行探索或分类操作。

Two-Stage Contract

两阶段协议

Stage 1 — NRS read during planning (lightweight)

第一阶段：规划期间读取NRS（轻量级）

While the plan is still being built, routers may perform a read-only consumption of the normalized repository state (NRS) for architectural context. At this stage only the NRS port is classified; the architectural classification is deferred.
Record the Stage 1 result using the following format:
text
Preflight: Stage 1 — NRS <consumed|n/a> · arch: deferred
This result informs the plan but does not block emission.
在计划制定过程中，路由可读取规范化仓库状态（NRS）以获取架构上下文，此操作为只读。在该阶段仅对NRS端口进行分类，架构分类将延迟执行。
使用以下格式记录第一阶段的结果：
text
Preflight: Stage 1 — NRS <consumed|n/a> · arch: deferred
该结果为计划提供参考，但不会阻止工件发布。

Stage 2 — Full classification after plan cut (final)

第二阶段：计划确定后进行完整分类（最终）

Once the complete engineering plan exists (the SPEC is filled and the phases are cut), run the FULL architectural classification exactly once per plan — never per-composed-internal.
Discover the optional project invariant document declared in the documentation map (normally 
docs/architecture/ARCHITECTURAL_INVARIANTS.md
). If absent, record 
n/a: no project invariants declared
and pass. For every applicable rule, cite its ID and repository evidence and classify the planned change as 
preserves
, 
violates
, 
introduces
, or 
changes
. Only 
preserves
may reach emission. A violation, new rule, or changed rule stops for an explicit architectural decision through the project's declared authority; never convert it into an engineering task or infer approval from the SPEC. Use frozen NRS facts when available, but repository inspection remains authoritative.
Record the Stage 2 result using the following format:
text
Preflight: NRS <consumed|n/a> · invariant classification: <preserves|violates|introduces|changes> (n/a when no invariants declared)
当完整工程计划确定后（SPEC已填写且阶段划分完成），每个计划仅执行一次完整架构分类操作——绝不为每个组合内部组件重复执行。
查找文档映射中声明的可选项目不变量文档（通常为
docs/architecture/ARCHITECTURAL_INVARIANTS.md
）。若不存在，则记录
n/a: no project invariants declared
并通过检查。对于每个适用规则，需引用其ID和仓库证据，并将计划变更分类为
preserves
（保留）、
violates
（违反）、
introduces
（引入）或
changes
（变更）。只有
preserves
的分类结果可进入工件发布环节。若出现违反、新规则或规则变更的情况，需暂停流程并通过项目指定的权限机构做出明确的架构决策；绝不能将其转化为工程任务或从SPEC中推断批准结果。若有已冻结的NRS事实则优先使用，但仓库检查结果仍具有权威性。
使用以下格式记录第二阶段的结果：
text
Preflight: NRS <consumed|n/a> · invariant classification: <preserves|violates|introduces|changes> (n/a when no invariants declared)

When to run Stage 2

何时执行第二阶段

Run Stage 2 immediately after the engineering plan is complete and before the router emits artifacts. This is the gate that decides whether the plan can be emitted or must stop for an architectural decision.
Stage 2 must also run whenever a previously-passed plan is re-validated after the engineering plan changes (e.g., a new phase was added or the SPEC was expanded). In that case, re-run only the invariant rules that may have been affected by the change.
在工程计划完成后、路由发布工件前立即执行第二阶段。这是决定计划是否可发布或是否需要暂停以做出架构决策的门控环节。
每当已通过检查的计划在工程计划变更后（例如添加新阶段或扩展SPEC）需要重新验证时，也必须执行第二阶段。此时，仅需重新运行可能受变更影响的不变量规则。

Step 0 — Consume the normalized repository state

步骤0：处理规范化仓库状态

When 
docs/workflow/REPOSITORY_STATE.md
exists, plan from its frozen facts and decisions. An absent fact may be inspected; a conflict is a resolver contradiction, never a rewrite. Planned work and documentation are not implementation evidence. A present ledger whose status is 
draft
, 
contradicted
, or 
resolved
stops planning and routes to discovery or resolution first. If no ledger exists, inspect the repository directly and record 
n/a: no normalized repository state
; NRS is optional.
当
docs/workflow/REPOSITORY_STATE.md
存在时，基于其中已冻结的事实和决策制定计划。若缺少某些事实，可进行检查；若出现冲突，则为解析器矛盾，绝不能重写。计划中的工作和文档不属于实现证据。若存在状态为
draft
（草稿）、
contradicted
（矛盾）或
resolved
（已解决）的分类账，则需暂停规划并先进入探索或解决流程。若不存在分类账，则直接检查仓库并记录
n/a: no normalized repository state
；NRS为可选内容。

Result — fixed classification record

结果：固定分类记录

Return exactly one line back to the router:
  • Stage 1 (while planning):
text
Preflight: Stage 1 — NRS <consumed|n/a> · arch: deferred
  • Stage 2 (after plan is cut, final gate):
text
Preflight: NRS <consumed|n/a> · invariant classification: <preserves|violates|introduces|changes> (n/a when no invariants declared)
preserves
(or 
n/a: no project invariants declared
) → the router proceeds to emit the artifacts and register the roadmap/fix entry. Any other classification → STOP with the fixed ARCHITECTURAL INVARIANT GATE BLOCKED block:
text
→ Next: resolve the architectural decision first — <rule-id>: <classification> (<evidence>).
  Run /design-feature or the project's declared decision authority; do not convert this into a phase task.
向路由返回恰好一行结果：
  • 第一阶段（规划期间）：
text
Preflight: Stage 1 — NRS <consumed|n/a> · arch: deferred
  • 第二阶段（计划确定后，最终门控）：
text
Preflight: NRS <consumed|n/a> · invariant classification: <preserves|violates|introduces|changes> (n/a when no invariants declared)
若结果为
preserves
（或
n/a: no project invariants declared
）→ 路由继续发布工件并注册路线图/修复条目。任何其他分类结果→ 暂停流程并返回固定的ARCHITECTURAL INVARIANT GATE BLOCKED（架构不变量门控阻塞）块：
text
→ Next: resolve the architectural decision first — <rule-id>: <classification> (<evidence>).
  Run /design-feature or the project's declared decision authority; do not convert this into a phase task.

Guardrails

约束规则

  • One classification per plan, taken after the engineering plan exists — never in each composed internal.
  • Never let the SPEC, a passing test, or a roadmap row infer the decision.
  • Docs only — no code, no branch, no forge writes.
  • Two-stage contract: Stage 1 is lightweight NRS read; Stage 2 is the final architectural gate. Stage 2 supersedes Stage 1 for emission decisions.
  • 每个计划仅执行一次分类，且必须在工程计划确定后进行——绝不为每个组合内部组件执行。
  • 绝不能从SPEC、通过的测试或路线图条目推断决策结果。
  • 仅涉及文档——不涉及代码、分支或代码托管平台写入操作。
  • 两阶段协议：第一阶段为轻量级NRS读取；第二阶段为最终架构门控。在工件发布决策中，第二阶段的结果优先于第一阶段。