create-intent

Create Intent

Overview

Turn a set of requirement sources into a small, traceable document set that says what business wants, and a question list that makes the unclear parts clear.

Core principle: never guess silently. Every statement carries its source. Every gap becomes a question with an ID, both sides quoted, and a proposal. Questions go to the right person: business items to the PO, technical items to the tech lead.

The 70 / 30 rule

Follow 70%. Adapt 30%. Each use case is different.

Fixed (70% — always do)	Flexible (30% — decide per case)
Phases below, in order	Feature grouping and F-numbering
Read each source in full, one at a time, update docs after each	Extra documents (for example `states.md`, a code reference, a glossary)
Core docs: `intent.md`, `fr.md`, `nfr.md`, `memlog.md`	Table columns beyond the template minimum
Question rules (see Question craft)	Which review lenses to run
Source tags S / D / P / ? on anything not from a story	When to trace code for "same as screen X"
Business → `confirm-po.md`, technical → `confirm-tech.md`	How to present results (web page, chat, file)
Verification script before "done"	Number of questions per round

When you adapt, say what you changed and why in one line of the report.

When to use

A list of Jira story folders (for example from jira-to-local) or pasted requirements.
The user wants the business view: features, requirements, acceptance criteria (AC).
The user answers questions that an earlier run of this skill wrote.

Not for: technical design (architecture-design), PRD writing (bmad-prd), splitting into stories (bmad-create-epics-and-stories).

Phases

Setup. Read project writing rules (for example CLAUDE.md style section) and memories. Check that every source exists and its size. Create the doc folder. Scope = business need, FR, NFR, AC. Out of scope = technical design, technical solution, subtasks, checklists.
Read and record, one source at a time. Read the whole file. Then update all four core docs before the next file. Per source: FR section with AC as written, feature row in intent.md, reading-log row and new questions in memlog.md, NFR rows (a block repeated in every story is written once).
Follow the links. Stories that other stories depend on ("same as AC3 of X", "clones", "Visibility scope in X") — ask to pull them (jira-to-local), then read them like phase 2. Read comments.md of every story: comments often change scope.
Trace referenced behavior. "Follow the behavior of screen X" → one read-only Explore agent traces the code. Verify its key claims yourself (file:line). Write a separate reference doc. Put only user-facing behavior into fr.md.
Show the questions. Group by feature. Put "blocks design" items first. Offer a page or file where the user can answer.
Apply answers. Answers arrive in chat, in memlog.md (=> lines), or in a confirm file. Move each answer into the question table (Answer + Status columns). Add a Decision (Q#) line under the story AC it changes; keep the story text above it. Log user clarifications as C# rows. Save lasting boundary facts as memories.
Split for the audience. Unanswered and "confirm" business items → confirm-po.md (self-contained: terms, AC change table "current text → new text", new rules, stories not built, gaps with proposals). Technical items → confirm-tech.md. Ask the user which person answers what if unclear.
Review. When the user asks, run review skills on the doc set in parallel (bmad-review-adversarial-general, bmad-review-edge-case-hunter, bmad-editorial-review-structure, bmad-editorial-review-prose). Verify findings that cite sources. Turn gaps into G# (business) or T# (technical) rows with a proposal. Do not treat a PRD or other downstream doc as a source unless the user says so.
Verify. Run python3 <skill>/scripts/check_intent.py <doc-folder> and fix every finding. Then report.

Build the documents yourself, in the main conversation. Subagents only for read-only work: code tracing, review lenses, skill tests.

Question craft

The questions are the main value. Each question:

Has a stable ID: Q# (story questions), G# (business gaps from review), T# (technical items). Never renumber an answered item.
Cites the source: story key + AC, file, or clarification ID.
States the problem concretely: quote both sides of a conflict, name the missing case. Never "please clarify X".
Carries a proposal when one is reasonable ("Proposed rule: orders over 500 EUR need manager approval …").
Asks one thing. Split compound questions. Avoid negative questions ("Can the user never …").
Names its audience: business (PO) or technical (tech lead).

Where to find questions — check every source for: references/question-craft.md.

Source tags

Anything not copied from a story gets a tag: S story text, D decision (answer or comment), P our proposal waiting for approval, ? open. Never write an inferred rule as if a story said it. Never invent an AC; write it as a proposal or a question.

Templates

templates/ holds one skeleton per file: intent.md, fr.md, nfr.md, memlog.md, confirm-po.md, confirm-tech.md, states.md. Copy, then fill. Keep headings; add sections when the case needs them (30%).

Checklist

Every source read in full; reading-log row for each
Every source key appears in intent.md, fr.md, memlog.md
Every story AC kept; AC as **ACn** + bullets (Given / When / Then)
Repeated DoD / NFR block written once
Linked stories and comments.md read, or listed as not read
Every open item has ID, source, both sides, proposal, audience
No inferred rule without a tag; no invented AC
Answers moved into tables; Decision lines under the AC they change
confirm-po.md has no technical words; stands alone for a PO
Every G# / T# defined once and linked from fr.md
check_intent.py passes

Common mistakes

Mistake	Fix
Reading all sources, then writing at the end	One source → update all docs → next source
Skipping `comments.md`	Comments hold scope changes; read them
Filling a gap with a sensible guess	Write the guess as P proposal inside a question
Question without a proposal	Add the default you would pick, and why
Business and technical questions in one list	Split: PO gets business only
Deleting story text when a decision changes it	Keep it; add Decision (Q#) below
Copying the same NFR source to every row	One row, source "all stories"
Patch scripts that half-apply	Exact-match replacements with assert; re-run the whole script after a fix
History in docs	Docs hold latest state; `memlog.md` is the only log