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.

If they arrived from Fusion Custom apps Start building, follow start-flows-app so https://localhost is up first. Do not dump an empty App-Brief template as the opening move. Write App-Brief.md after the SME conversation.

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 and show the current values. If it lacks maintainer or supportPath, treat them as missing and collect only those two. If an existing maintainer is a plain string instead of a list, show it and ask the user to convert it to email addresses. Otherwise, only re-coach or re-prompt 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):

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. If maintainer or supportPath are missing from the existing brief, treat them as missing and collect only those two. If an existing maintainer is a plain string instead of a list, show it and ask the user to convert it to emails. Otherwise, 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.

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 (appName, customer, tier, owner, maintainer, supportPath, and the coached human-centered fields) so the user knows what is needed to pass flows-external-app-submit, and tells them the rest are optional. Explain that maintainer and supportPath will be collected in Step 4 (Support readiness). Then ask for the Step 2 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 — Support readiness

These fields capture operational ownership and support decisions. Do not coach these like the Step 3 fields. They are decisions, not rubric answers.

Explain the difference once: Owner is the app's purpose, usage and lifecycle. Maintainers are the people who fix bugs, patches and re-certify changes.

maintainer (required)

Ask for one or more email addresses, comma or newline separated.

• Trim, lowercase, and deduplicate entries.
• Validate basic email format.
• Reject blank, TBD, unknown, N/A, and obvious placeholders (such as example.com, test@, etc.).
• Never pre-fill from git config or the owner field.
• If exactly one email is given, warn once: "One person is a single point of failure. A group alias or a second contact is safer." Accept it if the user confirms. Do not block.
• Do not try to verify that the addresses exist.
• Store as a YAML list of one or more email addresses:

  maintainer:
    - "name@company.com"

  Must contain at least one valid email.

supportPath (required)

Single AskQuestion with exactly these four options:

• Cognite Support
• Partner maintains
• Customer self-maintains
• Not going to production

After supportPath is chosen, print the matching reminder:

• Cognite Support: only valid with a support contract and a Support Handover ticket. Handover starts at project kickoff, not end of build. The PM raises a Zendesk ticket at support.cognite.com with the support contract attached. SPEC, Data Model and this App Brief must be attached. Certification alone does not mean Cognite Support covers the app. Maintainer emails should be the contacts who will own the app until handover completes.
• Partner maintains: the partner organization is the Maintainer. Cognite Support is involved only where a support contract or Business Application Support agreement exists.
• Customer self-maintains: needs a named customer team with active certified builders.
• Not going to production: the brief still needs Maintainer emails. A support path is required if the app later reaches a customer production project.

Re-run mode for support fields

If an existing App-Brief.md lacks maintainer or supportPath, treat them as missing and prompt only for those two. If an existing maintainer is a plain string instead of a list, show it and ask the user to convert it to emails.

Step 5 — 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, maintainer (at least one valid email in a list), supportPath, userRole, currentProblem, oneSentenceStory, successCriteria, userEvidence. If any required field is still empty, do not write the file; return to collecting or coaching that field.

Optional fields may be the empty string "": userCount, businessValue, milestones, repoUrl.

Never invent content for any field.

---
appName: "<working title>"
externalId: "<from app.json>"
infra: "<from app.json>"
customer: "<customer>"
tier: "<tier>"
owner: "<name <email>>"
maintainer:
  - "<email1>"
  - "<email2>"
supportPath: "<Cognite Support | Partner maintains | Customer self-maintains | Not going to production>"
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
  - support
---

# 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>

## Support

- **Maintainer:**
  - <email1>
  - <email2>
- **Support path:** <supportPath>

Step 6 — Confirm completion

After writing the file, print a short summary listing each field and its value (including maintainer and supportPath), 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."