flows-app-brief

Original：🇺🇸 English
Translated

Certification coach for Flows apps. Captures the app name, value case, persona, problem, and design intent through a structured conversation and writes App-Brief.md at the repo root. This is the FIRST step of the Flows app certification flow — run it immediately after `npx @cognite/cli apps create`, before building. Use when the user asks to start an app brief, run the certification coach, fill out the app brief, or run flows-app-brief.

217installs
Sourcecognitedata/builder-skills
Added on

NPX Install

npx skill4agent add cognitedata/builder-skills flows-app-brief

Tags

Translated version includes tags in frontmatter
flows-app-certificationapp-brief-generationcognite-clicertification-coachrepo-documentation

SKILL.md Content

View Translation Comparison →

Flows App Brief (Certification Coach)

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.

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:
  1. Run 
    Bash npx @cognite/cli@latest apps skills pull
    .
  2. Glob '**/skills/correctness-and-error-handling/SKILL.md'
    as a sentinel.
  3. Match found → continue.
  4. Zero matches → ask: "Skills pull didn't succeed — Retry / Skip and continue (review quality may degrade) / Stop."
On Skip: continue immediately.

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.

Step 0 — Pre-scan the repo before prompting

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):
SourceUse 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:
  1. 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.
  2. 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.
  3. Never invent. If a source is missing, leave the draft blank and ask normally.
  4. 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.

Spec-kit mapping

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 sectionBrief 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.

Step 1 — Confirm pre-scanned defaults

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.

Step 2 — App details (factual, not coached)

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.

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

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?

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."

currentProblem
— What problem does this solve?

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."

oneSentenceStory
— One-sentence value statement

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?

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."

userEvidence
— Have you talked to users?

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."

Step 4 — Write 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 — <appName>

## App details

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

## Who is this app for?

<userRole>

## What problem does this solve?

<currentProblem>

## Tasks and success

**One-sentence story.** <oneSentenceStory>

**Success criteria.** <successCriteria>

**User evidence.** <userEvidence>

Step 5 — Confirm completion

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
."