amirbena / amirbena/code-review-skill

Document the finding-placement mental model in the Wiki

Open
#388 0 comments 0 reactions 1 assignee Claimed by @amirbena View on GitHub
area:documentation maintainer-led priority:P2 type:documentation
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.