Revieko PR Review — Quickstart (3–5 minutes)

This guide explains how to quickly read a Revieko PR comment and choose the right next action: accept, request changes, simplify, isolate the change, or dive into the full report.

1) What a Revieko report is

Revieko is a review radar: it highlights places where a PR changes the project’s structure/behavior in a way that deviates from the repository’s usual “shape”.

The report provides three independent signal layers:

Structure — code shape (branching, nesting depth, pattern breaks, structural tails).
Semantic (effects/taint) — where side effects appear in the diff (NET_IO / DB / FILE_IO / EXEC / LOG) and which sources are nearby (USER_INPUT / SECRET / …).
Control — execution-path regimes (conditions, error branches, return tails, init/cleanup).

Important: this is not SAST and not a bug finder. CodeGuard doesn’t “prove” there is a bug — it helps you focus reviewer attention.

2) Two output levels: PR comment vs Full report

In GitHub, you typically see:

2.1 PR comment (short)

Includes:

overall status (Status, risk_level, ci_status, analysis full/partial),
struct_risk,
top-N hotspots (ranked by priority),
per-file structural risk,
links to the Full report (Markdown / JSON).

2.2 Full report (via link)

Use it when:

the PR is large and you need “the whole picture”,
you want details (effects/taint/control/invariants),
analysis=partial and you need to understand what was skipped,
you need an artifact-style workflow (Markdown next to the diff, or JSON for automation).

Top-N hotspots in the PR comment are an output limit, not a limit of understanding. They are the highest-priority areas so the comment doesn’t turn into a wall of text.

3) How to read the PR comment in 3–5 minutes (strict order)

Step 1. 15 seconds: scan the global signal

Look at these 4 fields first:

risk_level (low | medium | high)
struct_risk (0–100)
ci_status (ok | warn | fail)
analysis (full | partial)

Quick rule:

risk_level=high → almost always go straight to hotspots and the main file.
analysis=full → all code CodeGuard can analyze in this repo (currently: Python) was processed.
analysis=partial → the PR includes files outside the analysis profile (e.g., YAML/CSV/Markdown). CodeGuard did not analyze those files. The Python part of the PR is still fully analyzed.

Step 2. 30 seconds: identify the “main file”

Open Per-file structural risk and answer:

Which file contributes the largest share of risk?
Is risk concentrated in one file or spread out?

If one file dominates, review becomes faster: start there.

Step 3. 2 minutes: top-3 / top-5 hotspots

Open Top hotspots and go through the first 3–5 entries.

For each hotspot, answer:

What is this place? (lines, diff context)
Why might it be atypical? (kind)
How urgent is it? (score = review priority)

If Effects / Taint / Control columns are populated — start there. These are usually more “practical” risks than pure code shape.

Step 4. 30 seconds: pick an action

After reviewing a few hotspots, choose one path:

✅ Accept (and add context if needed)
🔧 Simplify (reduce complexity / “architectural mass”)
📦 Isolate (move a new subsystem/algorithm into a dedicated module/layer)
🧪 Add tests / invariants (if behavior, regimes, math, or contracts change)
🔎 Open Full report (strong signal but unclear context / analysis=partial)

4) How to interpret the key fields (only what matters)

4.1 `risk_level` and `struct_risk`

struct_risk is 0–100: how much the structure deviates from the repo baseline.
risk_level is a discrete shortcut for decision-making.

How to read:

low → usually just ensure hotspots don’t hide bad effects/taint.
medium → almost always review top-3 hotspots.
high → review the main file + top hotspots, then decide: simplify/isolate/justify.

4.2 `ci_status`

A CI/dashboard signal:

ok → no threshold-breaking situations detected.
warn → “must inspect manually”.
fail → in strict CI mode this may block merging (depends on project policy).

4.3 `analysis: full | partial`

full → CodeGuard analyzed all supported code in the PR (currently: Python).
partial → the PR includes changes in files CodeGuard doesn’t analyze (non-code / unsupported extensions). The report is “partial” not because Python analysis is incomplete, but because part of the PR lies outside the analysis scope.

Review rule:

For Python, use hotspots and per-file risk.
For out-of-profile files, review the diff normally (project checklist), without expecting CodeGuard signals.

4.4 Hotspot: `kind` and `score`

kind = anomaly type (what is “unlike the norm”).
score = review priority (what to inspect first), not “bug probability”.

Typical kind (intuitive):

struct_pattern_break — atypical structural pattern (often new entities/patterns/style).
depth_spike — nesting/conditional depth grew too much.
control_outlier — execution paths overheated (conditions/errors/return tails).
mixed — combination of factors.

5) “What to do next” decision matrix (short)

Scenario A: `risk_level=low`, `ci_status=ok`, `analysis=full`

Usually:

skim top hotspots (1–3),
check for effect tails / taint,
accept the PR.

Scenario B: `risk_level=medium` or `ci_status=warn`

Usually:

review top-3 / top-5 hotspots,
if changes are mostly stylistic/structural → propose simplification,
if changes are algorithmic → require explanation + tests.

Scenario C: `risk_level=high`

Minimum:

open the main file from Per-file structural risk,
walk through top hotspots,
choose Simplify or Isolate (most common),
or Accept + explain if the change is intentional and covered.

Scenario D: `analysis=partial`

Usually means the PR contains files outside the analysis scope (e.g., YAML/CSV/Markdown).

What to do:

Review the Python part via CodeGuard (per-file risk → top hotspots).
Review out-of-profile files (configs/data/docs) manually using project standards.

6) What to write in the PR discussion (short templates)

6.1 Accept + explain (intentional change)

“CodeGuard flagged an atypical complexity increase in <area>. This is intentional to achieve <goal>. Tests <...> were added/updated, and the contract is documented in <...>.”

6.2 Simplify (reduce cognitive load)

“This introduces a structural pattern break relative to the repo style. Please rewrite as <simpler function / no lambda / no generator> to keep the code predictable.”

6.3 Isolate (new subsystem/pattern/algorithm)

“This looks like a new mini-architecture/algorithm. Let’s extract it into a separate module/class with an explicit interface and a short doc, so the change stays localized.”

6.4 Add tests / invariants (behavior changes)

“This change affects runtime behavior / math / contract. We need tests for <invariant / edge cases / stability> or an explicit configuration flag.”

7) Mini example: how to read a “High risk” PR in 60 seconds

If you see:

Status: High risk
struct_risk: 69.49
control_risk_level: low
hotspots: many struct_pattern_break

Interpretation:

the signal is not about branching/errors; it’s about introducing atypical structural patterns;
start with top-3 hotspots and decide: “Is this a new architectural idea (then isolate/justify) or accidental complexity (then simplify)?”

8) When Quickstart is not enough

Open the Full report if:

the PR is large and you need the full per-file picture,
there are Effects/Taint/Control signals and you need to assess safety/boundaries/contracts,
analysis=partial,
changes look like a new subsystem or a new operating mode.

9) Links to next documents

REPORT_FIELDS_REFERENCE — full reference for all report fields.
REVIEW_PLAYBOOKS — playbooks (high struct, high control, effects/taint, partial).
CASE_STUDIES — real PR breakdowns (decision-making by examples).

Revieko Wiki