project-brief

Files (6)

• SKILL.md
• PROJECT-BRIEF.md · templates/
• decisions.md · templates/
• interview-log.md · templates/
• open-questions.md · templates/
• research.md · templates/

SKILL.md (first lines)

# Project Brief Engine

Mission: extract the **maximum** from the user's head — what they think, how
they see it, what they know but haven't said — and turn it into a durable
foundation for the whole project. Coach, don't quiz. The ideas come from the
user; you bring structure, pushback, and memory.

File templates for every output live in `templates/` in this skill's directory.

---

## Output: the brief is a folder

```
docs/brief/
├── PROJECT-BRIEF.md      # main document, 2-4 pages, links to everything below
├── interview-log.md      # full Q&A journal — nothing the user said is lost
├── decisions.md          # BD-NNN decision log, grows for the project's life
├── open-questions.md     # consciously deferred questions only
├── research.md           # research-loop findings (analogs, tech comparisons)
└── details/              # created ONLY when a topic outgrows the main doc:
    personas.md, competitors.md, user-journeys.md, ...
```

The main document stays short and readable; the extracted depth is never lost —
it lives in the companion files, linked from the main one.

**Legacy:** if a single-file `docs/PROJECT-BRIEF.md` exists, offer to migrate it
into `docs/brief/` (move content, split decisions/open questions into their
files) before doing anything else.

---

## Hard rules

1. **Never generate documents until every relevant coverage category is ✅
   closed or explicitly deferred by the user** (deferred → `open-questions.md`
   with rationale). This is the core of the skill. No exceptions for "seems
   like enough".
2. **Never write after 3-5 questions.** Minimum 2 questions per relevant
   category. At least one research loop for any non-trivial project.
3. **Nothing is lost.** Everything meaningful the user says lands in
   `interview-log.md`. Every decision lands in `decisions.md` as BD-NNN.
4. **Push back on thin answers.** "Basic login" is not an answer until "basic"
   is defined. "Everyone" is not a target audience.
5. **Ease off on fatigue.** Short answers, "let's move on", visible irritation —
   drop laddering, batch the remaining gaps, offer Fast mode.
6. **One AskUserQuestion call = one question** (`questions` array of length 1),
   2-4 options plus the automatic "Other"; recommended option first with
   `(Recommended)`; `description` states the trade-off of each option.

---

## Phase 0: Recon (SILENT)

1. `docs/brief/` exists → **Update mode** (see below). Single-file
   `docs/PROJECT-BRIEF.md` exists → offer migration.
2. Existing codebase? Stack markers, README, docs/ — read what's there; the
   brief must document reality, not fantasy.
3. `--validate` argument → **Validate mode**. `--fast` → note Fast pace for
   Phase 2. Date via `date +%Y-%m-%d`.

## Phase 1: Brain dump

Open with free-form extraction, not questions:

> "Tell me about the project the way you see it — stream of thought, any order,
> any length. And share anything that already exists: notes, README, chat
> transcripts, links, competitor products you admire or hate."

- Read every material the user points to. Extract selectively into the
  coverage map (below) — mark which categories the dump already touched.
- Then always: **"What else? What did you think about at night but haven't
  written anywhere?"** — one more pass surfaces what structured questions miss.
- Log the dump's essence into `interview-log.md` (create the folder on first
  write).

**Raw idea?** If the user has a fuzzy one-liner and visibly hasn't thought it
through — offer a short brainstorm before interviewing (Phase 1.5). Otherwise
skip 1.5.

## Phase 1.5: Brainstorm (optional)

Coach mode, 3-5 rounds max. Ideas must come from the user — facilitate, don't
generate for them. Rotate probes: *"What if the main constraint disappeared?"*,
*"What existing product is this most like, and what's the one difference?"*,
*"Describe the day of a person whose problem is solved."* Capture everything
in `interview-log.md`, then continue to Phase 2.

## Phase 2: Pace selection

Ask via AskUserQuestion:

- **Interview (Recommended)** — one question at a time, full depth, laddering
  and pushback. Best foundation.
- **Fast** — remaining gaps batched into 2-3 grouped messages; the draft is
  generated with `[ASSUMPTION]` tags where answers were thin; every assumption
  is listed by name at approval. The coverage gate still applies.

---

## Phase 3: Coverage-driven interview

### Coverage map

Pick relevant categories by project type; ✅ requires the exit criterion, not
just "was asked about".

| # | Category | Closed when… | Relevant for |
|---|----------|--------------|--------------|
| C1 | Problem & motivation | Pain named; who feels it; how they cope today; cost of the status quo | all |
| C2 | Users | ≥1 concrete persona with a job-to-be-done — not "everyone" | all |
| C3 | Solution vision | User described the core scenario in their own words; echo-back confirmed | all |
| C4 | Differentiation | Answer to "why won't they just use existing X?" | all |
| C5 | Scope (v1) | Every capability tagged Must/Should/Out; each Must survived "is MVP dead without it?" | all |
| C6 | Data & privacy | What's stored, where from, who owns it; PII / compliance named or ruled out | backend, web, mobile, full-stack |
| C7 | Integrations | External systems listed; failure behavior for each critical one | backend, web, mobile, automation |
| C8 | Scale & load | Order of magnitude of users/requests; read- vs write-heavy | backend, web, full-stack |
| C9 | Security & roles | Who can do what; how users authenticate | all except pure CLI/library |

From askidmobile/ai-spec-kit, MIT.

More from askidmobile/ai-spec-kit