create-intent

Files (10)

• SKILL.md
• question-craft.md · references/
• check_intent.py · scripts/
• confirm-po.md · templates/
• confirm-tech.md · templates/
• fr.md · templates/
• intent.md · templates/
• memlog.md · templates/
• nfr.md · templates/
• states.md · templates/

SKILL.md (first lines)

# 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

1. **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.
2. **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).
3. **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.
4. **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`.
5. **Show the questions.** Group by feature. Put "blocks design" items first. Offer a page or file where the user can answer.
6. **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.
7. **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.
8. **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.
9. **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](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 |

From bmad-labs/skills, MIT.

More from bmad-labs/skills