port-feature

移植功能

将 REFERENCE 实现中已能正常工作的功能移植到 TARGET 技术栈，并遵循目标栈自身的惯用方式。在 discover → plan 入口处，将移植所需的信心依据——功能的行为、目标已有的内容、缺少的内容以及可复用的内容——整理到磁盘上的一份差距图中，然后交接：只执行一轮，不循环，也不构成流水线。

输入

先根据请求和成本较低的仓库证据（Project Matrix、cwd、GLOSSARY.md、ADR 名称）推断；只有确实缺少信息时，才按 /feature-prompt 的方式访谈：

• 要移植的功能——要移植的行为或工作流。
• REFERENCE PROJECT-CODE——行为真相的来源。
• TARGET PROJECT-CODE——功能要落地的位置。

只有三项都明确后才能开始发现；如果用户不在，且其中一项无法推断，就停止并添加一条 Needs-user 说明，准确指出缺少哪一项——绝不猜测。

真相来源原则

在差距图的每个部分都贯彻以下原则：

• REFERENCE 是行为真相——包括工作流、导航（菜单位置、入口、路由）、权限、数据影响和状态。当目标当前行为与参考实现不一致时，以参考实现为准（除非用户已明确决定更改行为——这应是 /grill-with-field 做出的决定，而不是本技能擅自决定）。
• TARGET 的设计系统是 UI 真相。 当参考 UI 与目标设计系统冲突时，采用设计系统，并在 UI/设计差距部分记录偏差（参考实现采用了 X；目标设计系统采用了 Y；因此选择设计系统）。
• 绝不硬编码技术栈规则。 从目标的约束上下文中读取规则——GLOSSARY.md、specs/adr/、AGENTS.md——以及其 UI 编码技能。如果移植依赖的规则（技术栈版本、设计系统约定、组件规范、ADR 位置）未记录在这些上下文中，不要自行编造；将其列在待确认问题 / Needs-user 中，而不是猜测。

规则

• 零署名。 任何输出中都不得添加或保留共同作者、AI 或工具署名；将此规则写入差距图。
• 只建议，不自动串联。 结束时建议基于差距图运行 /grill-with-field，然后停止。规划和创建问题须等待单独请求。
• 此处绝不实现。 不得修改产品代码、配置或迁移；唯一允许的写入是差距图文件。
• 在所有位置使用 Project Matrix 中完整的 PROJECT-CODE；绝不将一个项目的约定、设计令牌或组件混入另一个项目。
• 仅进行有针对性的检索。 以类似 /feature-discovery 的方式，通过有针对性且有证据支持的搜索（使用 rg/git grep 搜索准确的路由/路径/符号/状态）追踪参考实现并调查目标。绝不批量读取整个仓库或其 specs/ 目录树来“查找所有内容”。
• 先读取上下文，再做决定。 GLOSSARY.md 和相关 ADR 描述已记录的决策；当前代码和测试展示已实现的行为。遵循当前用户明确作出的决定，记录与旧上下文之间的冲突，并将原生 CLI 记忆视为需要核实的线索。
• 决策必须落为文档。 输出是持久化的差距图文件，而不是聊天摘要；聊天中只报告写入了什么以及阶段更新。
• 子 Agent：对于相互独立的工作，自动分派本地工作流——绝不使用云端 Agent；分派时说明工作流数量，并在每个工作流完成时报告。

流程

1. 读取目标的约束上下文

读取 GLOSSARY.md（旧版 CONTEXT.md）、AGENTS.md 和 UI 编码技能，以了解技术栈和设计系统规则。按主题或关联决策定位相关 ADR；只阅读相关 ADR，不要读取整个 specs/adr/ 目录树。当已掌握约束规则，或已将每项缺失记录到待确认问题中时，此步骤完成。

2. 探索参考实现

按 /feature-discovery 的方式，追踪真实行为、工作流、导航、权限、状态和数据影响。包括字段验证和默认值、字段间依赖关系、行操作和批量操作、导入／导出、自动刷新，以及受角色限制的控件。基于模拟数据、测试样例或存根数据的路径并非真实行为；请标记为推断，并列入「待解答问题」。完成标准：每项陈述都附有具体引用（file:symbol、路由、迁移或测试）。

3. 调查目标项目的当前状态

目前已有的内容、相较参考实现哪些不完整或有误，以及哪些设计系统组件和现有模式可复用。如果该功能有 UI，请在经授权的本地环境中找到并检查目标组件预览。如果没有预览或无法查看，请列出组件源码清单并记录此限制；不要虚构预览路由。

4. 分派范围明确的工作线（可选）

拆分互不重叠的探索工作，例如一条工作线追踪参考实现，另一条调查目标项目。各工作线不得探索相同内容；主 Agent 负责综合结论、判断不确定性并产出文档。

差距图文档

每个移植功能编写一份差距图：

<artifacts-root>/specs/port/<feature-slug>-gapmap.md

解析 <artifacts-root>：如果存在 *.code-workspace 目录，则使用该目录；否则使用每个上下文对应的根目录（仓库根目录中的 GLOSSARY-MAP.md；旧版为 CONTEXT-MAP.md）；否则使用仓库根目录。<feature-slug> 根据功能名称采用 kebab-case，最多约 4 个词，仅限 ASCII 字符。差距图是按需创建的 slug 文件，不占用 NNNN 提示词／ADR 序列。

更新前先阅读现有差距图。保留用户修改和已记录的决策；如果新发现与之矛盾，请指出冲突并等待指示，再替换相关内容。如果用户暂时无法联系，请保留原内容，并将冲突追加到「待解答问题」下。

确认现有图中列明的是相同的 REFERENCE/TARGET 配对。如果配对不同，请保留该图，并使用 <feature-slug>-<REFERENCE-CODE>-<TARGET-CODE>-gapmap.md；在输出和完成检查中使用解析后的路径。

按顺序编写以下九个部分，每部分最多 3 条项目符号——链接或引用证据（file:line、路由、迁移、测试），切勿直接粘贴证据：

# Port Gap Map — <feature> (<REFERENCE-CODE> → <TARGET-CODE>)

Zero attribution: never add or leave co-author, AI, or tool attribution in any output.

## 1. Reference behaviour / workflow
- <behaviour/permission/state/data-effect> — evidence: `file:symbol`, route, migration, test.
- Navigation: where the feature lives in the reference and any moves the port implies.

## 2. Target current state
- <what exists today for this feature in the target> — evidence refs.
- <target piece that already matches the reference> — do not touch; evidence ref.

## 3. Missing / wrong in target
- <gap or divergence from the reference> — absent, partial, or behaving differently.

## 4. Reusable target code & DS components
- <existing target seam/service/component to extend> — path + why it fits.
- <design-system component from the target preview> — where it applies.

## 5. Tests needed
- Success paths, validation, permission checks, empty/error/success states, data effects, regressions to guard.

## 6. UI / design gaps vs reference (and forced DS deviations)
- <reference UI element> → <target DS equivalent>.
- Forced deviation: reference did X; target DS does Y; chose DS because <rule/source>.

## 7. Risks
- <behaviour, data, permission, or migration risk> and where it bites.
- Coexistence: while reference and target both run on shared data, which one writes.

## 8. First slice
- One thin vertical slice that cuts through all layers and is testable on its own — not a layer, not a big-bang.

## 9. Open questions
- <evidence-derived question for /grill-with-field>. List them; do not block on them.

各部分规则（已填写的项目示例见 references/gapmap-example.md）：

• 第 1–4 部分的每项陈述都必须附有具体证据引用；未经证实的陈述须标记为推断，不得当作事实。
• 第 5 部分为后续验收标准提供初稿——涵盖其模板项目符号列出的每个类别。
• 第 5 部分须标明第 1 部分中每项没有参考测试的行为；为其编写特征化测试，或将其列入「待解答问题」。

输出

每次阶段转换时输出 Stage / Found / Next / Needs user，每个字段各占一行。最终更新：

Stage: port-feature — wrote specs/port/<feature-slug>-gapmap.md (<REFERENCE-CODE> → <TARGET-CODE>).
Found: <N> reference behaviours traced; target is <absent/partial/diverging>; <M> reusable target/DS pieces; <K> forced DS deviations; <R> risks.
Next: run /grill-with-field on the gap map to challenge it and produce the ADR (next number in specs/adr/).
Needs user: <open questions to steer, or ambiguous reference/target mapping, or "none">.

Suggested next skills (optional):
- /grill-with-field: challenge the gap map and record the porting decisions as an ADR.
- /prototype: if a UI/interaction open question needs to be seen or felt before planning.

完成标准

• 差距图已保存至解析后的路径；必要时包含 PROJECT-CODE，以避免与其他配对的文件重名；九个部分标题均存在且内容非空
• git status 显示本次运行未在差距图文件之外创建或修改任何文件——未实现任何内容
• 已输出最终的 Stage / Found / Next / Needs user 更新，并以建议页脚结束