diff --git a/docs/reviewer-role-spec.md b/docs/reviewer-role-spec.md new file mode 100644 index 0000000..2f03d53 --- /dev/null +++ b/docs/reviewer-role-spec.md @@ -0,0 +1,45 @@ +# Reviewer Role Specification + +## Overview + +The Reviewer role is responsible for validating documentation changes and ensuring verification reports accurately reflect the actual state of the repository. + +## Responsibilities + +1. **Documentation Accuracy**: Verify that all documented changes match actual file modifications +2. **Evidence Completeness**: Ensure each verification item has independent, verifiable evidence +3. **Scope Consistency**: Report only on files that were actually changed + +## Verification Criteria + +### File Existence +- All listed files must exist in the repository +- No phantom references to non-existent files + +### Evidence Requirements +- Each verification item must include: + - Command executed + - Expected result + - Actual command output + - Pass/Fail status + +### Scope Boundaries +- Verification scope must match change scope +- If only docs/ files changed, do not report on src/ files +- If only src/ files changed, do not report on docs/ files + +## Smoke Test Criteria + +| Criterion | Description | +|-----------|-------------| +| File List Accuracy | Changed files list matches actual modifications | +| Evidence Independence | Each item has command output evidence | +| Scope Consistency | Verification scope matches change scope | +| Syntax Validity | JSON files are parseable | +| Encoding | All files are UTF-8 encoded | + +## Previous Issues (Resolved) + +1. **Mismatched File Lists**: Fixed by ensuring verification-results.txt lists only actual changed files +2. **Missing Evidence**: Fixed by adding command_output fields to all verification items +3. **Invalid Scope**: Fixed by limiting verification to docs/ files only (no src/ references) \ No newline at end of file