Review BRD Skill

Merge Request: Add review-brd skill — BRD / scope-document review gate

Summary

Adds a skill, review-brd, that cross-examines a Business Requirements Document (BRD), TO-BE process map, or scope document or DRG and produces a defensible GO / NO-GO verdict backed by a written review report. It is the quality gate a requirements document passes through before it goes to write-prd: it forces every gap, ambiguity, contradiction, and unstated assumption to be either resolved or explicitly accepted as a risk, and it separates blockers we control from items that are merely waiting on the client.

Why we need it

Requirements documents reach the team in mixed states of readiness. Starting a PRD (or worse, development) on a BRD with hidden contradictions or undefined core behavior wastes cycles and surfaces the gaps late. review-brd makes the readiness check explicit and repeatable, gives a documented verdict any stakeholder can read, and — importantly — never blocks our own progress on a client's outstanding decision: client-pending items are surfaced loudly but do not gate the go-ahead.

What the skill does

1. Ingests the document set. Reads the BRD fully, and any companion docs it references (TO-BE maps, scope appendices, architecture PDFs, linked tickets) — the whole set, not one file. Handles common formats (Markdown, PDF, images, Excel; Excel is parsed sheet-by-sheet).

2. Tests assumptions against reality. Where the BRD touches an existing codebase or system, it explores that system and flags every place the document assumes behavior the system does not have or contradicts how it actually works.

3. Runs a 2-agent review council. Two independent reviewers examine the document in parallel through partitioned mandates:

   • Solution agent (business POV): is the requirement right and complete? Actors/triggers/inputs/outputs/exception paths, business-rule and calculation-logic correctness, scope boundaries, consistency with the TO-BE process, stale superseded rows, business-decision TBDs, master/reference data the business must supply, success metrics, stakeholders and sign-off.
   • Developer agent (development & architecture POV): can engineering build it and can we verify it? Technical feasibility, integration/interface contracts, join keys between datasets, ingestion/posting mechanics, auth/idempotency/retries/ordering, volume/scale, schema and data quality, performance/SLA, security, audit/retention, measurable acceptance per requirement, and architecture conflicts across documents.

   Their findings are merged and deduped in the main thread. On a severity conflict the higher severity wins; a split between the two reviewers is treated as signal and raised with the user. (For trivial documents, or when agents are unavailable, the skill reviews single-pass instead.)

4. Interviews the user on the blockers we own. Walks each open Us-owned and Joint blocker until shared understanding is reached or the user explicitly accepts the gap as a risk. The answers become the resolution log in the report.

5. Classifies and decides. Every finding is tagged Severity (Blocker / Major / Minor) and Owner (Us / Client / Joint). Verdict rule:

   • GO — no open Us-owned (or unresolved Joint) blocker. Client-owned blockers are allowed but listed under Awaiting Client and must close before go-live.
   • NO-GO — one or more open Us-owned or unresolved Joint blockers remain, listed exactly.

6. Files a report to docs/brd-reviews/<YYYY-MM-DD>/<brd-slug>-review.md.

What it produces

A single Markdown review report containing:

• Verdict — GO / NO-GO with a one-paragraph rationale.
• Process Coverage Matrix — pipeline readiness at a glance: intake → master data → extraction → validation → approval → downstream posting, each rated Covered (Yes/Partial/No), Clarity (Clear/Vague/Missing), and a one-line gap note.
• Council Panel — the two reviewers, their findings counts, and any divergence reconciled.
• Findings — merged, deduped table: severity, owner, location, issue, resolution.
• Open Blockers — the exact Us-owned items that must be fixed (NO-GO only).
• Awaiting Client — highlighted, non-gating client items, each with what we need and who owns it.
• Accepted Risks — Majors the user chose to proceed with, plus rationale.
• Resolved Clarifications — the decisions extracted during the interview, to carry into the PRD.

How to use it

/review-brd <path-to-brd>           # e.g. /review-brd DOCS/scope.xlsx
/review-brd                          # then paste or point to the document

The skill asks for the file (or pasted text), pulls in any referenced companion docs, runs the council, interviews you on the blockers it owns, presents the proposed verdict for acknowledgement, and files the report. On a GO it reminds you to run write-prd; it never invokes write-prd itself.

Scope and boundaries

• In scope: reviewing and gating a requirements/scope document; producing the verdict and report.
• Out of scope: writing the PRD (that's write-prd) and breaking requirements into work items (that's the issues skills). The skill explicitly hands off rather than overstepping.

Conventions

• Installed user-scoped at ~/.claude/skills/review-brd/SKILL.md, so it is available in every project for the whole team once distributed.
• Reports land under docs/brd-reviews/<date>/ in the working repo; if a report already exists at the target path the skill appends -v2 rather than overwriting.
• Read-only with respect to the source documents; it never edits the BRD.

Risk

Low. The skill is additive and self-contained; it produces a document and asks questions but makes no code or system changes. Council mode spends roughly 2× tokens versus a single pass — acceptable for large or contested BRDs, and the skill falls back to single-pass on trivial documents.