Xray Method

<plugin-root> names the directory that holds this plugin's .codex-plugin/plugin.json. Resolve it once from where this file was loaded, then substitute it into every path below that starts with it.

Codebase X-Ray Analysis Skill

Overview

This skill combines mechanical structure extraction with Claude's semantic understanding to produce comprehensive codebase documentation. Unlike simple AST parsing, this skill captures:

• WHAT the code does (structure, functions, classes)
• WHY it exists (business purpose, design decisions)
• HOW it integrates (dependencies, contracts, flows)
• CONSEQUENCES of changes (side effects, failure modes)

Language Support

.sql files are disambiguated against PL/SQL by inspecting content for Oracle-specific markers (CREATE OR REPLACE PACKAGE, DBMS_OUTPUT, %TYPE, %ROWTYPE, UTL_FILE, PRAGMA AUTONOMOUS, etc.). PostgreSQL plpgsql is correctly classified as SQL.

Prerequisites

The scripts require Python >= 3.10 and work out of the box with just the stdlib. Tree-sitter is optional and improves accuracy for Java / JavaScript / TypeScript / Rust:

# Optional: install for higher-fidelity parsing
pip install -r "<plugin-root>/skills/xray-method/scripts/requirements.txt"
# or
uv pip install -r "<plugin-root>/skills/xray-method/scripts/requirements.txt"

What changes when tree-sitter is installed:

• Java: nested classes, generic type parameters, annotations, multi-line declarations parsed correctly. Without it, the regex fallback still finds top-level classes, methods, imports, and constants.
• JavaScript / TypeScript: arrow functions in object/class properties, decorators, template literals, JSX elements parsed correctly. Without it, the regex fallback handles top-level declarations, ES6 import/export, and CommonJS require.
• Rust: lifetimes, generic bounds (where clauses), impl blocks with trait bounds, attribute macros parsed correctly. Without it, the regex fallback still finds top-level fns, structs/enums/traits/impls/mods, use declarations, and UPPER_CASE constants.
• Python / SQL / PL-SQL: no change. Python always uses stdlib ast; SQL/PL-SQL always use the regex DDL extractor.

The active parser is reported in ParseResult.notes and in the CLI output: parser=stdlib-ast, parser=tree-sitter, or parser=regex-fallback.

Capabilities

Mechanical Analysis (Scripts):

• Extract code structure (classes, functions, imports)
• Map dependencies (internal/external)
• Find symbol usages across the codebase
• Classify files by criticality

Semantic Analysis (Claude AI):

• Recognize architectural and design patterns
• Identify red flags and anti-patterns
• Trace data and control flows
• Document contracts and invariants
• Assess quality and maintainability

Documentation Maintenance:

• Review and maintain documentation (Phase 6)
• Fix broken links and update navigation indexes
• Analyze and rewrite code comments (antirez standards)

Use this skill when:

• Analyzing a codebase you're unfamiliar with
• Generating documentation that explains WHY, not just WHAT
• Identifying architectural patterns and anti-patterns
• Building technical ground truth before a code review
• Onboarding to a new project

How This Skill Is Invoked

This skill is the method; the commands apply it. /codebase-xray:analyze runs every phase inline in one context, and /codebase-xray:team-analyze partitions the target and dispatches the phases per partition to isolated workers, which read this skill directly. Both manage their state automatically under .codebase-xray/ using the concurrent runs model below.

The skill's own name is codebase-xray:xray-method. codebase-xray:analyze names the command, and only the command: the two used to share a name, and on a host that lists both under one identifier the command shadowed the skill.

Concurrent Runs Model

Multiple analyses can run at the same time (different targets, different sessions, or a re-analysis while an older one is still in flight). Every analysis is an isolated run:

.codebase-xray/
├── runs.json                          # registry: active runs + latest completed
├── runs/
│   └── <run-id>/                      # one directory per analysis run
│       ├── state.json                 # per-run phase tracking, flags, lineage
│       ├── snapshot/manifest.json     # the tree this run analyzed: files, symbols, hashes
│       ├── changes.json               # incremental runs: the change set since the parent
│       ├── changes.md                 # incremental runs: what changed and what it did to the claims
│       ├── knowledge/                   # Phase 0: navigation.md, documentation-leads.md
│       ├── 01-structure.md .. 07-final-report.md
│       ├── partitions/<name>/...      # team mode only
│       └── 08-interconnect-map.md     # team mode only
├── state.json                         # mirror of the latest published run
└── 01-structure.md .. 08-*.md         # mirror of the latest published run

Rules:

1. Run identity. run-id = slug of the target path + -YYYYMMDD-HHMMSS, or the value of --run-name <name> (normalized to [a-z0-9-]; on collision append -2, -3, ...).
2. Isolation. A run writes ONLY inside .codebase-xray/runs/<run-id>/ while in progress. Concurrent runs never share files.
3. Registry. runs.json holds {"schema": 2, "active": [{run_id, target, mode, started_at}], "latest_completed": "<run-id>"}. Commands register their run at start and update the registry at completion. Read-modify-write it; never blindly overwrite entries you did not create.
4. Publish step. On successful completion, the orchestrating command copies the run's 01..0N.md files and state.json to the .codebase-xray/ root and sets latest_completed. The root mirror is the downstream contract: consumers (/senior-review:team-review, /senior-review:code-review, /codebase-mapper:map-codebase, /project-setup:create-claude-md) keep reading .codebase-xray/01-structure.md etc. unchanged. If two runs finish concurrently, the last one to publish owns the root mirror; both remain intact under runs/.
5. Resume. On invocation, the command reads runs.json: active runs are offered for resume; completed runs can be archived or re-published. A root state.json containing current_phase with no runs.json present is a pre-runs legacy layout: offer to migrate it into runs/legacy-<date>/ before starting.
6. Mirror is for latest-state consumers only. .codebase-xray/ is a mutable convenience mirror of the latest published run. It MUST NOT be used by an orchestrated workflow to consume the output of a specific X-ray invocation: rule 4 makes the root mirror owned by whichever run published last, so a concurrent run can replace it between production and consumption. A workflow that started a run and then consumes it MUST retain and propagate the immutable run directory .codebase-xray/runs/<run-id>/. The general form: a specific invocation implies the immutable run directory, a latest-state consumer implies the mirror. One-shot commands asking for the most recent published analysis are correct on the mirror.
7. Lineage. Every run writes snapshot/manifest.json, the structural record of the tree it analyzed, which makes it a possible parent for a later run. An incremental run records its parent in state.json -> parent_run and in its runs.json entry. The chain of those values is the analysis history, and no other structure holds it. A mirror consumer never needs any of this: snapshot/, changes.json and changes.md stay in the run directory and are never published to the root.

Incremental Updates

A second X-ray of the same target rebuilds from nothing only if nobody asked what changed. The mechanism that asks is scripts/snapshot.py, and every part of it runs outside the model.

The snapshot (snapshot/manifest.json, written by every run) records each file with its size, mtime and content hash, and each symbol with its line span and a hash of its body, plus the git commit as metadata. A class span encloses its methods, so editing a method moves both hashes. Files in languages the adapters do not parse get a file-level entry and no symbols. Forbidden files never enter it, not even as a hash.

The change set (changes.json, written by snapshot.py diff) compares that manifest with the current worktree. Equal size and mtime means unchanged with no read at all; anything else is hashed, because a checkout moves mtimes without changing a byte. It classifies files and symbols, resolves the one-hop blast radius from the manifest's import edges, and scans the parent's phase files for every claim citing anything it touched. It recommends incremental, full (with reasons: too much changed, no parent manifest, an incomplete parent, flags differing from the parent's) or none.

The carry (snapshot.py carry) copies the parent's phase files, except the final report, which is never carried and is always regenerated. It renumbers every citation whose symbol survived, and marks every affected claim with <!-- xray:stale reason=... cites=... -->. The model then reads only the affected files and re-derives only the marked claims.

The gate (snapshot.py check) fails if any marker survives or any added symbol went undocumented. An incremental run does not publish until it passes. That gate is the whole reason an incremental result can be trusted the way a full one is: the claims it kept were not re-checked, so what it did not carry must be provably finished.

Two things this deliberately does not do. It never uses a git range as the source of truth, because the tree a developer wants re-analyzed is usually dirty and sometimes not in a repository at all; git is metadata. And it never widens the blast radius past one hop, because the transitive closure of imports is, on most codebases, the whole tree.

CRITICAL PRINCIPLE: EVIDENCE-ANCHORED OUTPUT

Every file this skill produces is a set of claims about the code, each anchored to the code and each carrying a status. None of it is unquestionable. /senior-review:team-review re-derives its premises without reading the X-ray and refutes an X-ray claim whenever the code disagrees; that is the design working, not failing. What makes the output worth consuming is that every claim says where it came from and how sure it is.

Mandatory Rules (VIOLATION = FAILURE)

1. NEVER document anything without reading the actual source code first
2. NEVER assume any existing documentation, comment, or docstring is accurate
3. NEVER write documentation based on memory, inference, or "what should be"
4. ALWAYS derive technical facts EXCLUSIVELY from reading and tracing actual code
5. ALWAYS cite file:line for every technical claim in a phase file, and add the qualified symbol (file.py::Class.method) where one exists. The line locates the evidence for this run; the symbol survives the next edit. Downstream consumers (premise-auditor, the interconnect mapper, the review dimensions) read file:line
6. ALWAYS verify state machines, enums, constants against actual definitions
7. TREAT all pre-existing docs as unverified claims requiring validation
8. MARK every claim with the status the interconnect mapper uses: verified (enforced in code, cite where), documented (a document declares it, cite where), unverified (relied on, nothing enforces or documents it), disputed (two derivations disagree, cite both). [UNVERIFIED - REQUIRES CODE CHECK] stays the inline form for prose
9. USE qualified symbol names, never line numbers, in the verification markers of maintained documentation ([VERIFIED: file.py::Class.method], see references/analysis-templates.md). Those markers persist across edits, where a phase file is regenerated every run

Documents play two roles, and only one of them is constrained above

As evidence, a document is an unverified claim requiring validation. Rules 2 and 7 govern that role and are not negotiable: a document never establishes a technical fact.

As a discovery lead, a document is a first-class input that must be collected early. A project's own index telling you that a concept named X exists and lives in module Y is not a claim about behaviour; it is a pointer telling you where to look and what to look for. Refusing to read it does not make the analysis more rigorous, it makes it blind to intent and to code paths the structure alone does not reveal.

Phase 0 collects leads. Phase 6 audits documents as evidence. Never let the second role suppress the first.

See references/analysis-templates.md for the full verification trust model, temporal purity principle, and documentation status markers.

Phase 0: Project Knowledge Discovery

Runs in every depth, including --depth=lite, and runs first, in the orchestrating context: reading project instructions and globbing for index files is cheap, and what it finds shapes what every later phase looks for.

Phases 1 through 7 keep their numbers. --phase N is a user-facing flag and renumbering would break every invocation that names a phase.

Phase 0 is a preamble, not a selectable analysis phase. It runs before every invocation, --phase 5 and --docs-only included, and it does not change the numbering semantics of phases 1 to 7. --phase 5 still means "run phase 5 and nothing else from the analysis set", with the preamble in front of it. --phase 0 runs the preamble alone, which is a legitimate way to ask only "how does this repository document itself".

This phase owns discovery of how the repository documents itself. It does not evaluate whether the documentation is accurate, which is Phase 6.

1. Read CLAUDE.md, AGENTS.md and any equivalent project instruction file at the repository root and in the target's ancestors. Record any navigation instruction they give, especially a statement of the form "look here first to find where a concept lives".
2. Locate the canonical indexes the project actually uses. Glob for, at minimum: **/SEARCH_INDEX.md, **/INDEX.md, docs/README.md, README.md, **/BY_DOMAIN.md, **/adr/**, **/decisions/**, **/architecture/**, **/domains/**, .codebase-map/INDEX.md. Record what exists, not what you expected to exist.
3. For each concept, symbol and subsystem in the analysis scope, search the located documents for an entry. Record the concept, the document, and the anchor or heading that matched.
4. Write both output files. Every row is a lead with status documented or unverified. Nothing here is verified, because this phase reads no code.

$RUN_DIR below is the active run directory, .codebase-xray/runs/<run-id>/, per the Concurrent Runs Model above.

Output file: $RUN_DIR/knowledge/navigation.md

# Project Knowledge Navigation

## Project instructions read
| File | Navigation rule it states |
|------|---------------------------|

## Canonical indexes found
| Index | Path | What it indexes |
|-------|------|-----------------|

## Conventions observed
[How this repository organizes its knowledge, in prose. Name the file the project treats as its semantic index, if it has one.]

## Not found
[Index kinds searched for and absent. An absent index is a fact worth recording.]

Output file: $RUN_DIR/knowledge/documentation-leads.md

# Documentation Leads

> Leads, not truth. Every row is a pointer to where the project claims a concept lives.
> Status is `documented` or `unverified`. No row here is `verified`: this phase reads no code.

| Concept / symbol | Document | Anchor | Status |
|------------------|----------|--------|--------|

## Concepts in scope with no lead
[Concepts the scope touches for which no document was found. This list is what a
downstream consumer must discover independently.]

This section is the canonical copy. /codebase-xray:analyze carries the same procedure and templates in its own ## Phase 0 section so the command path is self-contained, and /codebase-xray:team-analyze runs the same phase once for the whole run. All three must move together: /senior-review:team-review reaches this phase through the analyze command and its Phase 1d consumes knowledge/documentation-leads.md from whichever path produced the run, while the team-analyze workers read this skill directly.

Output Usage Guide

After analysis completes, consult the right file for your task:

The two knowledge/ files are Phase 0 output and are the only files in the set produced without reading code: every row is a lead, never a verified fact. /senior-review:team-review Phase 1d reads knowledge/documentation-leads.md from the run directory and joins it against its own independent discovery, so a run that skips Phase 0 leaves that consumer with an empty half.

Forbidden Files

The analysis NEVER reads or includes contents from sensitive files: .env, .env.*, credentials.*, secrets.*, *.pem, *.key, *.p12, *.pfx, id_rsa*, id_ed25519*, .npmrc, .pypirc, .netrc, or any file containing API keys, passwords, or tokens. If encountered, note file existence only - never quote contents.

Script Commands

All scripts live in <plugin-root>/skills/xray-method/scripts/.

1. Analyze Single File

# Python
python "<plugin-root>/skills/xray-method/scripts/analyze_file.py" \
  --file src/utils/circuit_breaker.py \
  --output-format markdown

# Java
python "<plugin-root>/skills/xray-method/scripts/analyze_file.py" \
  --file src/main/java/com/example/UserService.java

# TypeScript
python "<plugin-root>/skills/xray-method/scripts/analyze_file.py" \
  --file src/services/auth.ts

# Rust
python "<plugin-root>/skills/xray-method/scripts/analyze_file.py" \
  --file src/lib.rs

# SQL / PL-SQL
python "<plugin-root>/skills/xray-method/scripts/analyze_file.py" \
  --file migrations/0042_users.sql

Parameters:

• --file / -f: Relative or absolute path to file - REQUIRED. Any supported extension (see Language Support table).
• --output-format / -o: Output format (json, markdown, summary) - default: summary
• --find-usages / -u: Find all usages of exported symbols - default: false

2. Find Usages of One Symbol

python "<plugin-root>/skills/xray-method/scripts/analyze_file.py" \
  --file src/utils/circuit_breaker.py --find-usages --symbol CircuitBreaker

--symbol restricts the usage search to a single exported symbol; the script errors cleanly if the symbol is not exported by the file.

3. Structural Parse Only

python "<plugin-root>/skills/xray-method/scripts/ast_parser.py" src/services/auth.ts

Emits the raw structural extraction (classes, functions, imports, exports) as JSON. Reports the active parser in notes.

Documentation Maintenance Commands (Phase 6)

4. Scan Documentation Health

python "<plugin-root>/skills/xray-method/scripts/doc_review.py" scan \
  --path docs/ --output doc_health_report.json

5. Validate Links

python "<plugin-root>/skills/xray-method/scripts/doc_review.py" validate-links \
  --path docs/ --fix

6. Verify Against Source Code

python "<plugin-root>/skills/xray-method/scripts/doc_review.py" verify \
  --doc docs/agents/lifecycle.md --source src/agents/lifecycle.py

7. Update Navigation Indexes

python "<plugin-root>/skills/xray-method/scripts/doc_review.py" update-indexes \
  --search-index docs/00_navigation/SEARCH_INDEX.md \
  --by-domain docs/00_navigation/BY_DOMAIN.md

8. Full Documentation Maintenance

python "<plugin-root>/skills/xray-method/scripts/doc_review.py" full-maintenance \
  --path docs/ --auto-fix --output doc_health_report.json

Executes: scan health, validate/fix links, identify obsolete files, update indexes, generate report.

Comment Quality Commands (Antirez Standards)

9. Analyze Comment Quality

python "<plugin-root>/skills/xray-method/scripts/rewrite_comments.py" analyze \
  src/main.py --report

10. Scan Directory for Comment Issues

python "<plugin-root>/skills/xray-method/scripts/rewrite_comments.py" scan \
  src/ --recursive --issues-only

11. Generate Comment Health Report

python "<plugin-root>/skills/xray-method/scripts/rewrite_comments.py" report \
  src/ --output comment_health.md

12. Rewrite Comments

python "<plugin-root>/skills/xray-method/scripts/rewrite_comments.py" rewrite \
  src/main.py --apply --backup

13. View Standards Reference

python "<plugin-root>/skills/xray-method/scripts/rewrite_comments.py" standards

Incremental Update Commands

14. Write a structural snapshot

python <plugin-root>/skills/xray-method/scripts/snapshot.py write <target> \
  --out <run-dir>/snapshot/manifest.json

Records the tree a run analyzed. Every run writes one, which is what makes it a possible parent.

15. Diff, carry and check an update

# what changed since a parent run, and which of its claims that affects
python <plugin-root>/skills/xray-method/scripts/snapshot.py diff \
  <parent-run-dir> <target> --out <run-dir> [--verify] [--threshold 0.4] [--flags '{"depth":"full"}']

# copy the parent's phase files, renumber citations, mark the stale claims
python <plugin-root>/skills/xray-method/scripts/snapshot.py carry <parent-run-dir> <run-dir>

# publication gate: no marker left, no undocumented new symbol
python <plugin-root>/skills/xray-method/scripts/snapshot.py check <run-dir>

--verify hashes every file instead of trusting size and mtime. --threshold is the affected-file ratio above which a full run is recommended instead.

File Classification Criteria

The classifier matches patterns against raw file content (including comments and string literals), so treat its verdict as a triage signal to be confirmed by reading the file, not as ground truth.

AI-Powered Semantic Analysis

Five Layers of Understanding

Pattern Recognition

Red Flags to Identify

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

AI Analysis Workflow

1. SCRIPTS RUN FIRST -> classifier.py, ast_parser.py, usage_finder.py
2. CLAUDE ANALYZES -> Read source, apply semantic questions, recognize patterns, identify red flags
3. CLAUDE DOCUMENTS -> Use template, explain WHY not just WHAT, document contracts
4. VERIFY -> Re-trace the code path end to end; accept runtime evidence only when the user supplies it

Analysis Loop Workflow

1. CLASSIFY -> LOC, dependencies, critical patterns, assign classification
2. READ & MAP -> AST structure, classes, functions, constants, state mutations
3. DEPENDENCY CHECK -> Internal imports, external imports, external calls
4. CONTEXT ANALYSIS -> Symbol usages, importing modules, message flows
5. CODE-PATH VERIFICATION (Critical/High-Complexity) -> Trace every call path the claim depends on; runtime logs or traces count only when the user supplies them, and are never invented
6. DOCUMENTATION -> Write the phase output file into the active run directory

Best Practices

Source Code Analysis (Phases 1-5)

1. Start with Phase 1 - foundation modules inform everything else
2. Never skip code-path verification for critical/high-complexity files. This is static analysis: runtime evidence is welcome when supplied, never required, never fabricated
3. Keep all writes inside the active run directory until the publish step

Documentation Maintenance (Phase 6)

1. Run scan first to understand current state
2. Fix links before content - broken links indicate structural issues
3. Verify against code before updating documentation
4. Update indexes last to reflect final state

Team Mode Integration

The classic /codebase-xray:analyze command runs every phase inline in one context on a single target. For monorepos, multi-language repos, or any target where one context would have to hold too much, switch to the team variant:

/codebase-xray:team-analyze <target>

The team command:

1. Auto-detects partitions (workspaces, top-level dirs, or language clusters) and asks you to confirm at a checkpoint.
2. Spawns three workers per partition in two waves (Wave 1 = Structure; Wave 2 = Behavior + Quality). Wave 2 workers read every partition's Wave 1 output, so cross-partition contracts and flows can be cited directly.
3. Synthesizes a backward-compatible 01..07.md set inside the run directory; the publish step mirrors it to the .codebase-xray/ root, so any downstream consumer (/senior-review:team-review, /codebase-mapper:map-codebase, /project-setup:create-claude-md) picks it up without changes.
4. Adds 08-interconnect-map.md produced by codebase-xray:semantic-interconnect-mapper on top of the consolidated set, giving a global Call Graph, Contracts, Invariants, and Integration Hot-Spots view.

Choosing between classic and team

References

• references/analysis-templates.md - Verification trust model, temporal purity principle, documentation status markers, comment classification, maintenance workflows
• references/AI_ANALYSIS_METHODOLOGY.md - Complete analysis methodology
• references/SEMANTIC_PATTERNS.md - Pattern recognition guide
• references/ANTIREZ_COMMENTING_STANDARDS.md - Comment taxonomy
• templates/semantic_analysis.md - AI-powered per-file analysis template
• templates/analysis_report.md - Module-level report template

Resources

• Scripts: scripts/ - analysis tools (Python >= 3.10 runtime, multi-language targets)
  • ast_parser.py - structural extraction dispatcher
  • analyze_file.py - per-file CLI (classification + structure + usages)
  • classifier.py - language-aware criticality classifier
  • usage_finder.py - cross-file symbol usage finder (multi-language extensions)
  • comment_rewriter.py - multi-language comment analysis engine
  • rewrite_comments.py - comment quality CLI (scan / analyze / rewrite / report)
  • doc_review.py - documentation maintenance (Phase 6)
  • languages/ - per-language adapters (Python ast, Java/JS/TS/Rust via tree-sitter or regex, SQL/PL-SQL regex)
    • base.py - shared dataclasses + LanguageAdapter Protocol
    • __init__.py - extension dispatch (detect_language, get_adapter)
    • comments.py - per-language comment lexer (includes rustdoc post-processor)
    • _treesitter.py - optional tree-sitter loader with fallbacks
    • python.py, java.py, javascript.py, typescript.py, sql.py, plsql.py, rust.py
  • requirements.txt - optional dependencies (tree-sitter + tree-sitter-language-pack)