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 \

--output

```

1. 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.
2. Materialize the final reviewed DOCX in the same folder as the source BRD:

```bash

python scripts/brd_review_pipeline.py materialize \

--input \

--review-json \

--output \

--author "Codex BRD Reviewer"

```

1. 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

• Question every paragraph that leaves implementation choices unresolved.
• Favor reviewer comments for missing information and tracked changes for proposed wording.
• Rewrite requirements into concrete, testable statements.
• Flag undefined actors, systems, interfaces, calculations, timing, permissions, and exception handling.
• Do not silently invent business rules. If the BRD lacks a critical detail, ask for it in the comment instead of guessing.
• Keep comments short and specific enough to be actionable in a comment balloon.
• Keep proposed replacements professional and directly usable in the document.

Output contract

• Always produce:
• .review.json
• .reviewed.docx
• Place both outputs in the same folder as the source BRD unless the user explicitly requests another path.
• Treat chat analysis as supplemental only. The .docx is the primary deliverable.

Resources

• Paragraph review schema: references/review-json-schema.md
• Main tool: scripts/brd_review_pipeline.py

Dependencies

Install once if missing:

python -m pip install python-docx lxml