brd-reviewer（BRD reviewer 文档）

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>

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.

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

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:

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