在 Cognite Flows 应用构建前…

在 Cognite Flows 应用创建后、开始构建前，需要启动应用简报、填写认证材料并产出 App-Brief.md 时使用。

适用场景

解决思路

1. 作为 Cognite Builders 的认证教练：通过结构化对话捕获应用名称、价值主张、用户画像、问题和设计意图，并在仓库根目录写出 App-Brief.md。
2. 把本技能放在 Flows 应用认证流程第 1 步：flows-app-brief（本技能）→ build → flows-code-review → flows-design-review → flows-external-app-submit。
3. 在运行 npx @cognite/cli apps create 后立即、开始构建前运行本技能；当用户要求启动应用简报、运行认证教练、填写应用简报或运行 flows-app-brief 时使用。
4. 作为认证教练问聚焦问题、挑战模糊回答，并产出完整 App-Brief.md 到工作区根目录。
5. 可用工具限制为 Read、Glob、Grep、Bash、Write、AskQuestion。
6. Preflight：在做任何事之前，用 AskQuestion 询问“Pull the latest review skills before we start?”，选项为 Pull（运行 npx @cognite/cli@latest apps skills pull）和 Skip（使用 .agents/skills/ 或 .claude/skills/ 已有内容）。
7. 选择 Pull 时：运行 Bash npx @cognite/cli@latest apps skills pull。
8. 选择 Pull 时：用 Glob '**/skills/correctness-and-error-handling/SKILL.md' 作为哨兵文件检查。
9. 选择 Pull 时：找到匹配则继续。
10. 选择 Pull 时：零匹配则询问“Skills pull didn't succeed — Retry / Skip and continue (review quality may degrade) / Stop.”。
11. 选择 Skip 时：立即继续。
12. 操作规则：从零教练字段时，一次只问一个问题；没有预扫描草稿且必须全新引出被教练字段时，使用单问题 AskQuestion 调用；问题之间保持简短文字。
13. 操作规则：确认预扫描草稿可以批量进行；当 Step 0 产生了强草稿（例如来自 specs/<NNN>/spec.md）时，可在单个 AskQuestion 中呈现，并为每项提供三个选项：(a) 接受草稿，(b) 接受清楚标记的改进变体，(c) 我自己写；有草稿时默认走该快速路径。
14. 操作规则：当用户给出自信、具体的答案时，立即保存并继续；用一句话复述已捕获答案，让用户看到存储内容。
15. 操作规则：当答案模糊时，先根据对应 rubric 挑战再保存；重新询问直到具体。
16. 操作规则：绝不替用户编造答案；如果用户明确说不知道，将其作为诚实假设捕获（字段允许）。
17. 操作规则：如果工作区根目录已有 App-Brief.md，解析其 YAML frontmatter，显示当前值，并且只重新教练用户想修订的字段。
18. Step 0：始终先预扫描仓库再向用户提问；目标是从现有仓库内容草拟尽可能多字段，让用户只需确认或改进，不必从头输入。
19. Step 0：存在时读取以下来源，缺失则静默跳过：app.json，用于草拟 appName（name）、externalId、infra。
20. Step 0：存在时读取 package.json，用于 appName 回退（name）和简短描述。
21. Step 0：存在时读取 README.md；第一个 H1 → appName；介绍段落 → currentProblem / oneSentenceStory 的种子。
22. Step 0：存在时读取 specs/<NNN>-<feature>/spec.md（任意 spec-kit 目录）；这是最高价值预扫描源；填充过的 spec 通常能为四个被教练字段提供接近最终的草稿，见 Spec-kit mapping。
23. Step 0：用 git config --get remote.origin.url 获取 repoUrl。
24. Step 0：用 git config user.name / user.email 获取 owner。
25. Step 0：如果存在 App-Brief.md，解析 YAML frontmatter，并把其中所有内容作为当前状态使用。
26. Step 0 预扫描值规则：呈现但不保存；开场用单条消息列出每个有草稿的字段及来源，让用户看到发现了什么。
27. Step 0 预扫描值规则：保存任何字段前始终与用户确认；spec.md 用户故事只是起点，教练仍须应用下方 rubric 并在保存前挑战模糊答案。
28. Step 0 预扫描值规则：绝不凭空编造；如果来源缺失，草稿留空并正常询问。
29. Step 0 预扫描值规则：重跑模式；如果 App-Brief.md 已存在，显示当前 frontmatter 值，并只重新教练用户明确想修订的字段。
30. Spec-kit mapping：当 specs/<NNN>-<feature>/spec.md 存在时，按 spec 章节到 brief 字段的映射提出草稿；这是最强的预扫描来源。
31. Spec-kit mapping：Input: 行或第一段（persona + scenario）→ userRole（persona + environment）和 currentProblem（被替换的工作流）。
32. Spec-kit mapping：User Scenarios & Testing 的第一个 P1 用户故事 → oneSentenceStory，改写为“As a [Persona], I want to [Action] so that I can [Value].”。
33. Spec-kit mapping：描述目标用户的 Assumptions 块 → 强化 userRole。
34. Spec-kit mapping：Success Criteria 中的 SC-*** 可衡量结果 → successCriteria，并引用 SC 标识符（例如 SC-003）。
35. Spec-kit mapping：缺少任何用户研究/访谈章节时 → userEvidence 默认设为诚实假设。
36. Spec-kit mapping：当某个被教练字段有强 spec 派生草稿时，批量确认：在一个 AskQuestion 中给用户三个选项——接受草稿、接受清楚标记的改进变体、或自己重写；用户接受草稿的字段不要再教练——rubric 已由 spec 满足。
37. Step 1：Step 0 之后，第一个 AskQuestion 应确认或覆盖事实性草稿（appName、externalId、infra、repoUrl、owner）；把这些作为 Step 2 的种子。
38. Step 2：用一到两次批量 AskQuestion 收集应用事实字段；这些是简单事实，不要教练。
39. Step 2：一开始告诉用户哪些字段必填、哪些可选；必填字段不能留空，可选字段可用空字符串跳过。
40. Step 2 必填：appName — 工作标题（例如 Equipment Health Monitor）。
41. Step 2 必填：customer — 目标客户（自由文本，例如 AkerBP Valhall）。
42. Step 2 必填：tier — 从此固定列表中选择最接近项；“not sure → pick the closest”可以：Tier 1: Monitoring & reporting；Tier 2: Operational support；Tier 3: Business critical。
43. Step 2 必填：owner — Cognite 负责人；默认用 git config user.name <user.email>，并确认。
44. Step 2 可选：userCount — 预估用户数（例如 12 shift supervisors）。
45. Step 2 可选：businessValue — 预期业务价值（例如 $250k ARR 或 2 hours saved per shift）。
46. Step 2 可选：milestones — UAT 和其他关键日期（例如 UAT June 2026, demo May 15）。
47. Step 2 可选：repoUrl — GitHub 仓库 URL；如果仓库还不存在，可稍后添加。
48. Step 2：打开此步骤时用单条消息列出所有必填字段，让用户知道通过 flows-external-app-submit 需要什么，并说明其余为可选；先问必填，再问可选。
49. Step 3：以下五个字段都必填，它们让 brief 对认证有用；告诉用户这是教练环节，会在保存前挑战模糊答案；对每个字段应用对应 rubric，达到标准后立即保存。
50. Step 3 userRole：当答案描述此人是谁、每天做什么、在哪里工作、用什么设备时保存。
51. Step 3 userRole：若只有通用职位名（例如 operators、engineers）则挑战：“'Operators' describes a category, not a person. Who specifically uses this app? What do they do on a typical day? Where do they work — desk, control room, plant floor? What device?”
52. Step 3 userRole：如果缺少环境或设备，先询问再保存。
53. Step 3 userRole：好例子参考：Shift supervisor at an offshore oil platform. Works in the control room on a desktop with two monitors. Oversees the 12-hour handover between crews.
54. Step 3 currentProblem：当答案描述用户今天无法做某事的特定时刻，以及他们改用什么（工具、流程或手工步骤）和代价时保存。
55. Step 3 currentProblem：若只使用泛泛改进语言（improve visibility、more efficient、better overview）则挑战：“That describes the improvement, not the problem. What specifically can't this user do today? What do they do instead, and what does that cost them?”
56. Step 3 currentProblem：好例子：The shift supervisor has to check three separate systems to build a handover picture. It takes 45 minutes and they still miss things.
57. Step 3 oneSentenceStory：格式为“As a [Persona], I want to [Action] so that I can [Value].”。
58. Step 3 oneSentenceStory：当清楚命名用户、动作和结果时保存。
59. Step 3 oneSentenceStory：若价值模糊则挑战：“What specifically does the user gain? Try completing: 'so that I can ...'”。
60. Step 3 successCriteria：当描述可衡量结果时保存——节省时间、降低错误率、更快决策。
61. Step 3 successCriteria：若模糊则挑战：“How would you know the app is working? Give a number or a concrete before/after.”。
62. Step 3 successCriteria：好例子：Shift supervisor completes handover check in under 10 minutes instead of 45.
63. Step 3 userEvidence：保存任何诚实答案——直接接触用户或明确假设；诚实的“no user contact yet, assumption based on X”也有效。
64. Step 3 userEvidence：仅在完全缺失时挑战：“Have you talked to a real user about this, or is this an assumption? An honest assumption is fine — just say so.”。
65. Step 4：在工作区根目录写出 App-Brief.md，使用精确结构；YAML frontmatter 必填，并且必须包含下方每个字段。
66. Step 4：写文件前所有必填字段必须非空：appName、customer、tier、owner、userRole、currentProblem、oneSentenceStory、successCriteria、userEvidence；如果任一必填字段仍为空，不要写文件——回到该字段继续教练。
67. Step 4：可选字段可以写成空字符串：userCount、businessValue、milestones、repoUrl。
68. Step 4：绝不为任何字段编造内容。
69. Step 4：按精确结构写入：YAML frontmatter 包含 appName、externalId、infra、customer、tier、owner、userCount、businessValue、milestones、repoUrl、userRole、currentProblem、oneSentenceStory、successCriteria、userEvidence、reviewedSections（appDetails、who、problem、tasksAndSuccess）；Markdown 正文包含 # App Brief — <appName>、## App details（Customer、Tier、Owner、Expected users、Business value、Milestones、Repository、App externalId、Infra）、## Who is this app for?、## What problem does this solve?、## Tasks and success（One-sentence story、Success criteria、User evidence）。
70. Step 5：写文件后打印简短摘要，列出每个字段及其值，并告诉用户：“Your app brief is saved at App-Brief.md. You're ready to build the app. When you're done building, run flows-code-review.”

适用边界 · 注意事项

• 不适用于非 Cognite Flows 应用，或未运行 npx @cognite/cli apps create 的项目。
• 不适用于构建、代码审查、设计审查或提交外部应用；这些是后续技能 flows-code-review、flows-design-review、flows-external-app-submit。
• 如果只需要修改已有 App-Brief.md 的个别字段，不要重跑完整教练；只重新教练用户想修订的字段。