Impeccable init 流程全解析：用 PRODUCT.md 捕获产品真相，为 AI 设计工作确立唯一事实源

init 是 Impeccable 设计技能（skill）体系中的第一个落地动作：它在不触碰任何视觉世界的前提下，把「用户是谁、产品做什么、哪些约束必须被永久保留」这类持久化产品事实沉淀进项目根的 PRODUCT.md。本文基于仓库内的权威参考文档 .gemini/skills/impeccable/reference/init.md，逐步拆解 init 的六阶段工作流（状态加载 → 项目探索 → 产品访谈 → 编写 PRODUCT.md → 记录工作流默认 → 收尾/恢复），并结合 SKILL.md、根 PRODUCT.md、.impeccable/config.json 与测试用例，讲清 schema 版本机制、buildPath 的 comp/code 语义以及它与其他设计命令的边界。读完你将掌握：在什么项目状态下该跑 init、每一步问什么不问什么、如何写出一份符合 impeccable:product-schema 规范的产品记录，以及 init 结束后如何正确地把工作交接给 new-work、document、shape 与 live。

init 在命令体系中的位置：只捕获事实，不发明视觉

在动手之前，先明确 init 的职责边界，否则容易在后续流程中越权。参考 SKILL.md 的命令总览 将 /impeccable init 归入 Build 类命令，一句话描述是「Capture durable product context in PRODUCT.md」；与其配套的脚本元数据 command-metadata.json 给出了更完整的官方定义：

Sets up a project for impeccable. Runs a multi-round discovery interview when context is missing and writes PRODUCT.md (strategic: users, brand, principles); offers DESIGN.md (visual: colors, typography, components) when code exists; pre-configures live mode; then recommends the best commands to run next. Every other command reads these files before doing work. Use once per project.

注意这里官方描述中的 "offers DESIGN.md when code exists" 是命令级摘要的概括性措辞；就 init 参考文档本身而言，其纪律是永不主动兜售 DESIGN.md（详见下文 Step 1），视觉世界的创建与记录由其他命令负责：

• init（本流程）→ 捕获产品真相，只写 PRODUCT.md；
• reference/new-work.md → 创建或扩展视觉世界（DESIGN.md 与 surface brief）；
• reference/document.md → 从既有代码反推记录在位视觉系统（DESIGN.md）；
• shape <surface> → 先做任务访谈拿到确认简报，再进入 new-work；
• craft 是 craft.md 中标注的已废弃别名，直接等价于普通 new-work 请求，不增加任何 setup、访谈、检查点行为；
• teach 是 init 的别名，见 SKILL.md 路由说明。

从命令路由看，什么时候会走到 init？SKILL.md 的 Routing 一节规定：当请求是一般性设计工作、但 PRODUCT.md 缺失且涉及新 surface 或替换视觉世界时，路由先经过 init 再进入 new-work；而对既有代码的局部精修则直接按现状推进，init 只是事后提供而非阻塞。此外，.impeccable 体系的另一条纪律是：PRODUCT.md 是所有后续命令（new-work、document、critique、live 等）读取的前置事实源——doctor 命令在 doctor.md 中明确写着「document owns DESIGN.md, init owns PRODUCT.md」，二者各有其主，互不越界。

Step 1：加载当前状态——先看存量，再决定写什么

init 的第一个动作不是提问，而是加载当前项目状态，原则是：init 只更新「由 context.mjs 解析出的那个 PRODUCT.md 路径」，绝不在旁边另建一个竞争性权威文件。这一点在 SKILL.md 的 Setup 约定 中有更完整的背景：每个会话开始时由 harness 运行一次 context.mjs（base-dir 由运行时解析，node <skill-base-dir>/scripts/context.mjs），它负责装载 PRODUCT.md、DESIGN.md 与匹配的 surface brief，并给出后续命令遵循的指令；init 文档中说的「Use the PRODUCT.md path resolved by context.mjs」正是指这个启动装载结果。（说明：从当前仓库快照看，.gemini/skills/impeccable/scripts/ 目录仅检入了 live-browser 系列脚本与 command-metadata.json 等文件，context.mjs 属于由各 harness 运行时装配的辅助脚本，因此其行为以 SKILL.md 与本文档的契约描述为准。）

针对不同的存量状态，init 采用如下分支策略：

当前状态	init 应做的事
没有 PRODUCT.md	探索项目 → 访谈 → 写一份全新的 PRODUCT.md
PRODUCT.md 已存在	直接问用户「哪些产品知识已过时或缺失」，没有理由就不要重新打开已确认的字段
Legacy PRODUCT.md（老格式）	只补充持久且缺失的事实；若文件里没有 ## Platform 小节，默认平台是 web，除非有证据表明否则不臆断
只有 DESIGN.md	原封不动地保留 DESIGN.md，另建 PRODUCT.md
改版/重塑品牌请求	保留已确认的产品真相（除非用户本人更改）；视觉替换属于稍后 new-work 的职责，不在这里发生

两条硬性禁令贯穿始终：绝不静默覆盖既有文件；绝不在 init 期间主动提议创建 DESIGN.md。如果 init 是被另一个请求顺带触发的（例如先前的任务发现自己缺 PRODUCT.md），那么先完成 PRODUCT.md 再恢复原任务，不要另起炉灶。

Step 2：探索项目——把代码库证据当假设，不当作批准

提问之前，先扫描项目，目标只有一个：避免让用户重复陈述已知事实。文档给出的扫描面包括：产品文档与文案；package/config 与应用边界；功能、工作流、路由与角色；名称、Logo、法律/凭证类资产与品牌承诺；平台与无障碍信号；以及当 live 模式适用时的 dev 命令与入口。

扫描有两个关键心智模型：

1. 代码库证据只是假设，不是用户批准。 仓库里现有的视觉形态只说明「当前世界长这样」，不代表用户确认要延续它。init 应留意项目的视觉成熟度（visual maturity），但不记录、不扩展、不替换视觉世界。
2. 先形成平台假设。 平台只有四种取值：web、ios、android、adaptive（指同一产品确实按操作系统分别适配设计语言的情形）。两条去伪规则很关键：移动端网页仍是 web；给网站套一层原生壳（native wrapper）并不会让它的设计语言变成原生。平台假设不直接落盘，它需要在访谈中向用户单独确认（见 Step 3）。

Step 3：访谈——只问仓库与请求回答不了的材料缺口

init 的访谈纪律可以浓缩为一句：只问那些你无法从仓库或原始请求中得到强证据、且会实质影响未来产品决策的缺口。具体而言：

• 优先使用结构化问题工具；不可用时直接提问并等待答复。
• 轮次上限为三轮，每轮聚焦；撰写一份新 PRODUCT.md 之前，至少要拿到一轮真实的回答或批准；推断出来的结论必须先向用户确认。
• 从「最会改变未来产品决策的未知项」开始，文档给出三个标准开场问题：
  1. 主要用户是谁，处在什么情境，正在完成什么任务（job）？
  2. 产品让什么成为可能，它有怎样「有意义的差异化机制或定位」？
  3. 哪些持久约束、资产、证据或产品事实是未来工作必须保留的？

平台与 Stack 单独确认

平台有歧义时必须单独确认（因为它决定后续是否装载 ios/android/adaptive 指导）。当项目没有任何框架或脚手架、而请求隐含「要构建」时，技术栈是用户决策而非 init 的决策：只问一次——要纯静态 HTML/CSS、特定框架，还是由你推荐——同时问清是否有会约束答案的部署目标，并把结果记入 ## Stack（用户把选择权交回给你时记 delegated，让后续工作知道「选择机会确实提供过」）。只有出现实质性的受众、品牌承诺、证据或无障碍缺口，才允许追加一轮。

无人应答的机械检验

「是否有人在应答」在 init 看来是机械测试而非主观判断：只要工具表面存在问题工具或决策页（decision page），就证明应答机制存在；系统提示里「用户处于无人值守」的声明对本次会话不构成任何证据。正确做法是先用真实的第一轮问题探测一次，只有探测出错或超时后，才允许从显式简报中推断——即便如此，也必须在 PRODUCT.md 里逐条标注每个推断事实，并在第一条回复（而不是最后一条）中披露这种替代，不能把推断伪装成确认。

什么该问、什么不该问

文档用两个清单把访谈边界画得非常清晰：

属于这里（该沉淀为产品真相）：用户、任务、工作流、目的、成功标准、定位与运营环境；能力、约束、术语、证据、平台与无障碍；已确认的声音、资产与品牌承诺。

不属于这里（访谈阶段严禁收集）：视觉世界、调色板、排版、组件或页面概念；访客模式、叙事、CTA/证明序列等表面策略；凭空编造的推荐语、客户、基准、定价、许可或部署声明；以及「每个可选字段都必须决定」的强迫症。

特别注意一条反向禁令：init 期间不要询问美学方向、情绪感受、视觉参考、颜色、字体或风格。如果用户主动给出一个有约束力的视觉约束，可以如实记录，但不得擅自展开。

Step 4：编写 PRODUCT.md——schema 模板、版本注释与完成门

访谈结束、事实确认后进入写入阶段。文档给出的完整模板如下（新文件必须原样保留开头的版本注释）：

# Product

<!-- impeccable:product-schema 1 -->

## Platform

web

## Stack
[Greenfield only: the user's answer to the stack question, e.g. "static HTML/CSS", "Astro", or "delegated: <what you chose and why>". Omit the section when an existing codebase already answers it.]

## Users
[Primary users, their situation, and job. Add other audiences only when confirmed.]

## Product Purpose
[What the product does, why it exists, and what success means.]

## Positioning
[The product mechanism or claim a neighboring product could not truthfully copy.]

## Operating Context
[Workflows, environments, tools, documents, materials, and rituals that are factual parts of using or evaluating the product.]

## Capabilities and Constraints
[Confirmed functionality, technical constraints, terminology, and explicitly undecided product facts.]

## Brand Commitments
[Existing name, voice, assets, personality, identity constraints, and references the user explicitly made binding. Omit when none exist.]

## Evidence on Hand
[Real content, data, demonstrations, testimonials, case studies, press, or assets, with paths where applicable. State absences that future work must not fabricate.]

## Product Principles
[Three to five durable strategic principles derived from confirmed answers; no visual recipes.]

## Accessibility & Inclusion
[Known user needs or required standard. Omit when no product-specific requirement was established.]

模板要点与配套规则：

• Platform 必须是裸值 web / ios / android / adaptive 之一，不能带解释性修饰。
• ## Stack 只服务于 Greenfield：既有代码库本身已回答技术栈时，直接省略该小节。buildPath 这类工作流设置永远不进 ## Stack 或任何 PRODUCT.md 小节——文档特别警告，一旦在 PRODUCT.md 里留下第二份副本，它会比设置本身活得久，并在无人能追溯到出处的情况下持续引导每一轮工作。
• 保留有用的 legacy 标题，不为了「整洁」删除仍有价值的旧字段。
• 新文件写到 PROJECT_ROOT/PRODUCT.md，否则更新解析出的那个文件。写入必须先于任何视觉世界或表面概念工作。
• 平台若记为 ios / android / adaptive，则必须装载 ios.md、android.md（或两者）之后再进行任何设计工作。文档点出一个只有 init 能补上的关键场景：在原本没有 PRODUCT.md 的项目上，context.mjs 启动时无从得知平台，因此从未装载原生指导；init 是唯一能得知答案、从而补装载的地方。

schema 版本注释：让短记录与旧记录可区分

<!-- impeccable:product-schema 1 --> 这一行必须逐字复制，哪怕更新的是旧文件也要带上。它的作用机制值得展开：它记录「这份产品记录遵循哪个版本的产品 schema」，使未来版本能够区分「一份故意写得短的新记录」和「一份写在某小节存在之前的旧记录」——从而永不向已经坐过访谈的用户再提一次访谈。schema 编号只在本参考文档的模板变更时递增；某个版本退役掉的小节会在启动时报告为 deprecated，征得用户同意后再删除，而不是默默携带或悄悄丢弃。

完成门（Completion Gate）

在把控制权交给 new-work 或恢复 shape/build 之前，必须校验：解析路径上的 PRODUCT.md 存在且包含已确认的产品记录。文件缺失即代表 init 未完成——访谈笔记、规划包或后续的设计文字都不能顶替这个文件。这一步是硬校验，不是软建议。

仓库内的真实样例

仓库根目录的 PRODUCT.md 就是一份按 schema 1 书写的现成范本：它以裸值 web 声明平台，Users 描述「使用 AI 编码工具的 Designer/PM/工程师」这一主受众，Product Purpose 定义成功标准，Positioning 描述「source-first、经各 harness 分发」的差异化机制，Brand Commitments 用直接、具体、根植于 craft 的声音约束落到措辞禁忌，Evidence on Hand 明确写到「没有客户推荐语与量化结果研究，未来 surface 不得虚构它们」——Product Principles 与 Accessibility & Inclusion（WCAG 2.1 AA）也一一对应模板。它同时示范了「没有确认就不写」：凡模板允许省略的小节（如无品牌场景下的某些字段），范本并不硬填。需要留意的是，仓库 demos/landing-demo/ 下的 PRODUCT.md 是 Lumina 演示站的独立品牌记录变体（无 schema 注释、字段结构不同），属于演示资产，不应与 init 产物的 schema 1 格式混为一谈。

Step 5：记录工作流默认——buildPath 的 comp/code 语义与一次提问纪律

PRODUCT.md 落盘之后，init 还有一项独立于产品真相的配置职责：当图像生成可用且尚未记录 buildPath 时，只问一次「新 surface 应该如何开始构建」。

可用性的判定

「图像生成可用」指 harness 自带的图像工具，或 context.mjs 以 IMAGE_GEN_AVAILABLE 键上报的 API 回退通道。文档给了一个容易踩的坑：第一种情况在启动输出中不留任何痕迹——context.mjs 只看到键，所以「某 harness 能生成图片但启动很安静」绝不构成「没有东西可问」的证据。

comp-first 与 code-first 的权衡

这个问题必须独立成问，绝不搭在其他问题的顺风车里（Stack 轮问「用什么构建」，这轮问「构建如何开始」，对第一个问题的回答不代表对第二个问题的同意）。向用户呈现时要用人能听懂的话说明取舍：

• comp-first（先图后码）：先用图像设定标杆再写代码。构图更大胆，但更慢，且最终构建必须与图像匹配；
• code-first（直接写码）：直接构建，雄心写进 direction contract，在 finish 阶段审计。更精简、更快。

写入位置与「一次提问」纪律

• 回答写入 .impeccable/config.json，键为 "buildPath": "comp" 或 "buildPath": "code"，并与文件中既有键合并写入；只写用户真正选择的值。
• 推荐不是回答，沉默不是授权：你做的推荐不构成用户给出的答案；从沉默里取值等于给项目安了一个无人认领的默认值，它会在之后每一轮都生效——这与「只问一次」的初衷恰好相反。
• 当问题无人回答时：什么都不写，只用一行说明本次会话走哪条路、且该选择未存储。这条默认路径是 comp-first（new-work 在图像生成存在且无记录时采用的默认），要指名道姓地说出来，而不是默默选一个更安静的路径——文档的措辞很严厉：在这里发明一个静默默认，与写入一个未经回答的值是同一种失败。
• 未设置是一种正常工作状态：decision page 上的 toggle 只约束当前会话，new-work 的一次性 offer 会在用户首次拨动时把答案记录下来。配置是 buildPath 的唯一归宿。
• 已记录的值是已确认的回答：重跑 init 时静默沿用，不再追问。buildPath 可同时存在于 gitignored 的 .impeccable/config.local.json——按 README.md 与 doctor.md 的描述，local 文件对单个开发者/单台机器胜出（例如你的 harness 没有图像生成时，用 local 覆盖团队提交值）；在 monorepo 中则提交一次在仓库根，其他 workspace 自行覆盖。
• 它是默认值而非锁：decision page 渲染的 toggle 一旦翻转只绑定本次会话，永不回写。
• 完全没有图像生成时，不存在可记录的选择，code-first 是唯一路径。

doctor 命令从配置健康角度对这条纪律做了旁证：doctor.md 提到 config-invalid-build-path 与 config-build-path-unset 两个 finding 都只针对 buildPath 这一个键，并警告「未被读取的值不会回退到相反路径」——例如项目本意是 code 却一直以 comp 方式构建，doctor 会报告确切值。此外，doctor 还点名了 init 场景 的补位场景：子 workspace 携带原生构建文件却继承 root 解析为 web 的记录时（workspace-platform-native-evidence），修复方式是在该 workspace 写一份子 PRODUCT.md，因为「一条继承来的记录无法同时承载两个平台」。测试侧同样覆盖了 buildPath 的会话翻转行为：在 tests/new-work-e2e.test.mjs 中可看到构造 buildPath 轮、以 { "value": "code", "toggle": true } 写入载荷、再断言 answer.buildPath === 'comp' 与 buildPathFlipped === true 的端到端用例，印证了「翻转值绑定单会话、不回写」的实现约定。

然后配置 live 模式

若项目是可运行的 Web 项目且 live 模式有用，则按 live.md 完成首次设置；原生项目或不可运行项目直接跳过；既有 live 配置保持原样、不动。任何 CSP 源编辑仍须取得文档所要求的明确同意。仓库自身的 .impeccable/live/config.json 展示了这种运行时注入配置的形态（files、insertBefore、commentSyntax、cspChecked），可作为理解「init 可能为可运行 Web 项目附加的 live 配置」的实物样例。

Step 6：收尾或恢复——总结、推荐下一步、优雅交接

写入完成后，init 收尾的动作是：总结已捕获的事实与有意未决定的事实（不要因为 DESIGN.md 缺失就主动提议创建它），然后根据项目真实状态推荐下一步。文档给出的决策矩阵：

当前项目状态	推荐的下一步
空项目或极早期项目	自然地问用户想构建哪个 surface；当用户想要「已确认的简报但不落地实现」时用 /impeccable shape <surface>。只有当请求的工作确实需要视觉世界时，new-work 才建立它
已有连贯界面但没有 DESIGN.md	若用户想独立于新构建、把在位系统记录下来：/impeccable document
已有 surface 需要改进	点名最相关的 scoped 命令
Web 项目已就绪、可做视觉迭代	配置完成后走 /impeccable live

如果 init 是由另一个请求触发（而非用户显式调用）的：完成 PRODUCT.md 后直接恢复原任务，不要重跑 context.mjs——文档的理由很精确：原生参考文档（native reference）是那次运行唯一无法提供的东西，而 init 已负责装载它；后续视觉决策归 new-work 所有。

贯穿全程的质量防线：从文档归纳的常见误区

把六步的纪律横向压缩，可以得到一份可直接对照的自检清单：

1. 职责越界：init 期间提出视觉方向、调色板或风格问题 → 属于 new-work，严禁。
2. 写入未确认事实：把推断当确认、把推荐当回答、把沉默当授权 → 推断必须标注、披露必须在第一条回复、未回答的值不得落盘。
3. 重复提问：对已记录的事实重开访谈、对已存在的 buildPath 再问一次 → 存量即确认，先加载再提问，轮次封顶三轮。
4. 制造第二权威：绕过 context.mjs 解析路径另建 PRODUCT.md、在 PRODUCT.md 里复制 buildPath → 只更新解析路径，工作流设置只进 config。
5. 静默覆盖与顺水推舟：悄悄改写既有 PRODUCT.md、因「DESIGN.md 缺失」就顺手提议补一份 → 两者都是禁令。
6. 伪造证据：在 Evidence on Hand 中虚构客户、推荐语、基准或部署声明 → 模板要求明示「缺失即缺失」。
7. 未设置即缺陷的误解：buildPath 未记录不代表 init 失败，未设置是 working state；只有 PRODUCT.md 缺失才是 init 未完成的判据（completion gate）。

这套纪律最终服务的是一条简单到容易被忽略的因果链：Impeccable 的每一个后续命令（new-work、document、shape、critique、audit、live…）都要先读 PRODUCT.md 再动手。init 把这条链的源头钉死——一份只含已确认事实与显式开放决策的产品记录，就是整个 AI 设计工作流里最值得花一次会话做好的地基。想继续深入，可从 new-work.md（视觉世界创建）、document.md（在位系统记录）、live.md（浏览器内视觉变体迭代）以及 SKILL.md（完整命令路由）四个入口接着读；同一份参考文档也在 skill/reference/（canonical 源）与 plugin/skills/ 及各 harness 目录下以同步副本形式分发。