# Brd > [Internal pipeline stage — run by /build; invoke directly only as a power user.] 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. - Skill: `cwijayasundara/brd` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add cwijayasundara/brd` - Raw SKILL.md: https://api.skillmd.com/api/skills/cwijayasundara/brd/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra, Coding & Dev Tools - Author: cwijayasundara (https://skillmd.com/u/cwijayasundara) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/cwijayasundara/brd --- # BRD Skill — Business Requirements Document ## Usage ``` /brd # interview-from-scratch /brd --frd path/to/frd.md # ground the BRD in a Functional Requirements Document /brd --prd path/to/prd.md # alias for --frd: a PRD is the grounding baseline /brd --delta path/to/prd-sprintN.md # ground sprint N's PRD against the prior sprint's requirement spine ``` Two modes: - **Document-grounded (recommended for greenfield):** pass `--frd ` (or its alias `--prd `) to a Functional/Product Requirements Document. `--prd` and `--frd` are treated identically — the document becomes the immutable grounding baseline, extracted into the same requirements spine (`frd-requirements.json`); only the input flag name differs. For the canonical PRD shape this skill grounds best against, see `docs/prd-format.md`. The document becomes the immutable grounding baseline — Claude interrogates it for gaps, then generates a BRD in which **every requirement traces back to a source section or to a confirmed clarification.** A deterministic gate (Step 4.4) hard-blocks anything invented or dropped relative to the source 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. --- ## Delta Mode (`--delta`) > Invoked by `/sprint` for sprint N (N >= 2). Grounds a new PRD against the > **prior sprint's approved requirement spine**, not against nothing — this is > what proves the new PRD's requirements are new/changed/carried, and flags > anything it silently drops. See > `docs/superpowers/specs/2026-07-04-sprint-delta-lane-design.md`. ### Step Δ0 — Locate the prior spine and resolve N List `specs/brd/sprint-*/` directories; let `prev` be the highest number found. If none exist, the prior spine is the flat legacy `specs/brd/brd-requirements.json` (sprint 1 predates sprint-numbered directories) and `N = 2`. If sprint directories exist, `N = prev + 1`. If neither the flat file nor any sprint directory exists, halt — `--delta` requires a prior sprint; use `--frd`/`--prd` for the very first sprint. ### Step Δ1 — Run Steps 0.0 through 4 unchanged, writing to `specs/brd/sprint-N/` Run the FRD-grounded flow (Steps 0.0, 0, 0.5, 1, 2, 2.8, 3, 4) exactly as written above, with one change: every output path becomes `specs/brd/sprint-N/` (e.g. `specs/brd/sprint-N/brd.md`, `specs/brd/sprint-N/brd-requirements.json`, `specs/brd/sprint-N/clarification-log.json`). When writing `brd-requirements.json`, any requirement that carries forward a prior-sprint requirement unchanged (or with only minor edits) must include that prior sprint's BR id in its `traces` array alongside this sprint's own FRD/clarification traces — this is what lets Step Δ2's classification tell "carried forward" apart from "silently dropped." ### Step Δ2 — Requirements-delta classification [HARD BLOCK] Step 4.4's grounding gate still runs unchanged (this sprint's BRD vs this sprint's own FRD/PRD spine). In addition, classify this sprint's spine against the **prior sprint's** spine — the same `trace-check.js` engine, reused with the prior spine as `required`, this sprint's spine also as a valid trace target (`optional`), and this sprint's spine as `downstream`: ```bash node .claude/scripts/trace-check.js \ --required specs/brd/sprint-{prev}/brd-requirements.json \ --optional specs/brd/sprint-N/brd-requirements.json \ --downstream specs/brd/sprint-N/brd-requirements.json \ --layer requirements-delta \ --out specs/brd/sprint-N/requirements-delta.json ``` (When `prev` refers to the flat legacy layout, use `--required specs/brd/brd-requirements.json`.) Read the resulting `requirements-delta.json`: - `net_new` entries are genuinely new requirements this sprint introduces — expected, not a failure. - `dropped` entries are prior-sprint requirements this sprint's spine does not cover — **each one needs an explicit human decision**: still active (add a BR entry carrying it forward) or intentionally retired (record why in this sprint's BRD Open Questions). A `dropped` entry with no such resolution is a silent regression — halt and ask before proceeding to Step 4.5. **Empty-spine guard:** a `required_total: 0` here means the prior sprint's spine is empty — a pre-spine legacy project. Skip this step in that case and note it in the BRD summary (Step 4.4's own grounding gate still runs normally against this sprint's spine). ### Step Δ3 — Present for Human Approval (delta mode) Same as Step 5, plus display the requirements-delta classification (new / changed / carried / dropped, with the human's resolution for each dropped item) before asking for approval. --- ## Steps ### Step 0.0 — Ingest the FRD (only when `--frd ` was given) If an FRD path was provided: 1. **Copy it verbatim** to `specs/brd/source-frd.md` — this is the immutable grounding baseline. Never edit it. 2. **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: ```json [ { "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 then the confirmed `INT-n` interview requirements captured in Step 2 (`specs/brd/interview-requirements.json`), plus the Step 0.5 clarification log. ### 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: ```json [ { "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, an `INT-n` interview requirement, 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. **As each dimension is confirmed, append the confirmed requirement statements to `specs/brd/interview-requirements.json`** — one entry per discrete requirement the human signed off: ```json [{ "id": "INT-1", "text": "Admins invite users by email", "section": "users-and-permissions" }] ``` Write entries **at confirmation time, not after synthesis** — this file is the grounding baseline the BRD is mechanically checked against (Step 4.4), so it must capture what the human confirmed before BRD prose can drift. Q&A detail that is context rather than a requirement stays in `clarification-log.json` (`C-n`); a statement the human confirmed as something the system must do is an `INT-n`. --- #### 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 2.7 — Seed Domain Vocabulary from Enabled Vertical Plugins **Run the vertical glossary pack script.** Run `node .claude/scripts/vertical-glossary-pack.js`. This is a no-op (nothing written, nothing to do here) unless `.claude/config/scaffold-packs.json`'s `verticalPacks` array has at least one entry whose `enabled_plugin_prefix` matches a truthy key in `.claude/settings.json#enabledPlugins`. - **Pack(s) written.** For each `specs/brd/-glossary-pack.json` the script wrote, read it. For each context entry, distill the real domain nouns implied by each skill's description into `CONTEXT.md`'s `## Terms` section (create `CONTEXT.md` from `.claude/templates/context.template.md` first if it does not exist yet). Use the context's `name` as a **``** bold grouping line (not a `###` heading — `vocabulary-check.js` parses every `###` under `## Terms` as a glossary term, so only actual terms may use that heading level), with individual `### ` entries and a one-line definition beneath each. - **Broken plugin install.** If the script exited 2, at least one enabled vertical's skills directory was missing or empty. Note the broken plugin install(s) in the progress log and continue — packs from any OTHER, successfully-resolved vertical were still written and should still be distilled per the bullet above. Do not block the BRD on a broken install. - **No verticals enabled.** If the script reported nothing enabled and wrote no pack files, no registered vertical plugin is active for this project — do nothing further. **Layering with Step 2.8.** Step 2.8 below still runs afterward for every project and merges `domain_concepts`-derived terms into the same `CONTEXT.md`, layering project-specific concepts on top of any vertical baseline(s) rather than overwriting them. --- ### Step 2.8 — Write the BRD Analysis Pack Before synthesizing the BRD prose, write `specs/brd/brd-analysis.json`. This is the SPDD-inspired analysis layer that turns the PRD/interview into a design contract instead of a thin summary. It must be grounded in the FRD/PRD, the clarification log, and existing-code scan. The JSON must include: ```json { "domain_concepts": [ { "name": "Subscription Plan", "status": "existing|new", "evidence": "FRD-1 or specs/brownfield/code-graph.json node", "notes": "business meaning and nearby terms" } ], "ambiguity_table": [ { "id": "AMB-1", "question": "What remains ambiguous?", "default_assumption": "Chosen assumption", "risk_if_wrong": "Concrete consequence", "resolution": "clarified|assumed|deferred", "trace": ["FRD-1", "C1"] } ], "edge_case_table": [ { "id": "EDGE-1", "scenario": "Boundary/failure case", "expected_behaviour": "Observable result", "trace": ["FRD-1"] } ], "decision_log": [ { "id": "DEC-1", "decision": "Chosen direction", "alternatives_rejected": ["Alternative A"], "rationale": "Trade-off that decided it", "trace": ["C2"] } ], "ac_coverage_matrix": [ { "requirement_id": "FRD-1", "acceptance_criteria": ["AC-1"], "covered": true, "gap": "" } ], "risk_gap_table": [ { "id": "RISK-1", "risk": "What could derail this", "mitigation": "Harness or design response", "owner": "human|agent|deferred", "trace": ["FRD-2"] } ] } ``` Rules: - **Domain Concepts** marks each important business object as `existing` or `new`. In brownfield mode, `existing` entries cite a code-graph node or file path; in greenfield, they cite FRD/PRD sections or `INT-n` interview requirements. - **Ambiguity Table** captures load-bearing uncertainties that were clarified, assumed, or deferred. A deferred ambiguity must appear in the BRD Open Questions. - **Edge-Case Table** names failures, limits, empty states, concurrency/race cases, and security/privacy exceptions that the BRD must preserve downstream. - **AC Coverage Matrix** proves every extracted FRD/PRD/`INT-n` requirement has at least one observable acceptance criterion before the grounding gate runs. - **Risk & Gap Table** records risks and missing inputs without turning them into hidden implementation scope. **Seed the domain glossary.** After writing `domain_concepts`, create or update `CONTEXT.md` at the repo root from it: for each entry, add or update a `### ` heading under `## Terms` using `notes` as the definition (use the template at `.claude/templates/context.template.md` if `CONTEXT.md` does not exist yet). Do this for greenfield BRDs too — `CONTEXT.md` must exist after this step whenever `domain_concepts` is non-empty, which it always is. If `/brownfield` already created `CONTEXT.md`, merge into it rather than overwriting existing terms. If this pack exposes a dropped requirement, unresolved high-risk ambiguity, or uncovered acceptance criterion, fix the interview/clarification log before proceeding. Do not paper over it in the BRD. ### Step 3 — Synthesize into BRD After all five dimensions are confirmed, produce a structured BRD with these sections: 1. Executive Summary 2. Problem Statement 3. Target Users 4. Success Metrics 5. Scope (In / Out) 6. MVP Definition 7. Alternatives Considered (with rationale for chosen approach) 8. Technical Architecture 9. Data Model Overview 10. External Integrations 11. Edge Cases & Constraints 12. UI Context 13. Open Questions 14. BRD Analysis Summary — summarize the Domain Concepts, Ambiguity Table, Edge-Case Table, AC Coverage Matrix, and Risk & Gap Table from `brd-analysis.json`; keep the full detail in JSON. 15. Forbidden Actions — an explicit list of things the implementation must **not** do, derived from the Out-of-Scope items (Dimension 2) and any source "non-goals". This becomes the deny-list the downstream gate (and any autonomous merge) enforces; phrase each as a checkable prohibition (e.g. "must not call external payment APIs", "must not store raw passwords"). ### 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: ```json [ { "id": "BR-1", "text": "Password reset via emailed link, token valid 1h", "traces": ["FRD-1", "C1"], "taxonomy": ["functional", "security_authz"], "acceptance": "Requesting a reset emails a link that logs the user in once within 1h and is rejected after." }, { "id": "BR-2", "text": "Paginated order history (20/page)", "traces": ["FRD-2", "C2"], "taxonomy": ["functional"], "acceptance": "Order history returns 20 items/page with working next/prev." } ] ``` Each BR entry carries an `acceptance` postcondition — an observable end-state the evaluator can verify, not a restatement of the requirement. This gives downstream gates (and any autonomous merge) a concrete pass/fail oracle instead of a self-judged "looks done". Each BR entry also carries `taxonomy` — one or more of the ten slots Step 4.45 checks. Tag by what the requirement *is*, not by which section it came from; one requirement may legitimately carry several tags (an authenticated endpoint is both `functional` and `security_authz`). **Also write `specs/brd/brd-acceptance.json`** — the postconditions split into individually traceable ids, one per observable claim: ```json [ { "id": "BR-1-AC1", "requirement": "BR-1", "text": "A reset request emails a link that logs the user in exactly once" }, { "id": "BR-1-AC2", "requirement": "BR-1", "text": "A reset link is rejected after 1 hour" } ] ``` A prose `acceptance` sentence usually bundles two or three separate claims, and a story can satisfy one while silently dropping another. Splitting them is what lets `/spec` Step 6.46 prove coverage at criterion granularity instead of at requirement granularity. **And write `specs/brd/brd-safeguards.json`** — the non-negotiable boundaries the design must honour, a superset of the Forbidden Actions list: ```json [ { "id": "SG-1", "kind": "invariant", "text": "An order total always equals the sum of its line items", "traces": ["FRD-3"] }, { "id": "SG-2", "kind": "prohibition", "text": "Must not store raw passwords", "traces": ["C4"] }, { "id": "SG-3", "kind": "limit", "text": "p95 checkout latency stays under 400ms", "traces": ["FRD-7"] } ] ``` `kind` is `invariant` | `prohibition` | `limit` | `norm`. These become required trace targets for the REASONS Canvas `Safeguards` and `Norms` sections at `/design`, so a business constraint cannot quietly fail to reach the design contract. **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 `INT-n` interview requirements and/or `C-n` clarifications; every `INT-n` must be covered by at least one BR entry. Create the `specs/brd/` directory if it does not exist. ### Step 4.4 — Grounding Gate [HARD BLOCK — all modes] Run the deterministic grounding check before the rubric evaluation — in FRD mode against the FRD spine, in interview mode against the confirmed interview spine. This proves mechanically — not by judgement — that the BRD invented and dropped nothing relative to the required spine (FRD or interview) + clarifications: ```bash 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 ``` In interview-from-scratch mode, run the same gate with the interview spine as the required set (the verdict keeps the generic `frd_total`/`frd_covered` field names): ```bash node .claude/skills/brd/scripts/grounding-check.js \ --frd specs/brd/interview-requirements.json \ --clarifications specs/brd/clarification-log.json \ --brd specs/brd/brd-requirements.json \ --out specs/reviews/brd-grounding.json ``` **Empty-spine guard (interview mode):** a verdict with `frd_total: 0` means `interview-requirements.json` is empty — the gate checked nothing. A completed five-dimension interview yields at least one `INT-n`; treat `frd_total: 0` as FAIL and return to Step 2 to capture the confirmed requirements before re-running. 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 a required-spine 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 only when neither `frd-requirements.json` nor `interview-requirements.json` exists — a pre-spine legacy project — and note the skipped gate in the BRD summary. **If you conducted the Step 2 interview in this session, the spine MUST exist** — a missing spine is a Step 2 execution bug, not a legacy project: reconstruct `interview-requirements.json` from the confirmed dimension summaries and re-run the gate. The skip applies only to a pre-existing BRD you did not author in this session.) ### Step 4.45 — Requirement-Taxonomy Floor [HARD BLOCK — all modes] The grounding gate proves the BRD invented and dropped nothing **relative to its source**. It cannot prove the source asked the right questions: if the FRD never mentions retention, authorization, or failure modes, the BRD is silent on them too and every check above still passes. Comprehensiveness then reduces to "all sections are non-empty", which is a formatting property. ```bash node .claude/scripts/brd-taxonomy-check.js \ --requirements specs/brd/brd-requirements.json \ --coverage specs/brd/taxonomy-coverage.json \ --out specs/reviews/brd-taxonomy.json ``` Every one of the ten slots — `functional`, `data_lifecycle`, `integration`, `performance`, `security_authz`, `privacy_retention`, `observability`, `operability_failure`, `ux_accessibility`, `constraints` — needs either a requirement tagged with it, or an entry in `specs/brd/taxonomy-coverage.json` recording why it does not apply: ```json [{ "slot": "privacy_retention", "na_reason": "the system stores no personal data; all records are anonymised aggregates" }] ``` **A justification must be a real reason.** `"N/A"`, `"none"`, `"TBD"`, and anything under 25 characters are rejected — the gate exists to force the question to be *asked*, and a box-tick means it was not. The reason lands in a committed artifact precisely so a reviewer can disagree with it. Resolve a failure at the source: a genuinely uncovered slot usually means the interview skipped a dimension. Return to Step 2, ask, capture the answer as a `C-n` clarification, and add the requirement — do not paper over it with an excuse. **Pre-existing BRD (not authored in this session).** A spine written before this gate existed carries no `taxonomy` field at all, so every requirement reports `UNTAGGED`. That is a migration state, not a quality signal. Tag the existing requirements first — reading each one and assigning its slots is a mechanical pass over an artifact you already have — then re-run. Do **not** record blanket `na_reason` entries to clear it; that converts a one-time migration into a permanently false clean bill of health. If you authored the spine in this session, `UNTAGGED` is a Step 4 execution bug: go back and tag them. ### 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`; in interview mode, `specs/brd/interview-requirements.json` + `specs/brd/clarification-log.json` - Grounding verdict: `specs/reviews/brd-grounding.json` in both modes (already PASS from Step 4.4 — the evaluator confirms the rubric's traceability criterion against it) (absent only for pre-spine legacy projects, where the gate was skipped and noted) - 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):** 1. If verdict is **PASS** — proceed to Step 5. Attach the eval summary (weighted average, any warnings). 2. If verdict is **FAIL** — revise the BRD to address ALL error-severity findings. Re-run the evaluator with incremented iteration and previous score. 3. **Ratchet rule:** weighted_average must be >= previous iteration's score. If it decreases, revert to the previous version and try a different revision approach. 4. 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 and `taxonomy` slots | | `specs/brd/brd-acceptance.json` | Postconditions split into individually traceable `BR-n-ACm` ids — what `/spec` Step 6.46 checks | | `specs/brd/brd-safeguards.json` | Invariants, prohibitions, limits, and norms — required trace targets for the Canvas | | `specs/brd/taxonomy-coverage.json` | Recorded `na_reason` for any taxonomy slot no requirement covers | | `specs/reviews/brd-taxonomy.json` | Ten-slot comprehensiveness verdict (`pass`, `uncovered[]`, `unjustified[]`) | | `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/interview-requirements.json` | (interview mode) confirmed `INT-n` requirement spine — the grounding baseline | | `specs/brd/clarification-log.json` | Confirmed interrogation answers (`C-n`) — the only sanctioned net-new content | | `specs/brd/brd-analysis.json` | SPDD-grade analysis pack: Domain Concepts, Ambiguity Table, Edge-Case Table, decision log, AC Coverage Matrix, and Risk & Gap Table | | `specs/reviews/brd-grounding.json` | deterministic grounding verdict (`pass`, `net_new[]`, `dropped[]`) | | `specs/brd/sprint-N/*` | (delta mode) sprint-N's BRD artifact set, same shape as the flat sprint-1 layout | | `specs/brd/sprint-N/requirements-delta.json` | (delta mode) new/changed/carried/dropped classification vs the prior sprint's spine | --- ## Gate **Grounding gate — hard block (both modes).** `grounding-check.js` proves mechanically that the BRD invented nothing (`net_new`) and dropped nothing (`dropped`) relative to the FRD spine (FRD mode) or the confirmed interview spine (interview mode), plus clarifications. Any violation blocks before the rubric even runs, regardless of quality score — see Step 4.4. **Taxonomy floor — hard block (both modes).** `brd-taxonomy-check.js` proves every one of the ten requirement slots is either covered by a tagged requirement or excused with a substantive, committed reason — the check the grounding gate structurally cannot make, since grounding is relative to a source that may itself be silent. See Step 4.45. **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 both modes the traceability criterion is anchored to the grounding verdict, and the completeness criterion to the taxonomy verdict, rather than 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.