{
  "item_type": "subsection",
  "chapter_id": "troubleshooting",
  "subsection_id": "error-messages-troubleshooting",
  "subsection_title": "Error Messages Reference",
  "subsection_file": "book/src/troubleshooting/error-messages.md",
  "feature_mappings": [
    "debt_detection.capabilities",
    "meta_content.troubleshooting",
    "boilerplate_detection"
  ],
  "drift_detected": true,
  "severity": "high",
  "quality_assessment": "Subsection covers basic error categories but is missing comprehensive error code documentation, language-specific issues, boilerplate detection context, and false positive handling. The actual codebase has a sophisticated error system with structured error codes (E001-E059) and classification methods that are not documented.",
  "issues": [
    {
      "type": "missing_content",
      "severity": "high",
      "section": "Error Codes",
      "description": "DebtmapError has structured error codes (E001-E059) with categories: I/O (E001-E009), Parse (E010-E019), Config (E020-E029), Analysis (E030-E039), CLI (E040-E049), Validation (E050-E059). These are not documented.",
      "feature_reference": "debtmap_error.ErrorCode",
      "fix_suggestion": "Add 'Error Codes Reference' section documenting all error code ranges and their meanings. Include E001 (IO_FILE_NOT_FOUND), E002 (IO_PERMISSION_DENIED), E010 (PARSE_SYNTAX), E020 (CONFIG_INVALID), etc.",
      "source_reference": "src/debtmap_error.rs:62-116"
    },
    {
      "type": "missing_content",
      "severity": "high",
      "section": "Error Classification",
      "description": "Errors have is_retryable() and is_user_fixable() classification methods that help users understand which errors are transient vs permanent. This is not documented.",
      "feature_reference": "debtmap_error.DebtmapError.is_retryable",
      "fix_suggestion": "Add section explaining error classification: retryable errors (resource busy, timeout, connection issues) vs non-retryable (parse errors, config errors). Document that parse/config/CLI/validation errors are user-fixable.",
      "source_reference": "src/debtmap_error.rs:466-519"
    },
    {
      "type": "missing_content",
      "severity": "medium",
      "section": "Coverage Errors",
      "description": "Coverage processing errors are a distinct category with specific solutions but are not documented in the error messages reference.",
      "feature_reference": "errors.AnalysisError.CoverageError",
      "fix_suggestion": "Add 'Coverage Errors' section documenting: coverage file format issues, function name matching failures, and the explain-coverage command for diagnostics.",
      "source_reference": "src/errors/mod.rs:96-100"
    },
    {
      "type": "missing_content",
      "severity": "medium",
      "section": "False Positives",
      "description": "The codebase has extensive false positive reduction mechanisms (context-aware detection, pattern-based classification, --no-context-aware flag) but the error messages reference doesn't explain how to handle false positive reports.",
      "feature_reference": "debt_detection.capabilities.context-aware_false_positive_reduction",
      "fix_suggestion": "Add 'Handling False Positives' section explaining: context-aware analysis (enabled by default), --no-context-aware flag, how pattern detection reduces false positives, and when to expect false positives.",
      "source_reference": "src/cli/args.rs:202-204"
    },
    {
      "type": "incomplete_explanation",
      "severity": "medium",
      "section": "Boilerplate Detection",
      "description": "The topics list includes 'Boilerplate detection' but the document doesn't explain boilerplate detection errors or how to interpret boilerplate recommendations.",
      "feature_reference": "boilerplate_detection",
      "fix_suggestion": "Add section explaining boilerplate detection messages: what they mean, when files are classified as boilerplate (20+ impl blocks, high method uniformity, low complexity), and how to act on recommendations.",
      "source_reference": "src/organization/boilerplate_detector.rs:33-58"
    },
    {
      "type": "outdated_information",
      "severity": "medium",
      "section": "Configuration Errors",
      "description": "Document mentions .debtmap/config.toml but the actual config location is debtmap.toml in the project root or ~/.config/debtmap/config.toml for global config.",
      "current_content": ".debtmap/config.toml",
      "should_be": "debtmap.toml or ~/.config/debtmap/config.toml",
      "fix_suggestion": "Update configuration error section to reference correct config file locations: project-level debtmap.toml and global ~/.config/debtmap/config.toml.",
      "source_reference": "features.json:configuration.configuration_sources"
    },
    {
      "type": "missing_content",
      "severity": "low",
      "section": "Language-Specific Issues",
      "description": "The topics list includes 'Language-specific issues' but document doesn't address Rust-specific parsing issues (macros, proc-macros) or Python support status.",
      "feature_reference": "cli_interface.commands.analyze.capabilities",
      "fix_suggestion": "Add section documenting language-specific considerations: Rust macro handling (--verbose-macro-warnings, --show-macro-stats), Python/JS support status (stub support), and language detection.",
      "source_reference": "src/core/ast.rs:138-142"
    },
    {
      "type": "missing_content",
      "severity": "low",
      "section": "Exit Codes",
      "description": "DebtmapError provides exit codes (1-5) for different error categories but these are not documented for CI/CD integration.",
      "feature_reference": "debtmap_error.DebtmapError.exit_code",
      "fix_suggestion": "Add 'Exit Codes' section: 1 (I/O/Analysis error), 2 (CLI error), 3 (Config error), 4 (Validation error), 5 (Parse error). This helps CI/CD pipelines handle failures appropriately.",
      "source_reference": "src/debtmap_error.rs:521-532"
    }
  ],
  "positive_aspects": [
    "Clear structure with error message, meaning, and solutions format",
    "Covers major error categories (File System, Parse, Analysis, Configuration, Validation, Dependency, Concurrency, Pattern)",
    "Provides practical command-line solutions with code blocks",
    "Cross-references to related troubleshooting subsections (Quick Fixes, Debug Mode)"
  ],
  "improvement_suggestions": [
    "Add comprehensive error code table with all E001-E059 codes",
    "Document error classification (retryable vs permanent, user-fixable vs system)",
    "Add section on false positive handling and context-aware analysis",
    "Include exit code reference for CI/CD integration",
    "Document boilerplate detection messages and recommendations",
    "Update configuration file paths to current locations"
  ],
  "cross_references": [
    "quick-fixes",
    "debug-mode",
    "faq"
  ],
  "metadata": {
    "analyzed_at": "2025-12-27T00:00:00Z",
    "feature_inventory": ".prodigy/book-analysis/features.json",
    "topics_covered": [
      "Error types",
      "Language-specific issues",
      "Boilerplate detection",
      "False positives"
    ],
    "validation_focus": "Check error messages and language issues are documented",
    "internal_links_validated": true,
    "broken_links_found": 0
  }
}
