flows-app-brief

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flows App Brief (Certification Coach)

Flows应用简报（认证指导工具）

This is step 1 of the Flows app certification flow:

flows-app-brief (this skill)  →  build  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit

Your job is to act as a certification coach for Cognite Builders: ask focused questions, challenge vague answers, and produce a complete

App-Brief.md

at the workspace root.

这是Flows应用认证流程的第1步：

flows-app-brief (本工具)  →  构建  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit

你的任务是担任Cognite开发者的认证指导工具：提出针对性问题，挑战模糊的回答，并在工作区根目录生成完整的

App-Brief.md

文件。

Preflight — Refresh review skills

预检——更新评审工具

Before doing anything else, ask (via

AskQuestion

"Pull the latest review skills before we start?"
Pull —
npx @cognite/cli@latest apps skills pull
Skip — use what's already in
.agents/skills/
/
.claude/skills/

On Pull:

Run

Bash npx @cognite/cli@latest apps skills pull

Glob '**/skills/correctness-and-error-handling/SKILL.md'

as a sentinel.

Match found → continue.
Zero matches → ask: "Skills pull didn't succeed — Retry / Skip and continue (review quality may degrade) / Stop."

On Skip: continue immediately.

在开始任何操作前，通过

AskQuestion

询问：

"我们开始前是否拉取最新的评审工具？"
拉取 —
npx @cognite/cli@latest apps skills pull
跳过 — 使用
.agents/skills/
/
.claude/skills/
中已有的工具

若选择拉取：

执行

Bash npx @cognite/cli@latest apps skills pull

。

以

Glob '**/skills/correctness-and-error-handling/SKILL.md'

作为验证标识。

找到匹配项 → 继续。
未找到匹配项 → 询问："工具拉取失败——重试 / 跳过并继续（评审质量可能下降） / 停止。"

若选择跳过：直接继续。

Operating rules

操作规则

Coaching from scratch is one question at a time. When you have no pre-scanned draft for a coached field and must elicit the answer fresh, use a single-question
```
AskQuestion
```
call. Keep your prose short between questions.
Confirming pre-scanned drafts can be batched. When Step 0 produced strong drafts (e.g. from
```
specs/<NNN>/spec.md
```
), it is fine and encouraged to present them in a single
```
AskQuestion
```
call with three options each: (a) accept the draft, (b) accept a clearly-labeled refined variant, (c) "I'll write my own". This is the fast path and should be the default when drafts exist.
When the user gives a confident, specific answer, save it immediately and move on. Restate the captured answer in one sentence so the user can see what you stored.
When an answer is vague, challenge it before saving using the rubric below. Re-ask until specific.
Never invent answers on the user's behalf. If the user explicitly says they do not know, capture that as an honest assumption (the field allows this).
If
```
App-Brief.md
```
already exists at the workspace root, parse its YAML frontmatter, show the current values, and only re-coach the fields the user wants to revise.

从零开始指导时一次只提一个问题。当某个需要指导的字段没有预扫描草稿，需要从头获取答案时，使用单次提问的
```
AskQuestion
```
调用。问题之间的表述要简洁。
预扫描草稿的确认可批量进行。当第0步生成了完善的草稿（例如来自
```
specs/<NNN>/spec.md
```
），可以在一次
```
AskQuestion
```
调用中展示这些草稿，并提供三个选项：(a) 接受草稿，(b) 接受标注明确的优化版本，(c) "我将自行编写"。这是快速路径，当草稿存在时应作为默认方式。
当用户给出明确、具体的答案时，立即保存并继续。用一句话重述已记录的答案，让用户可以确认存储的内容。
当答案模糊时，在保存前根据下方规则提出质疑。重新提问直到得到具体答案。
切勿替用户编造答案。如果用户明确表示不知道，如实记录为假设（该字段允许这样做）。
如果工作区根目录已存在
```
App-Brief.md
```
，解析其YAML前置内容，展示当前值，仅对用户想要修改的字段进行指导。

Step 0 — Pre-scan the repo before prompting

第0步——提问前预扫描仓库

Always pre-scan before asking the user anything. The goal is to draft as many fields as possible from existing repo content so the user only has to confirm or refine, not type from scratch.

Read these files when present (silently skip any that are missing):

Source	Use it to draft
`app.json`	`appName` ( `name` ), `externalId` , `infra`
`package.json`	`appName` fallback ( `name` ), short description
`README.md`	First H1 → `appName` ; intro paragraph → seed for `currentProblem` / `oneSentenceStory`
`specs/<NNN>-<feature>/spec.md` (any spec-kit directory)	Highest-value pre-scan source. A populated spec typically gives you near-final drafts for four coached fields — see "Spec-kit mapping" below.
`git config --get remote.origin.url`	`repoUrl`
`git config user.name` / `user.email`	`owner`
Existing `App-Brief.md`	Parse YAML frontmatter and use all of it as the current state

Rules for what to do with pre-scanned values:

Present, do not save. Open with a single message that lists every field you have a draft for, sourced from where, so the user can see what you found.
Always confirm with the user before saving any field. A
```
spec.md
```
user story is a starting point; the coach must still apply the rubric below and challenge vague answers before saving.
Never invent. If a source is missing, leave the draft blank and ask normally.
Re-run mode. If
```
App-Brief.md
```
already exists, show the current frontmatter values and only re-coach fields the user explicitly wants to revise.

提问前务必先预扫描仓库。目标是从现有仓库内容中尽可能多的生成字段草稿，让用户只需确认或优化，无需从头输入。

若存在以下文件则读取（缺失的文件自动跳过）：

来源	用于生成的字段草稿
`app.json`	`appName` （ `name` 字段）、 `externalId` 、 `infra`
`package.json`	`appName` 备选值（ `name` 字段）、简短描述
`README.md`	第一个H1标题 → `appName` ；介绍段落 → `currentProblem` / `oneSentenceStory` 的初始内容
`specs/<NNN>-<feature>/spec.md` （任何spec-kit目录）	价值最高的预扫描来源。已填充的spec通常能为四个需要指导的字段提供接近最终版本的草稿——详见下方"Spec-kit映射"。
`git config --get remote.origin.url`	`repoUrl`
`git config user.name` / `user.email`	`owner`
已存在的 `App-Brief.md`	解析其YAML前置内容，并将所有内容作为当前状态

预扫描值的处理规则：

展示而非直接保存。以一条消息开头，列出所有已生成草稿的字段及其来源，让用户了解你找到的内容。
保存任何字段前务必与用户确认。
```
spec.md
```
中的用户故事只是起点；指导工具仍需应用下方规则，在保存前挑战模糊的答案。
切勿编造。若来源缺失，留空草稿并正常提问。
重新运行模式。若
```
App-Brief.md
```
已存在，展示当前前置内容值，仅对用户明确要求修改的字段重新指导。

Spec-kit mapping

Spec-kit映射

When

specs/<NNN>-<feature>/spec.md

exists, propose drafts by mapping spec sections to brief fields. This is by far the most powerful pre-scan source.

Spec section	Brief field draft
`Input:` line or first paragraph (persona + scenario)	`userRole` (persona + environment) and `currentProblem` (workflow being replaced)
`User Scenarios & Testing` → first P1 user story	`oneSentenceStory` — rewrite into "As a [Persona], I want to [Action] so that I can [Value]."
`Assumptions` block describing the target user	strengthens `userRole`
`Success Criteria` → `SC-***` measurable outcomes	`successCriteria` — cite the SC identifiers (e.g. "SC-003")
Absence of any user research / interview section	`userEvidence` defaults to an honest assumption

When you have a strong spec-derived draft for a coached field, batch the confirmation: in one

AskQuestion

give the user three options — accept the draft, accept a clearly-labeled refined variant, or rewrite. Do NOT re-coach fields where the user accepted the draft — the rubric was already met by the spec.

当

specs/<NNN>-<feature>/spec.md

存在时，通过将spec章节映射到简报字段来生成草稿。这是目前最强大的预扫描来源。

Spec章节	简报字段草稿
`Input:` 行或第一段（用户角色+场景）	`userRole` （用户角色+环境）和 `currentProblem` （待替换的工作流程）
`User Scenarios & Testing` → 第一个P1用户故事	`oneSentenceStory` — 重写为"作为[用户角色]，我想要[操作]，以便我能[价值]。"
描述目标用户的 `Assumptions` 块	完善 `userRole`
`Success Criteria` → `SC-***` 可衡量结果	`successCriteria` — 引用SC标识符（例如"SC-003"）
缺少任何用户调研/访谈章节	`userEvidence` 默认如实记录为假设

当某个需要指导的字段有基于spec生成的完善草稿时，批量确认：在一次

AskQuestion

中为用户提供三个选项——接受草稿、接受标注明确的优化版本、或重写。用户接受草稿的字段无需再指导——spec已符合规则要求。

Step 1 — Confirm pre-scanned defaults

第1步——确认预扫描默认值

After Step 0, your first

AskQuestion

should confirm or override the factual drafts (

appName

externalId

infra

repoUrl

owner

). Use these as the seed for Step 2.

完成第0步后，你的第一次

AskQuestion

应确认或覆盖事实类草稿（

appName

、

externalId

、

infra

、

repoUrl

、

owner

）。将这些作为第2步的初始值。

Step 2 — App details (factual, not coached)

第2步——应用详情（事实类，无需指导）

Collect these in one or two batched

AskQuestion

calls. They are simple facts — do not coach. Tell the user up front which fields are required vs optional. Required fields cannot be left blank; optional fields can be skipped with an empty string.

Required

```
appName
```
(required) — working title (e.g. "Equipment Health Monitor")
```
customer
```
(required) — target customer (free text, e.g. "AkerBP Valhall")
```
tier
```
(required) — pick the closest match from this fixed list; "not sure → pick the closest" is fine:
- ```
Tier 1: Monitoring & reporting
```
- ```
Tier 2: Operational support
```
- ```
Tier 3: Business critical
```
```
owner
```
(required) — Cognite owner; default to
```
git config user.name <user.email>
```
and confirm

Optional (skip with empty string if unknown)

```
userCount
```
(optional) — estimated number of users (e.g. "12 shift supervisors")
```
businessValue
```
(optional) — expected business value (e.g. "$250k ARR" or "2 hours saved per shift")
```
milestones
```
(optional) — UAT and other key dates (e.g. "UAT June 2026, demo May 15")
```
repoUrl
```
(optional) — GitHub repo URL; can be added later if the repo does not exist yet

Open this step with a single message that lists all required fields up front (so the user knows what is needed to pass

flows-external-app-submit

) and tells them the rest are optional. Then ask for the required ones first, optional ones after.

通过一次或两次批量

AskQuestion

调用收集这些信息。它们是简单的事实——无需指导。提前告知用户哪些字段是必填项，哪些是可选项。必填字段不能为空；可选项若未知可留空字符串。

必填项

```
appName
```
(必填) — 工作标题（例如"设备健康监控器"）
```
customer
```
(必填) — 目标客户（自由文本，例如"AkerBP Valhall"）
```
tier
```
(必填) — 从以下固定列表中选择最匹配的选项；"不确定→选最接近的"即可：
- ```
Tier 1: Monitoring & reporting
```
- ```
Tier 2: Operational support
```
- ```
Tier 3: Business critical
```
```
owner
```
(必填) — Cognite负责人；默认使用
```
git config user.name <user.email>
```
并确认

可选项（若未知可留空字符串

""

）

```
userCount
```
(可选) — 预估用户数量（例如"12名轮班主管"）
```
businessValue
```
(可选) — 预期业务价值（例如"25万美元年度经常性收入"或"每班节省2小时"）
```
milestones
```
(可选) — 用户验收测试及其他关键日期（例如"用户验收测试2026年6月，演示2026年5月15日"）
```
repoUrl
```
(可选) — GitHub仓库URL；若仓库尚未创建可后续添加

本步骤以一条消息开头，列出所有必填项（让用户了解完成

flows-external-app-submit

所需的内容），并说明其余为可选项。先询问必填项，再询问可选项。

Step 3 — Coach the human-centered fields (one at a time)

第3步——指导以人为中心的字段（一次一个）

All five fields in this step are required — they are what makes the brief useful for certification. Tell the user this is the coached portion: you will challenge vague answers before saving. Apply the rubric for each field below and save each as soon as it meets the bar.

本步骤的所有五个字段均为必填项——它们是简报对认证有用的核心内容。告知用户这是需要指导的部分：在保存前会挑战模糊的回答。对每个字段应用下方规则，一旦符合要求立即保存。

userRole

— Who is this app for?

userRole

— 该应用面向谁？

Save when the answer describes: who the person is, what they do day to day, where they work, and what device they use.

Challenge if it's a generic job title only (e.g. "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?"

If environment or device are missing, ask for them before saving.

Good example to keep in mind: "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."

当答案描述清楚以下内容时保存：用户是谁、日常工作内容、工作地点、使用的设备。

若仅给出通用职位名称（例如"操作员"、"工程师"）则提出质疑：

"'操作员'描述的是一个类别，而非具体的人。具体是谁会使用这个应用？他们日常的工作内容是什么？工作地点在哪里——办公室、控制室、工厂车间？使用什么设备？"

若缺少环境或设备信息，在保存前询问相关内容。

参考优秀示例："海上石油平台的轮班主管。在控制室使用双显示器的桌面电脑工作。负责12小时的班组交接。"

currentProblem

— What problem does this solve?

currentProblem

— 该应用解决什么问题？

Save when the answer describes: a specific moment when the user cannot do something today, and what they do instead (tool, process, or manual step) and what that costs them.

Challenge if it uses only general improvement language ("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?"

Good example: "The shift supervisor has to check three separate systems to build a handover picture. It takes 45 minutes and they still miss things."

当答案描述清楚以下内容时保存：当前用户无法完成某件事的具体场景，以及他们当前的替代方案（工具、流程或手动步骤）及其成本。

若仅使用笼统的改进表述（"提升可见性"、"更高效"、"更好的概览"）则提出质疑：

"这描述的是改进效果，而非问题本身。当前用户具体无法完成什么任务？他们的替代方案是什么，成本有多少？"

参考优秀示例："轮班主管需要查看三个独立系统才能完成交接准备。这需要45分钟，且仍会遗漏信息。"

oneSentenceStory

— One-sentence value statement

oneSentenceStory

— 一句话价值陈述

Format: "As a [Persona], I want to [Action] so that I can [Value]."

Save when it clearly names the user, the action, and the outcome.

Challenge if the value is vague:

"What specifically does the user gain? Try completing: 'so that I can ...'"

格式："作为[用户角色]，我想要[操作]，以便我能[价值]。"

当答案明确指出用户、操作和结果时保存。

若价值表述模糊则提出质疑：

"用户具体能获得什么？尝试补充完整：'以便我能...'"

successCriteria

— How will we know it's working?

successCriteria

— 如何判断应用有效？

Save when it describes a measurable outcome — time saved, error rate reduced, decisions made faster.

Challenge if vague:

"How would you know the app is working? Give a number or a concrete before/after."

Good example: "Shift supervisor completes handover check in under 10 minutes instead of 45."

当答案描述可衡量的结果时保存——例如节省的时间、降低的错误率、更快的决策速度。

若表述模糊则提出质疑：

"你如何判断应用有效？给出具体数字或明确的前后对比。"

参考优秀示例："轮班主管完成交接检查的时间从45分钟缩短至10分钟以内。"

userEvidence

— Have you talked to users?

userEvidence

— 你是否与用户沟通过？

Save any honest answer — direct user contact OR an explicit assumption. An honest "no user contact yet, assumption based on X" is valid.

Challenge only if completely absent:

"Have you talked to a real user about this, or is this an assumption? An honest assumption is fine — just say so."

任何诚实的答案均可保存——直接用户沟通记录或明确的假设。诚实的"尚未与用户沟通，基于X的假设"是有效的。

仅当完全未回答时提出质疑：

"你是否与真实用户沟通过这个应用，还是这只是一个假设？诚实的假设是可以的——只需说明即可。"

Step 4 — Write App-Brief.md

第4步——生成App-Brief.md

Write

App-Brief.md

at the workspace root with this exact structure. The YAML frontmatter is required and must contain every field below.

Required fields must be non-empty before writing the file:

appName

customer

tier

owner

userRole

currentProblem

oneSentenceStory

successCriteria

userEvidence

. If any required field is still empty, do not write the file — return to coaching that field.

Optional fields may be the empty string

""

userCount

businessValue

milestones

repoUrl

Never invent content for any field.

markdown

---
appName: "<working title>"
externalId: "<from app.json>"
infra: "<from app.json>"
customer: "<customer>"
tier: "<tier>"
owner: "<name <email>>"
userCount: "<estimate>"
businessValue: "<value statement>"
milestones: "<UAT and key dates>"
repoUrl: "<https://github.com/...>"
userRole: "<coached>"
currentProblem: "<coached>"
oneSentenceStory: "<coached>"
successCriteria: "<coached>"
userEvidence: "<coached>"
reviewedSections:
  - appDetails
  - who
  - problem
  - tasksAndSuccess
---

在工作区根目录生成

App-Brief.md

文件，必须严格遵循以下结构。YAML前置内容是必填项，必须包含下方所有字段。

必填字段在生成文件前必须非空：

appName

、

customer

、

tier

、

owner

、

userRole

、

currentProblem

、

oneSentenceStory

、

successCriteria

、

userEvidence

。若任何必填字段仍为空，请勿生成文件——返回指导该字段。

可选项可为空字符串

""

：

userCount

、

businessValue

、

milestones

、

repoUrl

。

切勿为任何字段编造内容。

markdown

---
appName: "<工作标题>"
externalId: "<来自app.json>"
infra: "<来自app.json>"
customer: "<客户>"
tier: "<层级>"
owner: "<姓名 <邮箱>>"
userCount: "<预估数量>"
businessValue: "<价值陈述>"
milestones: "<用户验收测试及关键日期>"
repoUrl: "<https://github.com/...>"
userRole: "<指导后内容>"
currentProblem: "<指导后内容>"
oneSentenceStory: "<指导后内容>"
successCriteria: "<指导后内容>"
userEvidence: "<指导后内容>"
reviewedSections:
  - appDetails
  - who
  - problem
  - tasksAndSuccess
---

App Brief — <appName>

应用简报 — <appName>

App details

应用详情

Customer: <customer>
Tier: <tier>
Owner: <owner>
Expected users: <userCount>
Business value: <businessValue>
Milestones: <milestones>
Repository: <repoUrl>
App externalId: <externalId>
Infra: <infra>

客户: <customer>
层级: <tier>
负责人: <owner>
预期用户: <userCount>
业务价值: <businessValue>
关键节点: <milestones>
仓库: <repoUrl>
应用externalId: <externalId>
基础设施: <infra>

Who is this app for?

该应用面向谁？

What problem does this solve?

该应用解决什么问题？

Tasks and success

任务与成功标准

One-sentence story. <oneSentenceStory>

Success criteria. <successCriteria>

User evidence. <userEvidence>

undefined

一句话价值陈述。<oneSentenceStory>

成功标准。<successCriteria>

用户依据。<userEvidence>

undefined

Step 5 — Confirm completion

第5步——确认完成

After writing the file, print a short summary listing each field and its value, and tell the user: "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
."

生成文件后，打印包含每个字段及其值的简短摘要，并告知用户："你的应用简报已保存至
App-Brief.md
。你已准备好构建应用。构建完成后，请执行
flows-code-review
。"",