generate-project-brief — SPEAKMAN.AI Phase 0 Idea Intake

You are running Phase 0 of the SPEAKMAN.AI SDLC: turning a raw idea — a paragraph from a CEO, a Slack thread, a half-formed pitch — into a project brief rigorous enough to feed /generate-sad (Phase 1) or a sizing/investment-gate session directly. Nothing here calls the SPEAKMAN.AI MCP server. This phase is entirely conversational discovery plus local file writes — it costs no credits and produces no workflow session.

Your job is to coach, not to author. The brief describes the user's idea, not your elaboration of it. Ask sharp, specific questions; push back gently when an answer is vague; write down what the user actually says. Where you fill a gap because a question truly went unanswered, mark it [ASSUMPTION] in the brief text — never launder your own guess as the user's stated intent.

Credit

This skill's coaching stance, fast-path/coaching-path structure, and append-only audit-trail approach are adapted from the Product Brief workflow in BMAD-METHOD, an open-source AI-driven development framework built by a contributor community numbering in the tens of thousands. Used under BMAD-METHOD's MIT License (Copyright (c) 2025 BMad Code, LLC) — this is an independent SPEAKMAN.AI adaptation, rewritten for this pipeline, not a redistribution of BMAD-METHOD's own files. "BMad," "BMad Method," and "BMad Core" remain BMad Code, LLC's marks; nothing here implies affiliation with or endorsement by that project.

Step 0 — Determine Mode

Ask the user:

"What do you need?

Create — start a new project brief from an idea

Update — revise an existing brief against new information

Validate — get an honest critique of an existing brief's rigor before you trust it"

Store as MODE. If Update or Validate, also ask:

"Where's the existing brief? Point me at the outputs/YYYY-MM-DD_{slug}/ directory (I'll read brief.md and .memlog.md from it) or directly at a brief.md file."

Resolve and store BRIEF_DIR (the directory containing brief.md). If the path given is a file, its parent directory is BRIEF_DIR. Read brief.md; if .memlog.md exists alongside it, read that too — read the audit trail before touching the content, so you understand what was already decided and why before proposing any change.

If MODE is Create, skip to CREATE — Step 1. If Update, skip to UPDATE — Step 1. If Validate, skip to VALIDATE — Step 1.

CREATE

CREATE — Step 1 — Resolve Output Location

Ask the user:

"What's the project/idea called, and where should the brief live? Give me a parent directory (e.g. D:\git\tutorial\outputs or a project root) and I'll create outputs/YYYY-MM-DD_{slug}/ under it."

Create OUTPUT_PARENT/outputs/YYYY-MM-DD_{slug}/ (slug = lowercase-hyphenated project name, date = today). Initialize .memlog.md in that directory with a header and the first entry (mode: Create, started, source material provided if any).

CREATE — Step 2 — Open Discovery

Ask the user for a free-form dump of everything they have — the idea in their own words, and any source material: a pitch doc, a Slack thread pasted in, competitor URLs, prior research, a file, a directory. Tell them explicitly: you can read files and fetch URLs directly — if they hand you a path or a link, go read it yourself rather than asking them to summarize it. That's real leverage over a manual process; use it before asking a single clarifying question.

Store the raw material as RAW_INPUT. Skim it for what it already answers before Step 3 — don't re-ask what's already on the page.

CREATE — Step 3 — Choose a Discovery Path

Ask:

"How much time do you want to spend on this? Fast path — I'll draft the whole brief from what you've given me, flag every gap I filled with [ASSUMPTION], and you correct what's wrong in one pass. Coaching path — I'll ask you one sharp question at a time until each section is genuinely load-bearing, pushing back where an answer is too vague to build on."

Store as PATH. This is a per-brief choice, not a global one — a low-stakes internal tool and a client-facing rebuild of a payments flow deserve different amounts of rigor.

Fast path: batch the questions from CREATE — Step 4 into 2–3 grouped prompts, fill gaps with your own reasonable inference tagged [ASSUMPTION], and present the full draft for one round of correction.
Coaching path: work through CREATE — Step 4 one question at a time. When an answer is vague ("users will love it," "make it fast"), ask what specifically changes for whom, or what number "fast" means, before moving on. Ease off once a section is clearly rigorous — this is coaching, not interrogation; don't manufacture friction once the answer is solid.

Log the chosen path and every substantive question/answer pair to .memlog.md as you go — append-only, timestamped, one entry per decision. This is the record a later Update or Validate pass reads before touching anything.

CREATE — Step 4 — Structured Discovery

Work through each of the following with the user (order is a guide, not a script — follow what RAW_INPUT already answers and skip re-asking it):

Vision — one or two sentences: what is this, for whom, why does it need to exist now?
Problem statement — what pain does this solve? What happens if it's never built?
Goals & success metrics — the business goals, and measurable outcomes for each (a number, a rate, a deadline — not "improve efficiency").
Target users & personas — who uses this, and what do they specifically need from it? Don't accept "everyone" — press for the primary 1–3 personas.
Scope — explicit in-scope and out-of-scope boundaries. Out-of-scope is as important as in-scope; if the user hasn't thought about what's excluded, ask directly.
Key drivers & constraints — deadlines, budget signals, regulatory/compliance requirements, org mandates, anything non-negotiable.
Existing capabilities & tech context — what the org already has that this could reuse (platforms, APIs, data, teams) versus what would be genuinely new. Capture this explicitly as a list — it feeds the Sizing & Investment Gate's Existing-vs-New dependency framing directly, so vague answers here cost real quality downstream.
Competitive / market landscape (optional — only if relevant to the idea) — if the user names competitors or comparable products, go research them yourself (WebSearch / WebFetch) rather than asking the user to describe competitors from memory. Summarize findings in the brief; keep the full research dump for addendum.md.
Risks & open questions — name what could sink this and what's still genuinely unknown. An empty risk list is a sign you haven't pushed hard enough, not a sign the idea is safe.

CREATE — Step 5 — Draft the Brief

Write brief.md in BRIEF_DIR with this structure:

---
title: {project name}
status: Draft
created: {today, YYYY-MM-DD}
updated: {today, YYYY-MM-DD}
mode_history: [Create]
---

# {Project Name} — Project Brief

## Vision
## Problem Statement
## Goals & Success Metrics
## Target Users & Personas
## Scope
### In Scope
### Out of Scope
## Key Drivers & Constraints
## Existing Capabilities & Tech Context
## Competitive & Market Landscape        (omit section if not applicable)
## Risks & Open Questions
## Assumptions                            (fast path only — list every [ASSUMPTION] made, omit section if none)
## Recommended Next Step

For Recommended Next Step, make a real call, not a hedge: if scope or cost is genuinely uncertain, recommend the Sizing & Investment Gate workflow (MCP_SIZING_ESTIMATE_V1) before committing to full architecture; if scope is already tight and the stakes justify skipping straight to design, recommend /generate-sad directly. Say why in one sentence.

Present the full draft to the user — every section, not a compressed summary — and get explicit confirmation or corrections before treating it as final. Log the confirmation (and any corrections made) to .memlog.md.

CREATE — Step 6 — Addendum (if needed)

If there's material that doesn't belong in the main brief but is worth keeping — full competitive research notes, rejected framings, detailed persona interview notes, raw source material — write it to addendum.md in BRIEF_DIR, and add a one-line pointer to it at the bottom of brief.md. Skip this file entirely if there's nothing that clears that bar; an empty addendum is worse than no addendum.

CREATE — Step 7 — Channel to the SDLC

brief.md's structure already covers what Phase 1 and the Sizing Gate each need as a business description — no reformatting step required. Tell the user:

"Brief is ready at {BRIEF_DIR}/brief.md. Two ways to use it next:

Sizing & Investment Gate (MCP_SIZING_ESTIMATE_V1) — relative T-shirt sizing per component plus an overall estimate, with a human review gate. Good next step if cost/scope is still an open question the business needs to weigh in on before committing.

/generate-sad — full Solution Architecture Document. Point its Step 1 at this file path directly; it reads files natively as a business-description source.

Recommendation: {the Recommended Next Step call made in CREATE — Step 5}."

UPDATE

UPDATE — Step 1 — Confirm What Changed

BRIEF_DIR, brief.md, and .memlog.md are already loaded from Step 0. Ask the user:

"What changed? New information, a stakeholder correction, scope creep you need to capture — tell me what's different from what's in the brief now."

UPDATE — Step 2 — Surface Conflicts Before Changing Anything

Before editing, check the proposed change against the brief's existing content and the audit trail. If it contradicts a prior decision, say so explicitly and get confirmation before proceeding — never silently overwrite:

"This contradicts what's recorded on {date} in the brief: '{prior content}'. Confirm you want to replace it, or is this meant to sit alongside it?"

UPDATE — Step 3 — Apply the Change

Edit brief.md in place. Bump updated in the frontmatter to today; append Update to mode_history if not already the most recent entry. If the change affects Scope, Goals, or Existing Capabilities, re-check whether Recommended Next Step still holds — update it if the change shifts the sizing/architecture call.

Append an entry to .memlog.md: what changed, why, and what (if anything) it contradicted.

UPDATE — Step 4 — Report

Show the user the diff in plain terms (what sections changed, old → new) and confirm before treating the update as final. If this brief already fed a downstream Phase 1 or Sizing Gate session, flag that explicitly:

"Note: this brief already fed a downstream session. That session's outputs now reflect the old content — re-run it if this change is significant enough to matter to what it produced."

VALIDATE

VALIDATE — Step 1 — Critique Honestly

BRIEF_DIR and brief.md are already loaded from Step 0. Read the brief against its own stated purpose and critique it plainly — cite the specific section/line, don't soften a real gap:

Vague goals — goals without a measurable outcome attached
Unjustified scope boundaries — an in/out call with no stated reason
Personas with no clear need — a persona listed but never tied to a goal or requirement
Missing risk coverage — an empty or thin Risks section for a nontrivial idea
Internal contradictions — e.g. an out-of-scope item a later section quietly assumes
Unlabeled assumptions — content that reads like an inference but isn't tagged [ASSUMPTION], meaning the user might be trusting it as their own stated intent

VALIDATE — Step 2 — Flag What You Can't Evaluate

Some claims need external verification you can't do from the brief alone (a market-size number, a competitor's actual pricing, a compliance requirement's exact scope). List these separately as "needs verification," not folded into the pass/fail critique — don't guess at them yourself.

VALIDATE — Step 3 — Report

Project Brief Validation — {title}
Location: {BRIEF_DIR}/brief.md

Findings
  [section] — {issue, one line}
  ...

Needs verification (not evaluable from the brief alone)
  - ...

Overall: {ready to proceed | needs another pass}

Append the validation run and its findings to .memlog.md.

VALIDATE — Step 4 — Offer to Roll Findings Into an Update

Ask: "Want me to apply any of these fixes now?" If yes, switch into UPDATE mode (UPDATE — Step 2 onward) for each finding the user wants addressed, one at a time.

Rules

Coach, don't author. The brief is the user's idea in their own words; you sharpen and structure, you don't invent content and present it as theirs. Every gap you fill gets [ASSUMPTION].
Use real tools for real research. If the user hands you a file, URL, or competitor name, go read/fetch it yourself — don't ask them to do research a connected coding agent can do directly.
Read the audit trail before an Update or Validate touches anything. .memlog.md is the record of what was already decided and why; treat it as ground truth, not a log to skip.
Never silently overwrite a prior decision. Surface the conflict, get confirmation, then edit.
Show the whole thing, not a summary. When presenting a draft brief or a multi-item critique back to the user, show every section/finding individually — compressing a human-review moment into "a couple of interesting points" defeats the point of the gate.
This phase never touches the SPEAKMAN.AI MCP server. No start_session, no credits — if a task needs a real workflow session, that's Phase 1 or the Sizing Gate, not here.

generate-project-brief

SKILL.md.claude/skills/generate-project-brief/SKILL.md