Blocking vs Non-Blocking Issues

## Blocking vs Non-Blocking Issues

Not every issue should stop development.

SyntaxValid distinguishes between blocking and non-blocking issues to help teams move fast without ignoring real risk.

---

## What is a blocking issue?

A blocking issue represents unacceptable risk under the active policy.

Blocking issues:

- Indicate that a merge is unsafe

- Directly reduce TrustScore

- Require immediate action before proceeding

If a blocking issue exists, SyntaxValid considers the code not ready.

---

## What is a non-blocking issue?

Non-blocking issues provide visibility without stopping progress.

They:

- Highlight improvement opportunities

- Do not prevent merging

- Have limited or no immediate impact on TrustScore

Non-blocking issues support continuous improvement.

---

## How blocking decisions are made

Blocking status is not based on severity alone.

SyntaxValid uses policies to decide:

- Which categories matter

- Which severity levels block merges

- Which contexts increase risk

This ensures decisions match team risk tolerance.

---

## Examples

- A high-severity security vulnerability → blocking

- A medium-severity architectural violation → blocking (policy-dependent)

- A low-severity style issue → non-blocking

Policies control these outcomes.

---

## Why this distinction matters

Without blocking logic:

- Teams ignore long issue lists

- Critical risks get lost in noise

- Merge decisions become subjective

Blocking issues create a clear, enforceable signal.

---

## Blocking issues and TrustScore

Blocking issues have the strongest impact on TrustScore.

Resolving blocking issues:

- Immediately improves TrustScore

- Restores merge readiness

- Reduces overall risk

TrustScore reflects policy compliance.

---

## Using blocking effectively

### For developers

- Address blocking issues first

- Use Fix with AI for safe, focused changes

- Re-run analysis to confirm resolution

### For tech leads and CTOs

- Define policies that reflect real risk

- Avoid over-blocking low-impact issues

- Use blocking status to enforce standards consistently

---

## Avoiding over-blocking

Overly strict policies can slow teams down.

If too many issues are blocking:

- Review severity thresholds

- Reclassify low-impact rules

- Adjust policies gradually

Balanced policies improve adoption and trust.

---

## Next steps

- Fix with AI workflow

- Issue lifecycle

- Policies and rules