Prismatic Annihilation

Abstract

Prismatic Annihilation is the platform's automated technical debt elimination engine, designed to identify, categorize, and automatically fix quality issues across all 90 OTP applications. The system implements O(1) pattern detection (achieving 90-250x speedup over naive scanning) for anti-patterns, dead code, missing type specifications, and coding standard violations. Five CASCADE pattern families drive the elimination process: Type Mismatch detection and correction, Dead Code discovery and removal, Empty Check optimization (length() > 0 to != []), Timer Replacement (Process.sleep to timer-based alternatives), and Nuclear Cache clearing for persistent build issues. The auto-fix engine performs safe code transformations with mandatory test verification, batch processing across the entire codebase, and rollback capability for failed transformations. The system operates in concert with Prismatic Safety, which detects quality degradation and triggers Annihilation's remediation cycles.

1. Introduction

1.1 Problem Statement

A codebase of 6,652 Elixir source files across 90 applications accumulates technical debt through diverse mechanisms: deprecated API usage, suboptimal patterns that were acceptable at introduction time, missing type specifications on functions added under time pressure, and dead code left behind by refactoring. Manual debt elimination does not scale. Periodic cleanup sprints address visible issues but miss systemic patterns that require AST-level analysis to detect.

Prismatic Annihilation automates the entire debt lifecycle: detection through AST analysis, categorization by severity and pattern type, automated fix generation, test verification, and rollback on failure.

1.2 Design Goals

1. O(1) pattern detection -- indexed AST analysis enables constant-time pattern matching regardless of codebase size.
2. Safe auto-fix -- every automated code transformation is verified by running the affected module's test suite before and after the change.
3. CASCADE patterns -- five pattern families that address the most impactful debt categories.
4. Batch processing -- fix entire categories of debt across all applications in a single operation.
5. Rollback safety -- failed transformations are automatically reverted, leaving the codebase unchanged.
6. Integration with Safety -- receives evolution triggers from Prismatic Safety for automatic remediation.

1.3 Scope

Prismatic Annihilation covers detection and automated fixing of technical debt patterns. It does not handle architectural debt, which requires human design decisions. The system operates on individual files and functions, not on inter-module dependency structures.

2. Architecture

2.1 System Design

Trigger (Safety evolution | Manual scan)
       |
  AST-Indexed Scanner
  (O(1) pattern detection)
       |
  +----+----+----+----+----+
  |    |    |    |    |    |
  Type  Dead  Empty  Timer  Nuclear
  Mismatch Code Check  Replace Cache
       |
  Debt Catalog (categorized findings)
       |
  Auto-Fix Engine
  (transform → test → commit | rollback)
       |
  Quality Score Update

2.2 Core Components

2.3 Process Topology

PrismaticAnnihilation.Application (Supervisor, :one_for_one)
+-- PrismaticAnnihilation.Scanner (GenServer)
|     Maintains AST index, performs scan operations
+-- PrismaticAnnihilation.AutoFix (GenServer)
|     Manages transformation pipeline with test verification
+-- Task.Supervisor
      Parallel file-level scanning and fixing

2.4 Data Flow

A scan operation (triggered by Safety or manually) causes the Scanner to traverse the AST index and identify pattern matches. Matches are categorized into CASCADE families and accumulated into a debt catalog. The AutoFix engine processes the catalog by priority, applying transformations to source files, running tests against affected modules, and committing successful fixes or rolling back failures. The quality score is recalculated after each fix batch.

3. Implementation

3.1 Key Algorithms

AST-Indexed Scanning. On initialization, the Scanner parses all Elixir source files into AST representations and builds an index mapping pattern signatures to file locations. This enables O(1) lookup when checking for specific patterns, compared to O(n) sequential file scanning. The index is updated incrementally when files change.

Safe Transformation. Each CASCADE pattern defines a detect/1 function that identifies instances and a fix/1 function that generates the corrected AST. The AutoFix engine applies the transformation, writes the modified source, runs mix test for the affected module, and evaluates the result. A successful test suite means the fix is kept; a failure triggers rollback.

3.2 Data Structures

defmodule PrismaticAnnihilation.DebtItem do
  @type t :: %__MODULE__{
    file: String.t(),
    line: pos_integer(),
    pattern: :type_mismatch | :dead_code | :empty_check | :timer_replace | :nuclear_cache,
    severity: :info | :warning | :error,
    description: String.t(),
    auto_fixable: boolean(),
    fix_function: (String.t() -> {:ok, String.t()} | {:error, term()}) | nil
  }
end

3.3 API Surface

# Scan for technical debt
@spec scan() :: {:ok, [DebtItem.t()]}
PrismaticAnnihilation.scan()

# Auto-fix detected issues with test verification
@spec fix([DebtItem.t()], keyword()) :: {:ok, fix_report()} | {:error, term()}
PrismaticAnnihilation.fix(debt_items, verify: true)

# Nuclear cache fix for persistent build issues
@spec nuclear_cache_fix() :: {:ok, :cleared}
PrismaticAnnihilation.nuclear_cache_fix()

# Scan and fix a specific CASCADE pattern
@spec cascade(atom()) :: {:ok, fix_report()}
PrismaticAnnihilation.cascade(:empty_check)

3.4 Configuration

config :prismatic_annihilation,
  cascade_patterns: [:type_mismatch, :dead_code, :empty_check, :timer_replace, :nuclear_cache],
  auto_fix_enabled: true,
  test_verification: true,
  rollback_on_failure: true,
  parallel_workers: 4,
  nuclear_cache_paths: ["_build/dev/lib/*/ebin", "priv/plts/dialyzer.plt"]

4. Integration

4.1 Dependencies

4.2 Dependents

4.3 Inter-Process Communication

Evolution triggers from Safety arrive as function calls to the Annihilation facade. Fix operations execute as supervised tasks for parallel processing. Test verification runs in isolated system processes.

4.4 External Integrations

Mix build system for test execution and compilation verification. Git for file change tracking and rollback support.

5. Performance

5.1 Benchmarks

5.2 Scalability

AST index construction is O(n) at initialization; subsequent pattern queries are O(1). Fix operations parallelize across files with configurable worker count.

5.3 Resource Requirements

6. Testing Strategy

6.1 Unit Tests

Each CASCADE pattern has tests with known-positive and known-negative samples. Auto-fix tests verify correct transformation output for each pattern type.

6.2 Integration Tests

End-to-end tests exercise the scan-fix-verify-rollback cycle on a test codebase with deliberately introduced debt patterns.

6.3 Property-Based Testing

StreamData generators produce random Elixir AST fragments to verify that pattern detection never crashes and that auto-fix transformations produce valid Elixir syntax.

7. Security Considerations

7.1 Threat Model

Automated code modification carries the risk of introducing bugs. The mandatory test verification step mitigates this risk. Rollback capability ensures that any failed transformation is reverted.

7.2 Access Control

Annihilation operations require system-level access. The auto-fix engine cannot be triggered remotely; it operates only through local mix tasks or Safety evolution triggers.

8. Operational Considerations

8.1 Deployment

Deploys as part of the umbrella release. The AST index is rebuilt on first scan after deployment.

8.2 Monitoring

Telemetry events: [:prismatic, :annihilation, :scan_complete], [:prismatic, :annihilation, :fix_applied], [:prismatic, :annihilation, :fix_rolled_back]. Key metrics include debt items found, items fixed, and rollback frequency.

8.3 Troubleshooting

9. Future Work

Planned enhancements include machine learning-based pattern discovery from historical debt data, cross-module refactoring for architectural debt, integration with GitLab CI for automated debt elimination in pipelines, and developer-facing debt dashboard with fix suggestions.

References

• Prismatic Safety -- Quality monitoring and evolution triggers
• Prismatic Credo -- Static analysis integration
• Prismatic Claude -- Session lifecycle for auto-evolution

Related Agents

• CI/CD Guardrails Enforcer -- Enforces quality gates in the CI/CD pipeline that trigger Annihilation scans and block merges with technical debt
• Evolution Analyzer Specialist -- Analyzes CASCADE pattern effectiveness and recommends new debt elimination strategies
• Deployment Commander Agent -- Coordinates deployment workflows that include pre-deployment debt scans and post-deployment quality verification

Related Capabilities

• Quality Gates -- Enforces zero-warning compilation, Credo compliance, and test coverage requirements that Annihilation maintains
• Regression Tests -- Mandatory regression test protocol ensuring every auto-fix is validated by test verification before commit
• Color Teams -- White Team verification validates that automated code transformations maintain system invariants

Connect & Contribute

Created by Tomáš Korcak (korczis) | Open Source under GHL

• GitHub | GitLab | LinkedIn | Contact
• Developer Portal | Architecture | Meet the Creator