| name | brd |
| description | Create a Business Requirements Document — from a Socratic interview, or grounded in a Functional Requirements Document via --frd (with a deterministic net-new/dropped gate). First step in the SDLC pipeline. |
| context | fork |
| agent | planner |
BRD Skill — Business Requirements Document
Usage
/brd # interview-from-scratch
/brd --frd path/to/frd.md # ground the BRD in a Functional Requirements Document
Two modes:
- FRD-grounded (recommended for greenfield): pass
--frd <path> to a Functional Requirements Document. The FRD becomes the immutable grounding baseline — Claude interrogates it for gaps, then generates a BRD in which every requirement traces back to an FRD section or to a confirmed clarification. A deterministic gate (Step 4.4) hard-blocks anything invented or dropped relative to the FRD before you ever see it for approval.
- Interview-from-scratch: no argument — an interactive Socratic interview gathers requirements from nothing. Use only when there is no source document.
Overview
This is the first gate in the SDLC pipeline, and the origin of the whole grounding chain (BRD → /spec → /design → /test → /auto). Mistakes here cascade through every downstream phase, so the BRD must invent nothing the business did not state. With --frd, the FRD plus the human's confirmed interrogation answers are the only sanctioned sources of content; with no FRD, the confirmed interview answers are. Either way the planner interviews the human across five dimensions to surface the full problem space — Socratic: ask clarifying questions, probe assumptions, reflect answers back for confirmation before moving on.
Steps
Step 0.0 — Ingest the FRD (only when --frd <path> was given)
If an FRD path was provided:
- Copy it verbatim to
specs/brd/source-frd.md — this is the immutable grounding baseline. Never edit it.
- Extract its requirements into
specs/brd/frd-requirements.json — one entry per discrete functional requirement, with a stable id, the requirement text, and the source section:
[
{ "id": "FRD-1", "text": "Users can reset their password via an emailed link", "section": "3.2 Authentication" },
{ "id": "FRD-2", "text": "Users can view their order history", "section": "4.1 Orders" }
]
Be exhaustive and faithful — every "the system must / shall / should" statement, every user-facing behavior, every business rule becomes one FRD-n. Do not paraphrase away constraints. This list is what the BRD will be checked against, so a requirement you fail to extract here is a requirement that can be silently dropped.
If no --frd was given, skip this step; the BRD's grounding baseline is the confirmed interview answers (Step 0.5) alone.
Step 0 — Brainstorm with Superpowers
Before beginning the interview, invoke superpowers:brainstorming to explore the user's intent, requirements, and design space. This surfaces hidden assumptions and alternative framings before the structured Socratic interview locks in a direction. In FRD-grounded mode, brainstorm gaps and ambiguities in the FRD specifically — what it leaves unspecified. The brainstorming output feeds into the interview — it does not replace it.
Step 0.5 — Apply the Clarification Budget (and log every answer)
Before asking interview questions, invoke .claude/skills/clarify/SKILL.md. Use it to cap the total clarification burden:
- Ask only load-bearing questions that affect requirements, scope, data, security, architecture, or story readiness.
- Default to 10 total questions across the BRD interview.
- Continue to 15 only if the user explicitly asks to keep going.
- Capture low-risk assumptions in the BRD instead of asking about them.
Persist every confirmed answer to specs/brd/clarification-log.json with a stable id:
[
{ "id": "C1", "question": "What is the password-reset token TTL?", "answer": "1 hour" },
{ "id": "C2", "question": "Should order history paginate?", "answer": "Yes, 20 per page" }
]
The clarification log is the only sanctioned channel for content not already in the FRD. A BRD requirement may legitimately introduce something new only if it traces to an FRD section or a C-n clarification here — so anything the human confirms that expands scope must be captured as a C-n entry, not absorbed silently into the BRD prose.
Step 1 — Analyze Existing Codebase (if any)
Before beginning the interview, scan the working directory for existing code. Note:
- Current tech stack, frameworks, languages
- Existing data models or schemas
- Existing API surface
- Any patterns or conventions already in use
If this is an existing non-trivial codebase and specs/brownfield/codebase-map.md does not exist, recommend running /brownfield first. For small or urgent work, continue only after documenting the risk and the limited scope.
This prevents proposing solutions that conflict with what is already built.
Step 2 — Conduct the Five-Dimension Interview
Work through each dimension in order. Do not skip dimensions. Ask only the highest-value questions within the clarification budget, then summarize what you heard and ask the human to confirm before proceeding. If a dimension is already answered by local context, document the assumption and move on.
Dimension 1 — Why (Problem & Goals)
- What problem does this solve, and for whom?
- Who are the target users (role, technical level, context of use)?
- What does success look like in 90 days? What metrics will you track?
- What is the cost of not solving this problem?
Confirm: "Here is what I understand the problem and goals to be: [summary]. Is this correct?"
Dimension 2 — What (Scope & MVP)
- What are the core operations this system must perform? (List them.)
- What is explicitly out of scope for the first version?
- What is the minimum viable product — the smallest slice that delivers real value?
- Are there existing tools or systems this must integrate with?
Confirm: "Here is the core scope and MVP as I understand it: [summary]. Anything to add or change?"
Dimension 2.5 — Alternatives (Implementation Approaches)
Propose 2-3 concrete implementation approaches with trade-offs. For each option:
- Brief description of the approach
- Key advantages
- Key disadvantages / risks
- Best suited for (what context)
Ask the human to choose an approach or blend aspects. Document the chosen direction and the rationale for rejecting alternatives.
Dimension 3 — How (Technical Architecture)
- What is the preferred tech stack, or are there constraints (language, cloud, existing infra)?
- How will data be stored? What are the main data entities?
- Are there external integrations, APIs, or third-party services involved?
- What are the performance or scalability requirements?
Confirm: "Here is the technical direction I am capturing: [summary]. Does this match your expectations?"
Dimension 4 — Edge Cases (Failure & Constraints)
- What happens when [key operation] fails? Who is notified, and how?
- What are the operational constraints (uptime requirements, rate limits, budget)?
- Does this system handle sensitive data (PII, financial, health)? What compliance applies?
- What are the most likely failure modes in the first 6 months?
Confirm: "Here are the constraints and failure scenarios I am recording: [summary]. Anything missing?"
Dimension 5 — UI Context (Interface & Design)
- Is there a UI? If so, what are the primary screens or flows?
- Are there design references, mockups, or brand guidelines to follow?
- What devices and viewports must be supported (desktop, tablet, mobile)?
- Are there accessibility requirements (WCAG level)?
Confirm: "Here is the UI context I have captured: [summary]. Is this complete?"
Step 3 — Synthesize into BRD
After all five dimensions are confirmed, produce a structured BRD with these sections:
- Executive Summary
- Problem Statement
- Target Users
- Success Metrics
- Scope (In / Out)
- MVP Definition
- Alternatives Considered (with rationale for chosen approach)
- Technical Architecture
- Data Model Overview
- External Integrations
- Edge Cases & Constraints
- UI Context
- Open Questions
Step 4 — Write to specs/brd/
- For a new project: write to
specs/brd/brd.md
- For a feature addition: write to
specs/brd/feature-{name}.md
Also write the machine-readable requirement spine to specs/brd/brd-requirements.json — one entry per BRD requirement, each with a stable id and a traces array citing the FRD section ids and/or C-n clarification ids it derives from:
[
{ "id": "BR-1", "text": "Password reset via emailed link, token valid 1h", "traces": ["FRD-1", "C1"] },
{ "id": "BR-2", "text": "Paginated order history (20/page)", "traces": ["FRD-2", "C2"] }
]
Every BR entry must carry at least one valid trace. If you cannot trace a requirement to an FRD section or a clarification, it is invented — either remove it, or (if the human genuinely wants it) capture the human's confirmation as a new C-n entry in clarification-log.json first, then trace to it. In interview-from-scratch mode (no FRD), trace BR entries to C-n clarifications only.
Create the specs/brd/ directory if it does not exist.
Step 4.4 — Grounding Gate [HARD BLOCK — FRD mode]
When an FRD was provided, run the deterministic grounding check before the rubric evaluation. This proves mechanically — not by judgement — that the BRD invented and dropped nothing relative to the FRD + clarifications:
node .claude/skills/brd/scripts/grounding-check.js \
--frd specs/brd/frd-requirements.json \
--clarifications specs/brd/clarification-log.json \
--brd specs/brd/brd-requirements.json \
--out specs/reviews/brd-grounding.json
The script writes specs/reviews/brd-grounding.json ({ pass, frd_total, frd_covered, net_new[], dropped[] }) and exits non-zero on any violation. This is a hard gate, independent of the rubric score:
net_new non-empty → the BRD invented a requirement not in the FRD or any clarification. For each, either delete it or get explicit human sign-off and record it as a C-n clarification (then re-trace and re-run). Do not proceed with an unresolved net-new requirement.dropped non-empty → the BRD silently lost an FRD requirement. Add a BR entry covering it (or, if the human confirms it is intentionally out of scope, record that decision as a C-n clarification noting the deferral) and re-run.
Only when brd-grounding.json#pass === true may you proceed to Step 4.5. (Skip this step entirely in interview-from-scratch mode — there is no FRD to ground against.)
Step 4.5 — Phase Evaluation Gate
Spawn the evaluator agent (artifact mode) to validate the BRD before human review.
Agent invocation:
Spawn Agent with subagent_type="evaluator" and prompt:
- Phase: brd
- Artifact: the BRD file path (specs/brd/brd.md or specs/brd/feature-{name}.md)
- Upstream: in FRD mode,
specs/brd/source-frd.md + specs/brd/frd-requirements.json + specs/brd/clarification-log.json; otherwise none
- Grounding verdict: in FRD mode,
specs/reviews/brd-grounding.json (already PASS from Step 4.4 — the evaluator confirms the rubric's traceability criterion against it)
- Rubric: Read .claude/templates/phase-eval-rubrics.json, key "brd"
- Iteration: 1 (increment on retry)
- Previous score: null (or previous iteration's weighted_average)
- Write result to specs/reviews/phase-brd-eval.json
Ratchet loop (max 3 iterations):
- If verdict is PASS — proceed to Step 5. Attach the eval summary (weighted average, any warnings).
- If verdict is FAIL — revise the BRD to address ALL error-severity findings. Re-run the evaluator with incremented iteration and previous score.
- Ratchet rule: weighted_average must be >= previous iteration's score. If it decreases, revert to the previous version and try a different revision approach.
- After 3 iterations without PASS — present the best-scoring version to the human with all findings attached. Note: "Phase evaluator did not reach threshold after 3 iterations. Findings below require human judgment."
Step 5 — Present for Human Approval
Display the BRD and ask: "Does this BRD accurately capture the requirements? Approve to proceed to /spec, or provide corrections."
Output
| File | Purpose |
|---|
specs/brd/brd.md | Full BRD for a new project |
specs/brd/feature-{name}.md | BRD for a feature addition |
specs/brd/brd-requirements.json | Machine-readable requirement spine; each BR carries traces to FRD/clarification ids |
specs/brd/source-frd.md | (FRD mode) immutable copy of the provided FRD — the grounding baseline |
specs/brd/frd-requirements.json | (FRD mode) extracted FRD-n requirements the BRD is checked against |
specs/brd/clarification-log.json | Confirmed interrogation answers (C-n) — the only sanctioned net-new content |
specs/reviews/brd-grounding.json | (FRD mode) deterministic grounding verdict (pass, net_new[], dropped[]) |
Gate
Grounding gate (FRD mode) — hard block. grounding-check.js proves mechanically that the BRD invented nothing (net_new) and dropped nothing (dropped) relative to the FRD + clarifications. Any violation blocks before the rubric even runs, regardless of quality score — see Step 4.4.
Phase evaluation gate runs before human approval. The evaluator agent (artifact mode) scores the BRD against 5 criteria (completeness, traceability, specificity, consistency, actionability). Threshold: average >= 7.0, all criteria >= 5. In FRD mode the traceability criterion is anchored to the grounding verdict, not free judgement.
Human approval is still required before proceeding to /spec. The gates validate quality + grounding; the human validates intent.
Do not auto-advance. Wait for explicit approval or correction.
Gotchas
- Do not skip the interview. Never generate a BRD from a single sentence of input.
- Do not skip Dimension 2.5. Alternatives must be explored and documented.
- Avoid vague success metrics. "Users are happy" is not a metric. Push for numbers.
- Check existing code first. Proposing a new auth system when one already exists wastes cycles.
- Confirm each dimension before moving on. Misunderstood requirements compound.
- Do not conflate MVP with the full product. MVP is the smallest deployable slice.
