advanced-code-review-report

Phase 5: Report Generation

Invariant Principles

1. Signal over noise: Only verified findings appear in the final report. REFUTED findings are excluded. Quality of findings matters more than quantity.
2. Actionable output: Every finding must have clear next steps. Findings without suggestions or context are not actionable.
3. Machine-readable artifacts for automation: JSON summary enables CI/CD integration, automated triage, and tooling. Human-readable Markdown is not sufficient alone.

Purpose: Produce final deliverables including Markdown report and machine-readable JSON summary.

5.1 Finding Filtering

Filter to verified and inconclusive findings only:

def filter_findings_for_report(findings: list[dict]) -> list[dict]:
    """Filter out REFUTED findings for final report."""
    return [
        f for f in findings
        if f.get("verification_status") != "REFUTED"
    ]

5.2 Severity Sorting

Sort findings by severity (most critical first):

SEVERITY_ORDER = {
    "CRITICAL": 0,
    "HIGH": 1,
    "MEDIUM": 2,
    "LOW": 3,
    "NIT": 4,
    "QUESTION": 5,
    "PRAISE": 6
}
# QUESTION is a legal severity and MUST be present. Omitting it routes every
# QUESTION finding through the .get(..., 99) fallback, where it sorts last and
# disappears from by_severity. This dict must match the one in the
# advanced-code-review skill key for key.

def sort_by_severity(findings: list[dict]) -> list[dict]:
    """Sort findings by severity, most critical first."""
    return sorted(findings, key=lambda f: SEVERITY_ORDER.get(f["severity"], 99))

5.3 Verdict Determination

Determine overall review verdict:

BLOCKING = {"CRITICAL", "HIGH"}
DISCUSS = {"MEDIUM"}
NON_BLOCKING = {"LOW", "NIT", "QUESTION", "PRAISE"}
KNOWN_SEVERITIES = BLOCKING | DISCUSS | NON_BLOCKING


def determine_verdict(findings: list[dict]) -> str:
    """
    Determine review verdict based on findings.

    This is a MERGE GATE, so it FAILS CLOSED. Two ways it used to fail open:
    exact-uppercase membership testing (a finding emitted as `Critical` matched
    nothing and fell through to APPROVE), and treating an UNRECOGNISED severity
    as non-blocking. Both let a blocking finding merge under
    "No blocking issues found."

    Returns: "APPROVE" | "REQUEST_CHANGES" | "COMMENT"
    """
    severities = {
        str(f.get("severity", "")).strip().upper()
        for f in findings
        if f.get("verification_status") != "REFUTED"
    }

    # An unrecognised severity is NOT evidence of harmlessness. It means a
    # producer is speaking a vocabulary this gate does not know, so the gate
    # cannot rank it -- block and make a human look.
    unknown = severities - KNOWN_SEVERITIES - {""}
    if unknown:
        return "REQUEST_CHANGES"

    if severities & BLOCKING:
        return "REQUEST_CHANGES"

    if severities & DISCUSS:
        return "COMMENT"

    return "APPROVE"

def verdict_rationale(verdict: str, findings: list[dict]) -> str:
    """Generate rationale for verdict."""
    by_severity = {}
    for f in findings:
        # Normalise the same way determine_verdict does. Counting raw strings
        # here would report "0 blocking issue(s)" alongside REQUEST_CHANGES.
        sev = str(f.get("severity", "")).strip().upper()
        by_severity[sev] = by_severity.get(sev, 0) + 1

    unknown = sorted(set(by_severity) - KNOWN_SEVERITIES - {""})

    if verdict == "REQUEST_CHANGES":
        if unknown:
            return (
                f"unrecognised severity value(s) {unknown} -- the gate cannot "
                "rank them and blocks rather than assuming they are harmless"
            )
        critical = by_severity.get("CRITICAL", 0)
        high = by_severity.get("HIGH", 0)
        return f"{critical + high} blocking issue(s) require attention"
    elif verdict == "COMMENT":
        medium = by_severity.get("MEDIUM", 0)
        return f"{medium} medium-severity issue(s) worth discussing"
    else:
        return "No blocking issues found"