Flows App Brief

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

| 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:**
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