Tiered Prioritization

Debtmap uses a sophisticated tiered prioritization system to surface critical architectural issues above simple testing gaps. This chapter explains the tier strategy, how to interpret tier classifications, and how to customize tier thresholds for your project.

Overview

The tiered prioritization system organizes technical debt into four distinct tiers based on impact, urgency, and architectural significance. This prevents “walls of similar-scored items” and ensures critical issues don’t get lost among minor problems.

Two Tier Systems: Debtmap uses two complementary tier systems:

RecommendationTier (T1-T4): Used internally to classify items based on architectural significance and testing needs
Display Tier (Critical/High/Moderate/Low): Score-based tiers shown in terminal output, derived from final calculated scores

The configuration examples below control the RecommendationTier classification logic, which influences scoring through tier weights. The final display uses score-based tiers for consistency across all output formats.

The Four Tiers

Tier 1: Critical Architecture

Description: God Objects, God Modules, excessive complexity requiring immediate architectural attention

Priority: Must address before adding new features

Weight: 1.5x (highest priority multiplier)

Impact: High impact on maintainability and team velocity

Classification Criteria (src/priority/tiers.rs:183-216):

Debtmap uses sophisticated multi-factor analysis for Tier 1 classification, not just raw cyclomatic complexity. Items qualify for Tier 1 if they meet any of these criteria:

Critical Patterns: AsyncMisuse or ErrorSwallowing debt types (always Tier 1)
High Final Score: final_score > 10.0 after exponential scaling
Extreme Cyclomatic: Entropy-dampened cyclomatic complexity > 50
High Cognitive Load: Cognitive complexity >= 20
Deep Nesting: Nesting depth >= 5 levels
High Weighted Complexity: complexity_factor > 5.0 (weighted: 30% cyclomatic + 70% cognitive)

Examples:

Files with 15+ responsibilities (God Objects)
Modules with 50+ methods (God Modules)
ComplexityHotspot debt items meeting any of the criteria above
Functions with cognitive complexity >= 20 (extreme mental load)
Deeply nested code (5+ nesting levels)
Circular dependencies affecting core modules

When to Address: Immediately, before sprint work begins. These issues compound over time and block progress.

# Focus on Tier 1 items
debtmap analyze . --min-priority high --top 5

Tier 2: Complex Untested

Description: Untested code with high complexity or critical dependencies, plus moderate complexity hotspots not severe enough for Tier 1.

Priority: Risk of bugs in critical paths

Weight: 1.0x (standard multiplier)

Action: Should be tested before refactoring to prevent regressions

Classification Criteria (src/priority/tiers.rs:257-302):

Items qualify for Tier 2 through two distinct paths:

Path 1: Testing Gaps - Untested code meeting ANY of:

Cyclomatic complexity ≥ 15
Total dependencies ≥ 10
Entry point functions with any coverage gap

Path 2: Moderate Complexity Hotspots - ComplexityHotspot items with meaningful but non-extreme complexity, meeting ANY of:

Complexity factor >= 2.0 (weighted: 30% cyclomatic + 70% cognitive, scaled 0-10)
Cognitive complexity >= 12 (moderate to high mental load)
Nesting depth >= 3 (meaningful nested control flow)
Entropy-dampened cyclomatic complexity 8-50 (after filtering repetitive patterns)

Examples:

Functions with cyclomatic complexity ≥ 15 and 0% coverage
Functions with 10+ dependencies and low test coverage
Business logic entry points without tests
Complex error handling without validation
Moderate complexity hotspots (complexity_factor >= 2.0, cognitive >= 12, or nesting >= 3)

When to Address: Within current sprint. Add tests before making changes.

# See Tier 2 testing gaps
debtmap analyze . --lcov coverage.lcov --min-priority high

Tier 3: Testing Gaps

Description: Untested code with moderate complexity

Priority: Improve coverage to prevent future issues

Weight: 0.7x (reduced multiplier)

Action: Add tests opportunistically or during related changes

Examples:

Functions with cyclomatic complexity 10-15 and low coverage
Utility functions without edge case tests
Moderate complexity with partial coverage

When to Address: Next sprint or when touching related code.

Tier 4: Maintenance

Description: Low-complexity issues and code quality improvements

Priority: Address opportunistically during other work

Weight: 0.3x (lowest multiplier)

Action: Fix when convenient, low urgency

Examples:

Simple functions with minor code quality issues
TODO markers in well-tested code
Minor duplication in test code

When to Address: During cleanup sprints or when refactoring nearby code.

Configuration

Tier configuration is optional in .debtmap.toml. If not specified, Debtmap uses the balanced defaults shown below.

Default Tier Thresholds

[tiers]
# Tier 2 thresholds (Complex Untested)
t2_complexity_threshold = 15         # Cyclomatic complexity cutoff
t2_dependency_threshold = 10         # Dependency count cutoff

# Tier 3 thresholds (Testing Gaps)
t3_complexity_threshold = 10         # Lower complexity threshold

# Display options
show_t4_in_main_report = false      # Hide Tier 4 from main output (default: false)

# Tier weights (multipliers applied to base scores)
t1_weight = 1.5    # Critical architecture
t2_weight = 1.0    # Complex untested
t3_weight = 0.7    # Testing gaps
t4_weight = 0.3    # Maintenance

To use tier-based prioritization with custom settings, add the [tiers] section to your .debtmap.toml configuration file:

# Analyze with custom tier configuration
debtmap analyze . --config .debtmap.toml

Tier Preset Configurations

Debtmap provides three built-in tier presets for different project needs:

Balanced (Default)

[tiers]
t2_complexity_threshold = 15
t2_dependency_threshold = 10
t3_complexity_threshold = 10

Suitable for most projects. Balances detection sensitivity with manageable issue counts.

Strict

[tiers]
t2_complexity_threshold = 10
t2_dependency_threshold = 7
t3_complexity_threshold = 7

For high-quality codebases or teams with strict quality standards. Flags more items as requiring attention.

Lenient

[tiers]
t2_complexity_threshold = 20
t2_dependency_threshold = 15
t3_complexity_threshold = 15

For legacy codebases or gradual technical debt reduction. Focuses on the most critical issues first.

Programmatic Access: These presets are also available as methods when using Debtmap as a library:

TierConfig::balanced() - Equivalent to the balanced preset above
TierConfig::strict() - Equivalent to the strict preset above
TierConfig::lenient() - Equivalent to the lenient preset above

These methods can be used in Rust code to configure tier settings programmatically without manual TOML configuration.

Customizing Tier Thresholds

You can also create custom threshold configurations tailored to your project:

# Custom thresholds for specific project needs
[tiers]
t2_complexity_threshold = 12
t2_dependency_threshold = 8
t3_complexity_threshold = 8

Tier Weight Customization

Tier weights are multipliers applied to base debt scores during prioritization. A weight of 1.5 means items in that tier will score 50% higher than equivalent items in a tier with weight 1.0, pushing them higher in priority rankings.

Adjust weights based on your priorities:

# Emphasize testing over architecture
[tiers]
t1_weight = 1.2    # Reduce architecture weight
t2_weight = 1.3    # Increase testing weight
t3_weight = 0.8
t4_weight = 0.3

# Focus on architecture first
[tiers]
t1_weight = 2.0    # Maximize architecture weight
t2_weight = 1.0
t3_weight = 0.5
t4_weight = 0.2

Use Cases

Sprint Planning

Use tiered prioritization to allocate work:

# See Tier 1 items for architectural planning
debtmap analyze . --min-priority high --top 5

# See Tier 2/3 for testing sprint work
debtmap analyze . --lcov coverage.lcov --min-priority medium

Code Review Focus

Prioritize review attention based on tiers:

Tier 1: Architectural review required, senior dev attention
Tier 2: Test coverage validation critical
Tier 3: Standard review process
Tier 4: Quick review or automated checks

Refactoring Strategy

# Phase 1: Address Tier 1 architectural issues
debtmap analyze . --min-priority high

# Phase 2: Add tests for Tier 2 complex code
debtmap analyze . --lcov coverage.lcov --min-priority high

# Phase 3: Improve Tier 3 coverage
debtmap analyze . --lcov coverage.lcov --min-priority medium

Best Practices

Always address Tier 1 before feature work - Architectural issues compound
Test Tier 2 items before refactoring - Avoid regressions
Batch Tier 3 items - Address multiple in one sprint
Defer Tier 4 items - Only fix during cleanup or when convenient
Track tier distribution over time - Aim to reduce Tier 1/2 counts

Interpreting Tier Output

Terminal Output

Terminal output displays items grouped by score-based tiers:

TECHNICAL DEBT ANALYSIS - PRIORITY TIERS

Critical (score >= 90)
  src/services.rs - God Object (score: 127.5)
  src/core/engine.rs - Circular dependency (score: 95.2)

High (score 70-89.9)
  src/processing/transform.rs:145 - UntestableComplexity (score: 85.0)
  src/api/handlers.rs - God Module (score: 78.3)
  ...

Moderate (score 50-69.9)
  src/utils/parser.rs:220 - TestingGap (score: 62.1)
  ...

Low (score < 50)
  [Items with score < 50 appear here]

Note: The scores shown reflect tier weight multipliers applied during classification. Items classified as Tier 1 (Critical Architecture) receive a 1.5x weight boost, which often elevates them into the Critical or High score ranges.

JSON Output

JSON output uses the same score-based priority levels as terminal output:

{
  "summary": {
    "score_distribution": {
      "critical": 2,
      "high": 5,
      "moderate": 12,
      "low": 45
    }
  },
  "items": [
    {
      "type": "File",
      "score": 127.5,
      "priority": "critical",
      "location": {
        "file": "src/services.rs"
      },
      "debt_type": "GodObject"
    },
    {
      "type": "Function",
      "score": 85.0,
      "priority": "high",
      "location": {
        "file": "src/processing/transform.rs",
        "line": 145,
        "function": "process_data"
      },
      "debt_type": "UntestableComplexity"
    }
  ]
}

The priority field is derived from the score field using these thresholds:

critical: score >= 90.0
high: score >= 70.0
moderate: score >= 50.0
low: score < 50.0

Source: Priority tier thresholds defined in src/priority/mod.rs:478-484

Note: While RecommendationTier (T1-T4) classifications exist internally for applying tier weights, they are not included in JSON output. The output shows final calculated scores and their corresponding priority levels.

Troubleshooting

Issue: Too many Tier 1 items

Solution: Lower tier weights or increase thresholds temporarily:

[tiers]
t1_weight = 1.2    # Reduce from 1.5

Issue: Not enough items in Tier 1

Solution: Check if god object detection is enabled:

[god_object_detection]
enabled = true

Issue: All items in Tier 4

Solution: Lower minimum thresholds:

[thresholds]
minimum_debt_score = 1.0
minimum_cyclomatic_complexity = 2

Debtmap Documentation

Tiered Prioritization

Overview

The Four Tiers

Tier 1: Critical Architecture

Tier 2: Complex Untested

Tier 3: Testing Gaps

Tier 4: Maintenance

Configuration

Default Tier Thresholds

Tier Preset Configurations

Customizing Tier Thresholds

Tier Weight Customization

Use Cases

Sprint Planning

Code Review Focus

Refactoring Strategy

Best Practices

Interpreting Tier Output

Terminal Output

JSON Output

Troubleshooting

See Also

Keyboard shortcuts

Debtmap Documentation