Alerts & Monitoring
Automated code quality notifications triggered by metric thresholds
What are Alerts?
Alerts are automated notifications that fire when a code metric exceeds a configured threshold. They help you catch complexity regressions early, before they become entrenched technical debt.
Every time Spec This scans your repository, it compares the resulting metrics against your configured thresholds. When a metric crosses a threshold, an alert is created with an appropriate severity level.
Tip: Alerts are designed to be actionable, not noisy. Start with the default Medium preset and tighten thresholds as your codebase improves.
Alert Types
Spec This monitors seven distinct alert types, each tied to a specific code quality metric.
| Alert Type | Metric | Tier |
|---|---|---|
| complexity | Cyclomatic / nesting depth | All |
| cognitive_complexity | Cognitive complexity score | All |
| high_coupling | Module dependency count | All |
| high_parameter_count | Function parameters | All |
| churn_hotspot | File change frequency | Pro only |
| file_size | File byte size | All |
| parse_error | Files that fail to parse | All |
Pro feature: The churn_hotspot alert type is exclusive to Pro plans. It identifies files that change frequently and have high complexity — the most impactful targets for refactoring. Compare plans
Severity Levels
Each alert is assigned a severity based on how far the metric exceeds its threshold.
Info
Metric value slightly exceeds threshold (100–120%). Worth monitoring but not urgent. These often resolve naturally as code is refactored.
Warning
Metric value moderately exceeds threshold (120–200%). Should be addressed during the next development cycle.
Critical
Metric value significantly exceeds threshold (200%+). Immediate attention recommended. These represent serious maintainability risks.
Preset Threshold Levels
Spec This provides three preset levels to get you started quickly. Choose the one that best matches your codebase maturity.
| Metric | Low (Lenient) | Medium (Default) | High (Strict) |
|---|---|---|---|
| Nesting Depth | 8 | 5 | 3 |
| Branch Count | 25 | 15 | 10 |
| Logical LOC | 300 | 200 | 150 |
| Cognitive Complexity | 50 | 25 | 15 |
| Parameter Count | 8 | 5 | 3 |
| File Line Count | 800 | 500 | 300 |
| File Size | 200 KB | 100 KB | 50 KB |
| Parse Failure Rate | 10% | 5% | 2% |
Custom Thresholds
Presets are a starting point. You can override any threshold at two levels:
Organization-Level Thresholds
Set default thresholds that apply to every repository in your organization. Configure these in your Organization Settings under the Alerts tab.
// Example: Organization-level custom config
{
"preset": "medium",
"overrides": {
"nestingDepth": 4,
"cognitiveComplexity": 20
}
}User-Level Thresholds
Individual users can override organization defaults for their own view. This is useful for personal quality targets or when working on particularly critical sections of the codebase.
Alert Lifecycle
Alerts follow a simple lifecycle that tracks resolution progress automatically.
Active
A scan detects that a metric exceeds its configured threshold. The alert is created with the appropriate severity and appears on your dashboard.
Resolved (automatic)
On the next scan, if the metric has improved and no longer exceeds the threshold, the alert is automatically marked as resolved. No manual action needed.
Dismissed (manual)
If you determine an alert is not actionable (e.g., intentional complexity in a parser function), you can manually dismiss it. Dismissed alerts do not reappear for the same file and metric.
Dashboard Integration
Alerts feed directly into your repository dashboard, providing at-a-glance health visibility.
Severity Counts
The dashboard displays a breakdown of active alerts by severity (info, warning, critical), giving you a quick sense of the codebase state.
Health Score Impact
Active alerts reduce your repository health score. Critical alerts have the highest impact, while info-level alerts have minimal effect. Learn about health scores