plan-feature-from-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Plan Feature — From Issue (internal)

Plan Feature — 从 Issue 转化（内部流程）

Convert a feature-request issue into the project's planning artifacts, keeping a clean issue → SPEC → PR(Closes #n) trace. Writes the SPEC's product half (same two-halves convention

design-feature

uses) and must satisfy capability closure before handing off — a thin issue does not get a shortcut around it.

将功能请求 issue 转化为项目的规划工件，保持清晰的 issue → SPEC → PR(Closes #n) 追溯链路。撰写 SPEC 的产品端内容（遵循与

design-feature

相同的两端约定），且在移交前必须满足能力闭环——信息不足的 issue 无法走捷径跳过此步骤。

When to use

适用场景

The
```
plan-feature
```
router calls this when the input is a GitHub issue (or
```
--from-issue N
```
) that describes new product capability.

If the issue is a bug or tech-debt, stop and route it:

triage-issue

to classify, then

plan-fix

execute-phase --fix

. This skill is for genuine features only.

当输入为描述新产品能力的 GitHub issue（或使用
```
--from-issue N
```
参数）时，
```
plan-feature
```
路由会调用此流程。

如果 issue 是漏洞或技术债务，请停止当前流程并重新路由：先通过

triage-issue

进行分类，再执行

plan-fix

execute-phase --fix

。此流程仅适用于真正的功能需求。

Step 0 — Discover the project (always first)

步骤 0 — 了解项目（始终优先执行）

Per the agent guide's Workflow conventions + documentation map, then read what THIS skill needs: the feature SPEC template, the roadmap, and the issue/PR templates (

.github/ISSUE_TEMPLATE/

.github/PULL_REQUEST_TEMPLATE.md

) so the SPEC mirrors the fields reviewers expect. Then read the issue (forge CLI per the project's Workflow conventions — examples use

gh

gh issue view <N> --json number,title,body,labels,state,comments

根据 Agent 指南中的工作流约定 + 文档映射，先了解此流程所需的内容：功能 SPEC 模板、路线图以及 issue/PR 模板（

.github/ISSUE_TEMPLATE/

、

.github/PULL_REQUEST_TEMPLATE.md

），确保 SPEC 包含评审人员期望的字段。然后读取 issue（遵循项目工作流约定使用 Forge CLI——示例中使用

gh

）：

gh issue view <N> --json number,title,body,labels,state,comments

Process

流程步骤

Classify first. Confirm it is a feature. Not a feature if it describes a defect, regression, duplicated code, perf debt, or carries a "when to fix / trigger" clause → hand to
```
triage-issue
```
. State the verdict explicitly.
Normalize language. If not in the project's docs language (this repo: English), translate before drafting any artifact.
Map to the roadmap. Assign the next number + slug. Identify dependencies and conflicts with existing features, coupling/migration risks, and whether it should instead extend an existing feature.
Close product-half gaps proactively. Compare the issue against what a complete SPEC product half needs (goals, scope in/out, business goals, i18n/SEO/a11y/pricing per the docs map, a UI design reference when the feature has a UI surface), probing the same fixed vagueness rubric
```
design-feature
```
's interview uses: affected users/roles · error & edge states · data shape · boundaries & limits · out of scope · success criteria — each slot filled or explicit
```
n/a: <reason>
```
. For each genuine gap you can't safely default, ask the user one question per turn, never batched, each with a recommended default; never ask what the issue or docs already answer. Structural hand-off threshold: if ≥ 3 rubric slots remain unfillable from the issue plus the answers so far, stop and hand the feature to
```
design-feature
```
(the thin-issue rule below, now with a fixed trigger) instead of continuing to interview here.
Satisfy capability closure. Walk the same fixed checklist
```
design-feature
```
uses (per entity: CRUD + state transitions, each with UI + API + test, or explicit
```
n/a: <reason>
```
; per capability: entry point + ACL; per role: assigned/revoked/viewed where) into the SPEC's
```
## Capability closure
```
and
```
## Acceptance criteria
```
. A thin issue that doesn't carry enough to fill it is not a shortcut around the gate — hand it to
```
design-feature
```
(compose in-turn only at ≥ this skill's tier, per Guardrails; otherwise hand off with
```
run /design-feature <slug>
```
and stop here) rather than stamping
```
designed
```
on a hollow closure.
Size it. Estimate
```
XS / S / M / L
```
(scale defined in the SPEC template) and record it in the SPEC. XS/S → the SPEC is the only planning artifact (single-pass execution); M/L → full artifact set. If L, propose splitting.
Produce the SPEC product half. Fill it and stamp
```
## Design status: designed
```
once closure is complete; set the roadmap row (added at
```
idea
```
first if it didn't exist) to
```
defined
```
in the same edit — the same
```
idea → defined
```
transition
```
design-feature
```
owns, performed here when this skill is the one that satisfies closure. The
```
plan-feature
```
router then runs
```
plan-feature-scaffold
```
for the engineering half +
```
defined → planned
```
roadmap promotion.
Wire traceability. Record
```
#N
```
in the SPEC; the PR body must include
```
Closes #N
```
so the issue closes on merge.

Hand off — return exactly (fixed completion report, back to the router):

ISSUE #<N> → SPEC <slug> — size: <XS|S|M|L>
Verdict: feature (not bug/debt — else this would have routed to triage-issue)
Gaps closed: <n> asked / <n> defaulted (logged)   Closure: designed | handed to design-feature
Traceability: Closes #<N> wired
→ scaffold next (plan-feature-scaffold)

先分类。确认该请求为功能需求。如果内容描述的是缺陷、回归问题、重复代码、性能债务，或包含「修复时机/触发条件」条款，则不属于功能需求→移交至
```
triage-issue
```
。需明确给出判定结果。
统一语言。如果内容不符合项目文档指定的语言（本仓库：英文），需先翻译再起草任何工件。
映射到路线图。分配下一个编号和别名（slug）。识别与现有功能的依赖关系和冲突、耦合/迁移风险，以及是否应扩展现有功能而非新增。
主动填补产品端内容缺口。将 issue 内容与完整 SPEC 产品端内容的要求进行对比（目标、包含/排除范围、业务目标、文档映射中规定的国际化(i18n)/搜索引擎优化(SEO)/无障碍访问(a11y)/定价规则，若功能涉及 UI 界面则需提供 UI 设计参考），使用与
```
design-feature
```
访谈流程相同的固定模糊性评估准则进行核查：受影响的用户/角色 · 错误与边缘状态 · 数据结构 · 边界与限制 · 排除范围 · 成功标准——每个项都需填写或明确标注
```
n/a: <原因>
```
。对于无法安全默认的真实缺口，每次仅向用户提出一个问题，切勿批量提问，且每个问题需附带建议默认值；切勿询问 issue 或文档中已给出答案的问题。结构化移交阈值：若结合 issue 内容和已获取的答案后，仍有≥3项评估准则无法填充，则停止当前访谈，将功能需求移交至
```
design-feature
```
（即下文的信息不足 issue 规则，现已设置固定触发条件）。
满足能力闭环。使用与
```
design-feature
```
相同的固定检查清单（每个实体：CRUD + 状态转换，每项需包含 UI + API + 测试，或明确标注
```
n/a: <原因>
```
；每个能力：入口点 + 访问控制列表(ACL)；每个角色：分配/撤销/查看的场景），填写 SPEC 的
```
## Capability closure
```
和
```
## Acceptance criteria
```
部分。信息不足的 issue 无法绕过此关卡走捷径——需将其移交至
```
design-feature
```
（根据「防护规则」，仅当此流程运行等级≥
```
design-feature
```
等级时可依次组合执行；否则通过
```
run /design-feature <slug>
```
移交并在此停止），切勿在能力闭环内容空洞的情况下标记
```
designed
```
。
评估规模。按照
```
XS / S / M / L
```
进行估算（规模定义见 SPEC 模板）并记录在 SPEC 中。XS/S 规模→仅需 SPEC 作为规划工件（单次执行）；M/L 规模→需完整工件集。若为 L 规模，建议拆分。
生成 SPEC 产品端内容。完成闭环后填写内容并标记
```
## Design status: designed
```
；在同一编辑操作中将路线图中的对应条目（若不存在则先以
```
idea
```
状态添加）设置为
```
defined
```
——此
```
idea → defined
```
状态转换由
```
design-feature
```
负责，但当此流程完成能力闭环时，在此执行该转换。随后
```
plan-feature
```
路由将运行
```
plan-feature-scaffold
```
生成工程端内容，并将路线图状态从
```
defined
```
升级为
```
planned
```
。
建立可追溯链路。在 SPEC 中记录
```
#N
```
；PR 正文必须包含
```
Closes #N
```
，以便合并时自动关闭对应的 issue。

移交——严格返回（固定格式的完成报告，返回至路由）：

ISSUE #<N> → SPEC <slug> — size: <XS|S|M|L>
Verdict: feature (not bug/debt — else this would have routed to triage-issue)
Gaps closed: <n> asked / <n> defaulted (logged)   Closure: designed | handed to design-feature
Traceability: Closes #<N> wired
→ scaffold next (plan-feature-scaffold)

Guardrails

防护规则

Don't silently expand scope beyond the issue — surface additions as proposals.
Don't open the feature branch or write code here.
Keep the
```
Closes #N
```
link; an issue-born feature must close it.
Never stamp
## Design status: designed
with a blank Capability closure row — the same rule
```
design-feature
```
follows; a thin issue hands off instead of faking closure.
Composition tier. Composing
```
design-feature
```
in-turn for a thin issue is allowed only when this skill is running at ≥
```
design-feature
```
's tier (planning-class — strongest model / highest effort); otherwise hand off (
```
run /design-feature <slug>
```
) rather than under-power it.
Otherwise honor the project's Workflow conventions (branch/PR, docs-language).

切勿在未告知的情况下扩展超出 issue 范围的内容——新增内容需作为提案提出。
请勿在此流程中创建功能分支或编写代码。
保留
```
Closes #N
```
链接；由 issue 转化而来的功能需求必须通过此链接关闭原 issue。
切勿在能力闭环内容为空的情况下标记
## Design status: designed
——此规则与
```
design-feature
```
一致；信息不足的 issue 需移交而非伪造闭环。
组合执行等级。仅当此流程运行等级≥
```
design-feature
```
等级（规划类——最强模型/最高投入）时，才允许为信息不足的 issue 依次组合执行
```
design-feature
```
；否则需移交（
```
run /design-feature <slug>
```
），避免能力不足导致的问题。
除此之外，需遵循项目的工作流约定（分支/PR、文档语言）。

Architectural invariants

架构不变量

The planning preflight owns the normalized repository state read and the ONE final architectural classification for the whole plan. Consume it here before writing the product half: for each applicable invariant rule, cite its ID and repository evidence and classify the issue proposal as

preserves

violates

introduces

, or

changes

. Only

preserves

can be stamped

designed

; every other classification stops for an explicit architectural decision through the project-declared authority — never before the full plan exists, and never inferred from the issue body, SPEC, or passing test.

规划预检负责读取标准化的仓库状态，并对整个计划做出唯一最终的架构分类。在撰写产品端内容前需参考此结果：对于每个适用的不变量规则，引用其 ID 和仓库证据，并将 issue 提案分类为

preserves

（保持）、

violates

（违反）、

introduces

（引入）或

changes

（变更）。仅

preserves

分类的提案可标记为

designed

；其他所有分类均需暂停，通过项目指定的权限方做出明确的架构决策——切勿在完整计划形成前做出决策，也切勿从 issue 内容、SPEC 或测试通过结果中推断决策。

Relationship to other skills

与其他流程的关系

```
triage-issue
```
— decides bug vs feature vs defer; call it if unsure.
```
plan-fix
```
— the fix-side sibling for bug/debt issues.
```
design-feature
```
— receives thin issues this skill cannot safely close capability closure for; both write the SPEC's product half in the same format.
```
plan-feature-scaffold
```
— fills the engineering half once the product half is designed.
```
execute-phase
```
— executes the phases; its PR carries
```
Closes #N
```
.

```
triage-issue
```
——判定漏洞、功能需求或延期处理；若不确定则调用此流程。
```
plan-fix
```
——处理漏洞/技术债务 issue 的对应流程。
```
design-feature
```
——接收此流程无法安全完成能力闭环的信息不足 issue；两者以相同格式撰写 SPEC 的产品端内容。
```
plan-feature-scaffold
```
——在产品端内容完成后填写工程端内容。
```
execute-phase
```
——执行各阶段；其 PR 需包含
```
Closes #N
```
。

Done when

完成标准

A filled SPEC product half + planning artifacts exist, roadmap-registered.
Capability closure is satisfied (or the issue was handed off to
```
design-feature
```
instead of faking it) and
```
## Design status
```
is accurate.
The roadmap row status is
```
defined
```
(added at
```
idea
```
first if new) whenever
```
## Design status: designed
```
was stamped — never
```
defined
```
on a hollow closure, never left at
```
idea
```
once
```
designed
```
is stamped.
```
#N
```
is recorded and the PR plan includes
```
Closes #N
```
.
Scope gaps were resolved with the user, not assumed.

已填写完整的 SPEC 产品端内容 + 规划工件，并已在路线图中注册。
能力闭环已满足（或已将 issue 移交至
```
design-feature
```
而非伪造闭环），且
```
## Design status
```
状态准确。
每当标记
```
## Design status: designed
```
时，路线图对应条目的状态需设置为
```
defined
```
（若为新增条目则先以
```
idea
```
状态添加）——切勿在闭环内容空洞时设置为
```
defined
```
，也切勿在标记
```
designed
```
后仍保留
```
idea
```
状态。
已记录
```
#N
```
，且 PR 计划包含
```
Closes #N
```
。
范围缺口已与用户确认解决，而非自行假设。