microsoft / microsoft/hve-core
docs: Documentation drift: code-review README doesn't reflect new change-risk evidence checklist
- Dominant language
- Python
- Stars
- 1.5k
- Forks
- 301
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 92
Description
## Component
Documentation
## Bug Description
Commit f97a38c ("feat(code-review): add advisory change-risk evidence checklist (#2550)") introduced a new six-category evidence checklist (`.github/skills/coding-standards/code-review/references/change-risk-model.md`) that drives depth-tier recommendations, and substantially rewrote `references/depth-tiers.md` to describe evidence-based recommendations (`observed`/`unavailable`/`qualitative` states, human-confirmed vs automation-derived provenance) instead of the prior generic "small/low-risk" language. `review-artifacts.instructions.md` also gained a new "Change-Risk Decision State" section documenting `changeRiskEvidence` and `reviewStateProvenance` fields persisted in `diff-state.json`.
`docs/agents/code-review/README.md` (the narrative usage guide) was not updated. Its "Depth Tiers" section (around lines 176-184) still describes tiers using only the old generic guidance ("Quick pass on small or low-risk changes", "Deep verification for high-risk surfaces or large changes") and never mentions the six evidence categories, the evidence-state vocabulary, or the new `change-risk-model.md` reference. Step 3 of the workflow table only vaguely says the agent "pre-populates a recommended default derived from the scope," which no longer reflects the more specific evidence-checklist mechanism now in place.
## Expected Behavior
`docs/agents/code-review/README.md` should describe the change-risk evidence checklist: the six categories (change scope, path criticality, history, test presence, coverage, rollback), the three evidence states, and that the human always confirms the final depth tier while the recommendation stays advisory. It should link to the new `change-risk-model.md` reference, consistent with how it already links to `depth-tiers.md`.
## Steps to Reproduce
1. See commit `f97a38c1539028af6bfacff9fbd4855dd4f6255b` (PR #2550) on `main`.
2. Compare `.github/skills/coding-standards/code-review/references/depth-tiers.md` and the new `references/change-risk-model.md` against `docs/agents/code-review/README.md`'s "Depth Tiers" section.
## Additional Context
* Changed source: `.github/skills/coding-standards/code-review/references/change-risk-model.md` (new), `references/depth-tiers.md`, `.github/instructions/coding-standards/code-review/review-artifacts.instructions.md`
* Stale documentation: `docs/agents/code-review/README.md`
> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/33339545285) · auto · 74.8 AIC · ⌖ 1.87 AIC · ⊞ 11.1K · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)
Contributor guide
Research direction
Start with docs/agents/code-review/README.md and its “Depth Tiers” section, then compare it with .github/skills/coding-standards/code-review/references/change-risk-model.md, references/depth-tiers.md, and review-artifacts.instructions.md. Update the README to cover the six evidence categories, three evidence states, advisory recommendations, human confirmation, and a link to change-risk-model.md. Done means the narrative guide matches the newer references and workflow description.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100