Issues & Severities

## Issues & Severities

SyntaxValid reports findings as issues with clearly defined categories and severity levels.

This page explains how issues are classified, how severity is determined, and which issues block safe progress.

---

## What is an issue?

An issue represents a detected risk, violation, or unsafe pattern in the codebase.

Each issue includes:

- Category

- Severity

- Blocking or non-blocking status

- Clear explanation

- Fix guidance

Issues are designed to be actionable, not noisy.

---

## Issue categories

SyntaxValid groups issues into categories to help teams prioritize effectively.

### Security

Issues that may lead to vulnerabilities, data exposure, or unsafe execution paths.

### Code Quality

Maintainability problems, complexity risks, and patterns that increase long-term cost.

### Architecture

Violations of architectural boundaries, layering rules, or dependency constraints.

### AI-Generated Code Risk

Findings related to AI-assisted or AI-generated code that increase uncertainty or fragility.

### Supply Chain

Dependency risks, outdated packages, and known vulnerability signals.

---

## Severity levels

Each issue is assigned a severity based on potential impact and likelihood.

### Critical

Immediate risk. Must be addressed before merging or releasing.

### High

Significant risk. Strongly recommended to fix before proceeding.

### Medium

Moderate risk. Should be planned and addressed soon.

### Low

Minor issue. Informational or stylistic impact.

Severity reflects risk, not effort.

---

## Blocking vs non-blocking issues

Not all issues affect merge readiness.

### Blocking issues

Blocking issues indicate unacceptable risk.

They:

- Prevent safe merging

- Directly reduce TrustScore

- Require immediate action

Blocking status is determined by policy, not severity alone.

---

### Non-blocking issues

Non-blocking issues:

- Do not prevent progress

- Provide visibility and guidance

- Can be resolved incrementally

They help teams improve without slowing delivery.

---

## How severity and blocking interact

Severity and blocking are related but not identical.

Examples:

- A high-severity security issue may be blocking

- A medium-severity architecture issue may be blocking if policy requires it

- A low-severity issue is typically non-blocking

Policies define these thresholds.

---

## How to work with issues effectively

### For developers

- Fix blocking issues first

- Review high-severity findings carefully

- Use Fix with AI for safe, scoped patches

### For tech leads and CTOs

- Monitor issue trends over time

- Adjust policies to match risk tolerance

- Use blocking issues to enforce standards consistently

---

## Reducing noise

SyntaxValid is designed to minimize false positives.

If an issue appears incorrect:

- Review its explanation

- Check related policy rules

- Adjust severity or policy thresholds if appropriate

Noise reduction improves long-term TrustScore reliability.

---

## Next steps

- Blocking vs non-blocking issues

- Fix with AI workflow

- Issue lifecycle