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 <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:

   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

• 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:
  • <name>.review.json
  • <name>.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