amirbena / amirbena/code-review-skill
Document the finding-placement mental model in the Wiki
- Dominant language
- Python
- Stars
- 7
- Forks
- 2
- Avg merge
- 27m
- Merged PRs (30d)
- 188
Description
## Type
Documentation
## Area
Documentation
## Priority
P2 — Medium
## Problem
No Wiki page explains why a finding's location can differ from where its
evidence was found or where its symptom is visible. The existing
`docs/features/github-review-publication.md` explains publication modes
and #164's anchor-selection/fallback mechanics, but not the causal/
contract-ownership reasoning that determines the fix/action location in
the first place.
## Goal
Explain the implemented placement pipeline's mental model and lifecycle
to users/contributors, referencing the canonical policy rather than
duplicating it.
## Scope
- Explain the distinction: evidence location ≠ symptom location ≠ finding
location, and the shorthand "Evidence can move. The finding must not
drift with it."
- State the principles: causal ownership, contract ownership, no
mechanical caller/callee preference, locality preservation during
context expansion, semantic honesty over false precision, and that
GitHub-inline availability never redefines semantic ownership (the
existing fallback behavior from #164).
- Include short generic examples: cause vs. symptom (upstream state
creation vs. downstream unsafe handling), the precedent trap (a correct
sibling implementation is evidence, not the anchor), and the
nearest-line trap (a convenient but misleading precise line vs. a
truthful broader placement).
- Extend an existing relevant Wiki page (e.g. the page documenting review
output/publication, if one already covers `github-review-publication`)
if a coherent home exists; create a new page and connect it to Wiki
navigation only if none does.
- Link the canonical policy location rather than restating its contract.
## Non-Goals
- Any policy change — this consumes the final implementation contract.
- Copying the full canonical policy text into the Wiki.
- Restating #164's anchor-selection/fallback mechanics beyond a brief
cross-reference.
## Acceptance Criteria
- [ ] The evidence/symptom/finding-location distinction and its shorthand
are documented.
- [ ] Causal ownership, contract ownership, non-mechanical caller/callee
reasoning, and locality preservation during context expansion are
each explained.
- [ ] The examples are included and the canonical policy location is
referenced, not duplicated.
- [ ] Navigation is updated if a new page was created.
- [ ] Content reflects the implemented contract, not pre-implementation
speculation.
## Dependencies
Parent: #385
Depends on: #386 (implementation contract)
Relates: #384 (sibling Wiki issue for candidate-finding validation — same
conventions); `docs/features/github-review-publication.md` (existing
feature page for the adjacent publication/anchor mechanics).
## Validation
- Wiki content reviewed against the landed implementation.
- Links resolve; navigation/index updated if a new page was added.
Contributor guide
Assessment
This issue has not been assessed yet.