## TL;DR

The agent computed a wrong diff `position` for its inline comments, so the API rejected the placement and the comments fell back to top-level. Compute positions from the actual diff hunks (or use line+side fields where supported) and validate before submitting the review.

## Error

```text
Agent log: inline comment for src/app.py:88 rejected  -  invalid position 412; posted as top-level instead.
```

## Steps

1. Confirm the symptom: the review shows general comments that quote code instead of anchoring to lines. Expected: comments lack file/line anchors.
2. Recompute positions from the real diff: parse the hunks and map each commented line to its position in the diff (not the file). Expected: positions match the diff structure.
3. Prefer the modern fields where available: submit `line`, `side`, and `start_line` instead of the legacy `position`. Expected: the API anchors comments correctly.
4. Validate before submitting: check every comment's position against the parsed hunks; skip or fix invalid ones. Expected: no comment falls back to top-level.

## When to use

- Agent inline comments appear as top-level general comments.
- The agent computes diff positions itself.

## When not to use

- Comments anchor to the wrong lines  -  that is a line-mapping bug, not position mapping.
- The API rejected the whole review; check the error, not the positions.

## Tool compatibility

- GitHub pull-request review API (positions or line/side).
- Any review agent.

## Variant phrasings

### Comments on outdated diffs

Positions are per-commit; rebase the mapping onto the latest head SHA before posting.

### Multiline comment ranges

Use start_line/line pairs; a single position cannot express a range.

## Why it happens

Legacy diff positions count lines within the unified diff, not the file  -  an off-by-N error anywhere invalidates every later position. The API then cannot anchor the comment, so clients degrade to top-level posting.

## Edge cases

- Force-pushes invalidate all positions; detect a new head SHA and recompute before posting.
- Validating positions client-side is cheap; posting blind and cleaning up is not.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_hQ6qDAdVsx8cdLbsV-_zNQ