Skip to main content

​
Walkthrough anatomy

The walkthrough is the top-level review comment Qodex posts on a pull request. It helps the author understand what changed, what Qodex checked, which findings were raised, and whether any findings could not be attached inline.

​
What the walkthrough contains

The walkthrough is posted as a GitHub review comment. It usually contains four parts:
  • A header summary.
  • An optional “Findings outside the diff” section.
  • A collapsible “What Qodex checked” block.
  • A footer with model, timing, and filtering details.
Inline findings are attached to the same GitHub review, but they render next to the changed code instead of inside the walkthrough body.

​
Header summary

The header gives a short behavior-level summary of the PR. It explains what Qodex thinks the diff changes, then shows an effort score and finding counts grouped by severity. 
## Qodex review

This PR adds a profile endpoint and a settings page. The endpoint
reads the user ID from the path, fetches the row, and returns it.
The page calls the endpoint on mount and renders a settings form.

Effort: 3/5 - 2 findings: 1 critical, 1 minor
When Qodex finds nothing worth raising, the walkthrough says the diff reads clean. An empty findings list is a valid review outcome. On non-trivial diffs, Qodex may take one deeper look before it accepts a clean result. If that zero-finding escalation pass runs, the walkthrough’s checklist calls it out so the author can see that Qodex specifically rechecked for subtle consistency, contract, and missing-predicate issues.

​
Findings outside the diff

GitHub only accepts inline review comments on lines that are part of the PR diff. If Qodex finds something related but the cited line is outside the diff, the finding appears in the walkthrough instead. 
### Findings outside the diff

_These findings reference files or lines that aren't part of the PR
diff. They couldn't be posted as inline comments. Treat them as
advisory._

- Critical - `src/auth.ts:142` - _security_ - Missing auth check on profile read
  The endpoint fetches by user ID from the URL but never compares it
  to the session user. Any logged-in user can read any other user's
  profile.
This keeps useful context visible without pretending GitHub accepted it as an inline finding.

​
”What Qodex checked” block

The walkthrough includes a collapsible <details> block that shows what Qodex actually ran. Checked boxes mean a step ran. Empty boxes mean the step was skipped, usually with a reason. The block covers four areas:
  1. Lenses: bugs, security, performance, maintainability, and style.
  2. Quality filters: the confidence floor, severity threshold, and path excludes.
  3. Verification probes: whether a preview deployment was found and whether probes ran.
  4. Output: whether the walkthrough and inline comments were posted.
<details>
<summary>What Qodex checked</summary>

**Lenses (single LLM pass, all dimensions)**

- [x] Bugs and correctness
- [x] Security (auth, injection, SSRF, secrets, headers)
- [x] Performance regressions
- [x] Maintainability
- [x] Style and consistency

**Quality filters**

- [x] Confidence floor at 0.7 (dropped 3 below)
- [x] Severity threshold from `.qodex.yaml`: `minor`
- [ ] Path excludes (none configured in `.qodex.yaml`)

**Verification probes against PR preview**

- [x] Preview deployment discovered: `pr-42.preview.acme.app`
- [x] Probes executed on 1 finding: 1 verified

**Output**

- [x] Walkthrough comment posted
- [x] 1 inline comment on specific lines

</details>
The footer shows the model, elapsed time, and a truncation note when the diff was capped at 200 KB. 
---
Reviewed by Qodex - gpt-5.4-mini - 8.4s - diff truncated at 200KB

_Findings shown are above the high-precision confidence threshold (>= 0.7).
Mark a finding resolved or flag a false positive in the Qodex Pull
Requests view._

​
A complete sample

## Qodex review

This PR replaces the manual cookie parser with a library call and
moves the session loader from middleware to a route handler. The
behavior should be identical; the change is mostly mechanical.

**Effort:** 2/5 - **1 finding: 1 major**

_1 inline comment attached to specific lines below._

<details>
<summary>What Qodex checked</summary>

**Lenses (single LLM pass, all dimensions)**

- [x] Bugs and correctness
- [x] Security (auth, injection, SSRF, secrets, headers)
- [x] Performance regressions
- [x] Maintainability
- [x] Style and consistency

**Quality filters**

- [x] Confidence floor at 0.7
- [x] Severity threshold from `.qodex.yaml`: `minor`
- [ ] Path excludes (none configured in `.qodex.yaml`)

**Verification probes against PR preview**

- [ ] Preview deployment discovered (no successful deploy for this commit)
- [ ] Probes (skipped, no preview to probe)

**Output**

- [x] Walkthrough comment posted
- [x] 1 inline comment on specific lines

</details>

---
Reviewed by Qodex - gpt-5.4-mini - 6.1s

_Findings shown are above the high-precision confidence threshold (>= 0.7).
Mark a finding resolved or flag a false positive in the Qodex Pull
Requests view._

​
When the walkthrough updates

Each review run posts a fresh review and walkthrough comment. The Check Run on the same head SHA updates in place, so the PR checks panel does not stack duplicate checks.

​
On the roadmap

A resolution affordance is on the roadmap. When a reviewer comments @qodex resolve <finding-id> or @qodex false-positive <finding-id> on an inline finding, Qodex will record the signal and train the per-project filter so the same noise stops recurring on future PRs.

Inline findings

Verification probes

Check Run and merge gating

.qodex.yaml reference