gh-bbrowning-bbrowning-claude-marketplace-bbrowning-claude/skills/pr-review/reference/severity-guide.md

Severity Classification Guide

Use this guide to consistently categorize findings during PR reviews. Each finding should be classified by severity to help prioritize fixes.

Severity Levels

Critical

Definition: Issues that MUST be fixed before merge. These pose immediate risks or cause serious problems.

When to use:

• Security vulnerabilities (SQL injection, XSS, exposed secrets)
• Data loss or corruption risks
• Breaking changes to public APIs without proper deprecation
• Code that will crash in production
• Severe performance issues (timeouts, memory leaks)
• Introduces legal/compliance violations

Examples:

• Hardcoded API key in source code
• SQL query vulnerable to injection
• Deleting data without transaction protection
• Breaking change to widely-used API
• Memory leak that grows unbounded
• Removing authentication check
• GitHub Actions workflow using pull_request_target + checkout of untrusted code + id-token: write
• CI/CD workflow that exposes secrets or OIDC tokens to untrusted code

Characteristics:

• Blocks merge
• Requires immediate fix
• Has production impact
• No workarounds available

High

Definition: Significant issues that should be fixed before merge. These cause problems but may have temporary workarounds.

When to use:

• Logic bugs that affect core functionality
• Missing error handling for likely errors
• Incomplete implementations
• Missing critical tests
• Performance issues that impact user experience
• Incorrect algorithm or approach

Examples:

• Function returns wrong result for valid input
• No error handling for network call
• Feature incomplete (half-implemented)
• No tests for new API endpoint
• O(n²) algorithm where O(n) is possible
• Race condition in concurrent code

Characteristics:

• Should block merge
• Affects functionality
• May have workarounds
• Needs addressing before release

Medium

Definition: Issues that should be addressed but don't block merge. These affect code quality, maintainability, or minor functionality.

When to use:

• Code quality issues
• Missing edge case handling
• Suboptimal implementations
• Insufficient test coverage
• Documentation gaps
• Minor design issues

Examples:

• Function is too complex and hard to read
• Doesn't handle empty array case
• Using map where set would be better
• No tests for error paths
• Missing docstring for public function
• Repeated code that should be extracted

Characteristics:

• Doesn't block merge
• Affects maintainability
• Should be addressed soon
• Follow-up PR acceptable

Low

Definition: Suggestions and minor improvements. Nice to have but not required.

When to use:

• Style preferences
• Minor optimizations
• Suggestions for future improvements
• Naming suggestions
• Comment improvements
• Non-critical refactoring ideas

Examples:

• Variable could have more descriptive name
• Could use newer language feature
• Comment could be more detailed
• Alternative approach suggestion
• Formatting inconsistency
• Typo in comment

Characteristics:

• Doesn't block merge
• Optional improvements
• Personal preference
• Future enhancement ideas

Classification Decision Tree

Use this flowchart to determine severity:

Does this create a security risk or data loss?
├─ YES → Critical
└─ NO ↓

Does this cause incorrect behavior or crashes?
├─ YES → High
└─ NO ↓

Does this impact code quality or maintainability significantly?
├─ YES → Medium
└─ NO ↓

Is this a suggestion or minor improvement?
└─ YES → Low

Context Matters

The same issue can have different severities based on context:

Example: Missing Error Handling

Critical: Payment processing endpoint

• Could lose money or charge incorrectly
• No recovery mechanism

High: User data fetch

• Core functionality broken
• Error affects user experience

Medium: Analytics tracking

• Non-critical feature
• Failure is acceptable

Low: Debug logging

• Optional feature
• No impact on users

Example: Performance Issue

Critical: Database query on high-traffic endpoint

• Causes timeouts under load
• Affects all users

High: Slow algorithm in user-facing feature

• Noticeable delay (>1s)
• Frequent operation

Medium: Inefficient background job

• Runs occasionally
• Has time budget

Low: Inefficiency in dev tooling

• Rarely executed
• Minimal impact

Borderline Cases

When a finding could fit multiple categories:

Between Critical and High

Ask: Will this definitely cause production issues?

• Definitely → Critical
• Probably → High

Between High and Medium

Ask: Does this affect core functionality?

• Yes → High
• No → Medium

Between Medium and Low

Ask: Does this impact maintainability significantly?

• Yes → Medium
• No → Low

Special Considerations

Breaking Changes

• With migration path + deprecation → High
• Without migration path → Critical

Test Issues

• No tests for new API → High
• Incomplete test coverage → Medium
• Test quality issues → Low

Documentation

• Missing docs for public API → Medium
• Incomplete docs → Low
• Typos in docs → Low

Dependencies

• Vulnerable dependency → Critical
• Unnecessary dependency → Medium
• Outdated but safe dependency → Low

Communicating Severity

Critical

• Start with "CRITICAL:" or use strong language
• Explain the immediate risk
• Mark as blocking

Example:

CRITICAL: This SQL query is vulnerable to injection. An attacker could access all user data. Must use parameterized queries.

High

• Clearly state it should block merge
• Explain the problem and impact
• Suggest fix

Example:

This function will crash when users.length is 0 (see line 42). This should be fixed before merge. Suggest adding a length check or using optional chaining.

Medium

• Explain why it matters
• Can be more conversational
• OK to suggest follow-up

Example:

This function is quite complex and hard to follow. Consider extracting the validation logic into a separate function. Could be addressed in a follow-up PR if needed.

Low

• Use softer language ("consider", "might", "could")
• Make it clear it's optional
• Can combine multiple low items

Example:

Minor: Consider renaming data to userData for clarity. Also, the comment on line 15 has a typo.

Repository-Specific Severity Adjustments

Some repositories may have custom severity criteria. Add repository-specific rules below:

High-Security Projects

• Elevate any security issue to Critical
• Stricter criteria for code quality

Fast-Moving Startups

• May accept more Medium issues
• Focus on Critical/High

Library/Framework Projects

• Breaking changes are always Critical
• Backward compatibility very important
• Documentation gaps elevated

Internal Tools

• Can be more lenient overall
• Security still Critical
• User experience less critical

Review Your Classifications

Before finalizing, check:

• Each finding has appropriate severity
• Critical items are truly blocking
• Low items are clearly optional
• Severity is justified in the comment
• Context is considered

Remember: The goal is to help prioritize fixes, not to be overly critical. When in doubt, err on the side of being helpful rather than strict.