microsoft / microsoft/hve-core

docs: Documentation drift: code-review README doesn't reflect new change-risk evidence checklist

Open Beginner friendly
#2,803 1 comment 0 reactions 0 assignees View on GitHub
agent-ready documentation good first issue needs-triage
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.