Review Business Requirement Document Skill

---

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:

   python scripts/brd_review_pipeline.py init-review \
     --input  \
     --output 
   

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:

   python scripts/brd_review_pipeline.py materialize \
     --input  \
     --review-json  \
     --output  \
     --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

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