╔══════════════════════════════════════════════════════════════════════════════╗
║                     VERIFICATION TRUST MODEL                                  ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  Layer 1: TOOL-VALIDATED                                                     ║
║    └── Automated checks: file exists, line in range, AST symbol match        ║
║    └── Marker: [VALIDATED: file.py:123 @ 2025-12-20]                         ║
║                                                                              ║
║  Layer 2: HUMAN-VERIFIED                                                     ║
║    └── Manual review: semantic correctness, behavior match                   ║
║    └── Marker: [VERIFIED: file.py:123 by @reviewer @ 2025-12-20]             ║
║                                                                              ║
║  Layer 3: RUNTIME-CONFIRMED                                                  ║
║    └── Log/trace evidence of actual behavior                                 ║
║    └── Marker: [CONFIRMED: trace_id=abc123 @ 2025-12-20]                     ║
╚══════════════════════════════════════════════════════════════════════════════╝

Tool validation catches STRUCTURAL issues (file moved, line shifted, symbol renamed).
Human verification ensures SEMANTIC correctness (code does what doc says).
Runtime confirmation proves BEHAVIORAL truth (system actually works this way).

ALL THREE LAYERS are required for critical documentation.

╔══════════════════════════════════════════════════════════════════════════════╗
║  DOCUMENTATION = f(SOURCE_CODE) + VERIFICATION                               ║
║                                                                              ║
║  If NOT verified_against_code(statement) → statement is FALSE                ║
║  If NOT exists_in_codebase(reference)    → reference is FABRICATED           ║
║  If NOT traceable_to_source(claim)       → claim is SPECULATION              ║
╚══════════════════════════════════════════════════════════════════════════════╝

╔══════════════════════════════════════════════════════════════════════════════╗
║                     THE TEMPORAL PURITY PRINCIPLE                            ║
╠══════════════════════════════════════════════════════════════════════════════╣
║  Documentation = PRESENT_TENSE(current_implementation)                       ║
║                                                                              ║
║  FORBIDDEN:                                                                  ║
║  ✗ "was/were/previously/formerly/used to"                                    ║
║  ✗ "deprecated since version X" → just REMOVE it                             ║
║  ✗ "changed from X to Y" → only describe Y                                   ║
║  ✗ "in the old system..." → irrelevant, delete                               ║
║  ✗ inline changelogs → use CHANGELOG.md or git                               ║
║                                                                              ║
║  REQUIRED:                                                                   ║
║  ✓ Present tense: "The system uses..." not "The system used..."              ║
║  ✓ Current state only: Document what IS, not what WAS                        ║
║  ✓ Git for archaeology: History lives in version control, not docs           ║
╚══════════════════════════════════════════════════════════════════════════════╝

python .claude/skills/deep-dive-analysis/scripts/analyze_file.py \
  --file src/utils/circuit_breaker.py \
  --output-format markdown

python .claude/skills/deep-dive-analysis/scripts/check_progress.py \
  --phase 1 \
  --status pending

python .claude/skills/deep-dive-analysis/scripts/analyze_file.py \
  --symbol CircuitBreaker \
  --file src/utils/circuit_breaker.py

python .claude/skills/deep-dive-analysis/scripts/analyze_file.py \
  --phase 1 \
  --output-format markdown \
  --output-file docs/01_domains/COMMON_LIBRARY.md

python .claude/skills/deep-dive-analysis/scripts/doc_review.py scan \
  --path docs/ \
  --output doc_health_report.json

python .claude/skills/deep-dive-analysis/scripts/doc_review.py validate-links \
  --path docs/ \
  --fix  # Optional: auto-remove broken links

python .claude/skills/deep-dive-analysis/scripts/doc_review.py verify \
  --doc docs/agents/lifecycle.md \
  --source src/agents/lifecycle.py

python .claude/skills/deep-dive-analysis/scripts/doc_review.py update-indexes \
  --search-index docs/00_navigation/SEARCH_INDEX.md \
  --by-domain docs/00_navigation/BY_DOMAIN.md

python .claude/skills/deep-dive-analysis/scripts/doc_review.py full-maintenance \
  --path docs/ \
  --auto-fix \
  --output doc_health_report.json

python .claude/skills/deep-dive-analysis/scripts/rewrite_comments.py analyze \
  src/main.py \
  --report

python .claude/skills/deep-dive-analysis/scripts/rewrite_comments.py scan \
  src/ \
  --recursive \
  --issues-only

python .claude/skills/deep-dive-analysis/scripts/rewrite_comments.py report \
  src/ \
  --output comment_health.md

undefined

**Options:**
- `--apply` / `-a`: Actually modify the file (default: dry run)
- `--backup` / `-b`: Create .bak backup before modifying
- `--output` / `-o`: Write to different file instead of in-place

**Actions taken:**
- DELETE: Remove trivial comments and backup (commented-out code)
- REWRITE: Add suggested improvements for debt comments (TODO/FIXME)

python .claude/skills/deep-dive-analysis/scripts/rewrite_comments.py standards

1. SCAN
   ├── Run: rewrite_comments.py scan <dir> --recursive
   ├── Review files with most issues
   └── Generate: rewrite_comments.py report <dir> --output report.md

2. TRIAGE
   ├── Identify high-priority files (critical modules)
   ├── Focus on DEBT comments (convert to issues or design docs)
   └── Plan bulk TRIVIAL/BACKUP deletions

3. REWRITE
   ├── Run: rewrite_comments.py rewrite <file> --apply --backup
   ├── Review changes in diff
   └── Verify no functional changes

4. VERIFY
   ├── Run tests to confirm no breakage
   ├── Re-scan to confirm improvements
   └── Update comment_health.md report

╔══════════════════════════════════════════════════════════════════════════════╗
║                    STRUCTURE vs MEANING                                      ║
╠══════════════════════════════════════════════════════════════════════════════╣
║                                                                              ║
║  Scripts extract STRUCTURE:  "class Foo with method bar()"                   ║
║  Claude extracts MEANING:    "Foo implements Repository pattern for         ║
║                               caching user sessions with TTL expiration"     ║
║                                                                              ║
║  NEVER stop at structure. ALWAYS pursue understanding.                      ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝

ARCHITECTURE:
⚠ GOD CLASS: >10 public methods or >500 LOC
⚠ CIRCULAR DEPENDENCY: A → B → C → A
⚠ LEAKY ABSTRACTION: Implementation details in interface

RELIABILITY:
⚠ SWALLOWED EXCEPTION: Empty catch blocks
⚠ MISSING TIMEOUT: Network calls without timeout
⚠ RACE CONDITION: Shared mutable state without sync

SECURITY:
⚠ HARDCODED SECRET: Passwords, API keys in code
⚠ SQL INJECTION: String concatenation in queries
⚠ MISSING VALIDATION: Unsanitized user input

1. SCRIPTS RUN FIRST
   ├── classifier.py → File classification
   ├── ast_parser.py → Structure extraction
   └── usage_finder.py → Cross-references

2. CLAUDE ANALYZES
   ├── Read actual source code
   ├── Apply semantic questions
   ├── Recognize patterns
   ├── Identify red flags
   └── Trace flows

3. CLAUDE DOCUMENTS
   ├── Use semantic_analysis.md template
   ├── Explain WHY, not just WHAT
   ├── Document contracts and invariants
   └── Flag concerns with severity

4. VERIFY
   ├── Check against runtime behavior
   ├── Validate with code traces
   └── Mark verification status

1. CLASSIFY
   ├── Count lines of code
   ├── Count dependencies
   ├── Check for critical patterns (auth, security, encryption)
   └── Assign classification

2. READ & MAP
   ├── Parse AST to extract structure
   ├── Identify classes and their methods
   ├── Identify standalone functions
   ├── Find global variables and constants
   └── Detect state mutations

3. DEPENDENCY CHECK
   ├── Internal imports (from project modules)
   ├── External imports (third-party)
   └── External calls (database, network, filesystem, messaging, ipc)

4. CONTEXT ANALYSIS
   ├── Where are exported symbols used?
   ├── What modules import this file?
   └── What message types flow through here?

5. RUNTIME VERIFICATION (if Critical/High-Complexity)
   ├── Use log analysis to trace actual behavior
   ├── Verify documented flow matches actual flow
   └── Note any discrepancies

6. DOCUMENTATION
   ├── Update analysis_progress.json
   ├── Generate module report section
   └── Cross-reference with CONTEXT.md

{
  "file": "src/utils/circuit_breaker.py",
  "classification": "critical",
  "metrics": {
    "lines_of_code": 245,
    "num_classes": 2,
    "num_functions": 8,
    "num_dependencies": 12
  },
  "structure": {
    "classes": [...],
    "functions": [...],
    "constants": [...]
  },
  "dependencies": {
    "internal": [...],
    "external": [...],
    "external_calls": [...]
  },
  "usages": [...],
  "verification_required": true
}

1. PLANNING
   ├── Run: doc_review.py scan --path docs/
   ├── Review health report
   ├── Identify priority fixes (broken links, obsolete files)
   └── Create todo list with specific actions

2. EXECUTION (in batches)
   ├── Batch 1: Fix broken links
   │   └── Run: doc_review.py validate-links --fix
   ├── Batch 2: Verify critical docs against source
   │   └── Run: doc_review.py verify --doc <file> --source <code>
   ├── Batch 3: Delete obsolete files
   │   └── Manual review + deletion
   ├── Batch 4: Update navigation indexes
   │   └── Run: doc_review.py update-indexes
   └── Batch 5: Update timestamps
       └── Set last_updated on verified files

3. VERIFICATION
   ├── Run: doc_review.py scan (confirm improvements)
   ├── Run: doc_review.py validate-links (confirm zero broken)
   └── Generate final doc_health_report.json