/scan-mycelium

Documentation L2+ Production low usage

/scan-mycelium

Overview

/scan-mycelium is a production command in the Documentation category of the Prismatic Platform. It performs comprehensive pattern scanning across both documentation and source code, identifying recurring structures, anti-patterns, improvement opportunities, and cross-cutting concerns that the mycelial network can propagate. The scanner bridges the gap between code patterns and their documentation, ensuring that improvements discovered in one domain are visible to and actionable by the propagation system.

This command operates under the L2+ authority level and is executed by the mycelium-scanner agent. It is part of the platform's 216-command slash command registry, built on the AIAD (Autonomous Intelligence Agent Design) standard. The mycelium-scanner agent has read access to the entire codebase and documentation corpus, enabling it to identify patterns that span multiple applications and documentation sections.

The scanning process is the discovery phase of the mycelial lifecycle. Before patterns can be propagated (via /mycelialize), evolved (via /mycelialize-living), or verified (via /mycelialize-formal), they must first be identified and catalogued. /scan-mycelium serves this critical role, feeding the mycelial network with fresh pattern discoveries.

The biological metaphor behind the mycelial network is deliberate: just as fungal mycelium networks discover and transport nutrients through soil ecosystems, the platform's mycelial scanning discovers valuable patterns and routes them to the systems that can propagate and apply them. The scanner is the sensory apparatus of this network -- constantly probing the codebase for new patterns, changed patterns, and degraded patterns that require attention.

Syntax and Usage

/scan-mycelium [options]

The command supports multiple scan modes, focus areas, and output formats.

# Full scan across code and documentation
/scan-mycelium

# Scan code patterns only
/scan-mycelium --mode code

# Scan documentation patterns only
/scan-mycelium --mode docs

# Scan for anti-patterns specifically
/scan-mycelium --focus anti-patterns

# Scan specific application
/scan-mycelium --app prismatic_web

# Scan with verbose pattern details
/scan-mycelium --verbose

# Output as JSON for pipeline integration
/scan-mycelium --format json

# Scan recently changed files only
/scan-mycelium --since 7d

# Export discovered patterns
/scan-mycelium --export ./patterns/

# Dry run showing scan plan
/scan-mycelium --dry-run

# Find patterns suitable for propagation
/scan-mycelium --propagation-candidates --export ./candidates/

# Full documentation consistency scan
/scan-mycelium --mode docs --cross-reference --verbose

Parameters and Options

OptionTypeDefaultDescription
--modeenumallScan mode: code, docs, cross, all
--focusenumallFocus area: patterns, anti-patterns, improvements, consistency, all
--appstringallSpecific application to scan
--sincedurationallScan only files modified within period
--formatenumtextOutput format: text, json, markdown
--verboseflagfalseDetailed pattern descriptions and examples
--exportpathnoneExport patterns to directory
--dry-runflagfalseShow scan plan without executing
--min-confidencefloat0.5Minimum confidence for reported patterns
--max-resultsinteger100Maximum patterns to report
--cross-referenceflagfalseEnable code-documentation cross-referencing
--propagation-candidatesflagfalseFilter to patterns suitable for propagation
--parallelinteger4Number of parallel scan workers
--custom-patternspathnoneLoad custom pattern definitions from file
--incrementalflagfalseScan only changes since last scan
--trend-analysisflagfalseAnalyze pattern frequency trends over time

Implementation Architecture

The scanner operates as a multi-pass analysis system that examines code and documentation through different analytical lenses.

             /scan-mycelium
                    |
           Scan Orchestrator
                    |
          +--------+--------+
          |        |        |
       Code      Doc      Cross
       Scanner   Scanner   Scanner
          |        |        |
    +-----+---+ +--+--+ +--+--+
    |     |   | |  |  | |  |  |
   AST  Regex Doc  MD  Code Doc
   Scan  Scan Parse Scan Link Link
    |     |   | |  |  | |  |  |
    +-----+---+-+--+--+-+--+--+
                    |
           Pattern Classifier
                    |
          +--------+--------+
          |        |        |
       Known    Novel    Anti
       Patterns Patterns Patterns
          |        |        |
          +--------+--------+
                    |
           Pattern Registry Update

Scan Modes

ModeTargetAnalysis TypePerformance
AST ScanElixir source filesAbstract syntax tree pattern matching1,000 files/sec
Regex ScanAll text filesRegular expression pattern detection5,000 files/sec
Doc ParseMarkdown/documentationStructure and content pattern analysis2,000 files/sec
Cross-ReferenceCode + documentation pairsConsistency and coverage analysis500 pairs/sec

Pattern Classification

Discovered patterns are classified into three categories:

  • Known Patterns: Match existing entries in the pattern library with confidence scores. These patterns confirm that established architectural decisions are being followed (or violated, in the case of anti-patterns).
  • Novel Patterns: New structures appearing frequently enough to warrant cataloguing. These represent emerging conventions that may deserve formalization in the pattern library.
  • Anti-Patterns: Structures matching known problematic patterns. These are flagged for remediation through /quality-evolve or manual intervention.

Execution Phases

Phase 1 -- File Discovery: The scanner enumerates target files using the Git tree index for performance. Files are categorized by type (Elixir source, test, documentation, configuration) and queued for appropriate scan modes.

Phase 2 -- Code Pattern Scanning: Elixir source files are parsed into ASTs and analyzed for structural patterns. The scanner maintains a library of known patterns (both positive and anti-patterns) and uses fuzzy matching to identify variants. Novel structures that appear frequently across the codebase are flagged as potential new patterns.

Phase 3 -- Documentation Pattern Scanning: Documentation files are parsed for structural patterns: heading hierarchies, cross-reference density, content coverage, and terminology consistency. Documentation that diverges from platform conventions is flagged for review.

Phase 4 -- Cross-Reference Analysis: When enabled, the scanner correlates code modules with their documentation. Missing documentation for public modules, outdated documentation that does not match current code, and undocumented public functions are all identified.

Phase 5 -- Pattern Classification: Discovered patterns are classified against the pattern library. Confidence scores are assigned based on structural similarity, frequency, and context matching.

Phase 6 -- Registry Update: Classified patterns are submitted to the mycelial network registry. Known patterns have their occurrence counts updated. Novel patterns are queued for human review. Anti-patterns are flagged for remediation.

Examples

Quality-Focused Anti-Pattern Scan

/scan-mycelium --focus anti-patterns --since 7d --format json
# Discovers anti-patterns introduced in the last week:
# - 3 instances of unsafe map access (map[:key] instead of Map.get)
# - 2 instances of Process.sleep in production code
# - 1 God module exceeding 500 lines

Documentation Consistency Audit

/scan-mycelium --mode docs --cross-reference --verbose
# Cross-references code modules with documentation:
# - 12 public modules lack documentation
# - 5 documentation files reference removed functions
# - 3 documentation files have outdated code examples

Propagation Candidate Discovery

/scan-mycelium --propagation-candidates --export ./candidates/
# Identifies patterns suitable for mycelial propagation:
# - GenServer health check pattern (found in 8 modules, missing from 15)
# - Telemetry event pattern (found in 12 modules, missing from 23)
# - Circuit breaker pattern (found in 3 modules, applicable to 7 more)

Integration with Platform

ComponentIntegration TypeDescription
/mycelializeDownstreamDiscovered patterns feed into propagation
/mycelialize-livingDownstreamNovel patterns become evolution candidates
/mycelialize-formalDownstreamCritical patterns queued for formal verification
/propagate-patternDownstreamPositive patterns propagated across codebase
/quality-evolveDownstreamAnti-patterns trigger quality evolution cycles
/chronicPeerDocumentation hygiene scan results feed into mycelium
Git TreesInfrastructureFast file enumeration
TelemetryMonitoringScan metrics and pattern discovery rates
/patternPattern libraryKnown patterns sourced from pattern library

Workflow Integration

The /scan-mycelium command participates in the platform's continuous improvement workflow:

  1. Post-Feature Scanning: After major feature additions, scanning discovers new patterns introduced by the feature. Positive patterns are candidates for propagation; anti-patterns are candidates for remediation.

  2. Pre-Evolution Preparation: Before /quality-evolve cycles, anti-pattern scanning provides a fresh list of targets. This ensures evolution efforts address real, current problems rather than stale data.

  3. Documentation Maintenance: Weekly cross-reference scans catch documentation drift before it accumulates. Code changes without corresponding documentation updates are a persistent quality issue that this scanning addresses systematically.

  4. Pattern Library Growth: Novel pattern discovery feeds the /pattern library with new candidates. Patterns that appear consistently across the codebase may be formalized into the library after review.

  5. Quality Monitoring: Trend analysis (--trend-analysis) tracks pattern frequency over time, revealing whether quality improvement efforts are having their intended effect.

NABLA Compliance

All commands operate under the NO MERCY, NO DOUBTS doctrine:

  • NO MERCY: Zero tolerance for incomplete execution or quality violations. Anti-patterns are flagged without exception. No scan results are suppressed or minimized.
  • NO DOUBTS: Full investigation before action, evidence-based results. Patterns are reported with confidence scores and evidence locations. Every finding is traceable to specific files and line numbers.

NABLA axiom compliance:

AxiomEnforcement
Signal PluralityMultiple scan modes (AST, regex, doc parse) provide independent signals
Provenance MandatoryEvery pattern finding includes file path, line numbers, and scan mode
Unknown ValidUncertain patterns reported with confidence scores, not suppressed
Time DecayPattern freshness tracked; stale patterns flagged for re-verification
Contradiction PreservationConflicting pattern classifications preserved for human resolution

Performance

MetricTargetTypical
AST scan1,000 files/sec~1,200 files/sec
Regex scan5,000 files/sec~6,000 files/sec
Doc parse2,000 files/sec~2,500 files/sec
Cross-reference500 pairs/sec~600 pairs/sec
Full platform scan< 5min~2min
Incremental scan (7d)< 30s~10s
Pattern classification< 10s~3s
Registry update< 5s~1s

The scanner leverages Git Trees for file enumeration and parallel workers for concurrent scanning. The default parallelism of 4 workers balances throughput with system load. Incremental scanning (using --since or --incremental) dramatically reduces scan time by processing only recently changed files.

Connect & Contribute

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

Related Commands

/chronic

Chronic documentation scan and technical hygiene maintenance

/find-lowfruit

Identify low-hanging fruit improvements across codebase

/propagate-pattern

Propagate successful patterns across the ecosystem
All Commands
Next
/propagate-pattern