BRD Reviewer

---

name: brd-reviewer

description: Review Business Requirements Documents in `.docx` format by reading the existing BRD, extracting paragraph-level context, drafting clarification questions for unclear statements, and producing a final Word document that combines comments and tracked changes. Use when the user wants a BRD reviewed, challenged for ambiguity, or redlined with proposed wording improvements while preserving Word-native review features.

---

# BRD Reviewer

Overview

Review a BRD paragraph by paragraph, capture clarification questions for ambiguous or incomplete requirements, and generate a single `.docx` with Word comments plus tracked revisions.

Prefer the bundled pipeline so the final deliverable is a Word-native review artifact instead of chat-only notes.

Workflow

1. Confirm the source BRD `.docx` path.

2. Initialize the paragraph review JSON:

```bash

python scripts/brd_review_pipeline.py init-review \

--input <brd.docx> \

--output <brd.review.json>

```

3. Read the BRD and fill the review JSON.

- For every `paragraphs[]` item, keep `paragraph_index`, `style_id`, `heading_path`, and `source_text` unchanged.

- Set `needs_comment` to `true` when the paragraph is unclear, incomplete, internally inconsistent, or missing acceptance criteria, data definitions, ownership, dependencies, assumptions, or edge cases.

- Write `comment_question` as a concise reviewer question suitable for a Word comment.

- Set `needs_revision` to `true` when the paragraph should be rewritten for precision, completeness, grammar, or testability.

- Write `proposed_replacement` as full replacement language, not fragments.

- Use `issue_tags` to make the reason explicit. Prefer tags such as `ambiguity`, `scope`, `actor`, `data`, `workflow`, `exception`, `dependency`, `acceptance-criteria`, `nonfunctional`, `term-definition`, or `conflict`.

4. Materialize the final reviewed DOCX in the same folder as the source BRD:

```bash

python scripts/brd_review_pipeline.py materialize \

--input <brd.docx> \

--review-json <brd.review.json> \

--output <brd.reviewed.docx> \

--author "Codex BRD Reviewer"

```

5. Verify output quality.

- Confirm the reviewed file exists beside the source BRD.

- Confirm Word comments appear on paragraphs with `needs_comment=true`.

- Confirm tracked changes are visible for paragraphs with `needs_revision=true`.

- If the BRD relies heavily on tables or special layout, use the `$doc` skill workflow to render and visually inspect the result before delivery.

Review standard

Output contract

- `<name>.review.json`

- `<name>.reviewed.docx`

Resources

Dependencies

Install once if missing:

python -m pip install python-docx lxml