pan-wizard 2.8.1 → 2.9.1

package/commands/pan/focus-drift-walking.md

@@ -0,0 +1,525 @@
+---
+name: focus-drift-walking
+group: Focus
+description: Deep documentation-code drift detection, CLAUDE.md alignment, and auto-repair across all project directories
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+---
+
+# /pan:focus-drift-walking — Documentation-Code Drift Detection & Alignment
+
+Walk every directory in the project, detect drift between documentation and code reality, create missing documentation, repair drifted files, and synchronize the truth hierarchy. $ARGUMENTS
+
+**Goal:** Eliminate the #1 cause of AI assistant hallucination — stale documentation. Walk the entire project tree, compare what documentation *claims* against what code *does*, score drift severity, and produce a complete alignment report with optional auto-repair. Every finding is evidence-based with file paths and line numbers.
+
+**Methodology:** Combines directory-walking inventory, content fingerprinting, cross-reference validation, semantic drift scoring, and layered truth reconciliation into a single automated pipeline.
+
+---
+
+## CRITICAL: Project Scope Boundary
+
+This command walks the **host project's directories and documentation** — NOT PAN Wizard's own infrastructure.
+
+**ALWAYS EXCLUDE these directories from walking:**
+- `.claude/`, `.github/copilot-instructions.md`, `.opencode/`, `.gemini/`, `.codex/` — PAN runtime directories
+- `.planning/` — PAN planning state (read for context, never report as drift)
+- Any `pan-wizard-core/`, `pan-tools`, agent `.md`, or command `.md` files within PAN runtime directories
+- Build output directories: `build/`, `dist/`, `out/`, `target/`, `bin/`, `obj/`, `node_modules/`, `.git/`, `__pycache__/`, `.next/`, `.nuxt/`
+
+**ALSO EXCLUDE:** Any directory listed in the project's `.gitignore` that represents generated output.
+
+If a drift finding points to a file inside a PAN or build directory — DROP IT.
+
+---
+
+## MANDATORY: Execute ALL Phases Automatically
+
+When `/pan:focus-drift-walking` is invoked, execute ALL phases for the selected mode without stopping. Do NOT ask questions between phases. Do NOT skip phases beyond what the mode specifies. Produce a complete drift report at the end.
+
+**Flags:**
+- `--create` — Create missing documentation files in directories that lack them
+- `--audit` — Audit all existing documentation files for drift against code
+- `--repair` — Auto-fix drifted documentation (update counts, paths, versions)
+- `--report` — Dry run: detect and report drift without modifying anything
+- `--dir <path>` — Target a specific directory subtree only
+- `--depth <n>` — Limit walk depth (default: unlimited)
+- `--severity <level>` — Filter report: `critical`, `warning`, `info` (default: all)
+- `--format <type>` — Output format: `markdown` (default), `json`, `checklist`
+- `--quick` — Skip Phase 4 (deep semantic analysis) and Phase 7 (cross-project sync)
+
+**Default mode (no flags):** `--audit --report` — full audit with report, no modifications.
+
+---
+
+## Truth Hierarchy
+
+Documentation has layers. Drift detection must understand which layer is the source of truth for what:
+
+```
+Layer 0: CODE (absolute truth)
+  │  Source files, config files, build scripts — what the project actually IS
+  │
+Layer 1: PROJECT ROOT DOCS (primary documentation)
+  │  README.md, CLAUDE.md, package.json, Cargo.toml, CMakeLists.txt
+  │  Source of truth for: version, project name, top-level architecture, build commands
+  │
+Layer 2: DIRECTORY-LEVEL DOCS (local documentation)
+  │  Per-directory README.md, CLAUDE.md, or equivalent
+  │  Source of truth for: directory purpose, local conventions, key files
+  │
+Layer 3: INLINE DOCS (code-level documentation)
+  │  Comments, docstrings, JSDoc, XML docs
+  │  Source of truth for: function behavior, parameter semantics
+  │
+Layer 4: EXTERNAL DOCS (generated/published documentation)
+     docs/, wiki/, guides, API references
+     Source of truth for: NOTHING (must be derived from Layers 0-3)
+```
+
+**Drift direction rule:** Higher layers NEVER override lower layers. If code says X and docs say Y, the docs are wrong.
+
+---
+
+## Phase 0: Initialization & Project Discovery
+
+### 0.1 Detect Project Type
+Automatically detect the project's technology stack and structure:
+
+| Signal File | Indicates |
+|------------|-----------|
+| `package.json` | Node.js / JavaScript / TypeScript |
+| `Cargo.toml` | Rust |
+| `CMakeLists.txt` | C / C++ (CMake) |
+| `*.csproj` / `*.sln` | .NET / C# |
+| `go.mod` | Go |
+| `pyproject.toml` / `setup.py` / `requirements.txt` | Python |
+| `pom.xml` / `build.gradle` | Java / Kotlin |
+| `pubspec.yaml` | Dart / Flutter |
+| `Makefile` | Generic build system |
+| `Dockerfile` | Containerized application |
+| `terraform/` / `*.tf` | Infrastructure as Code |
+
+Record all detected stacks — projects can be polyglot.
+
+### 0.2 Extract Root Truth
+Read the project's root-level documentation and extract canonical facts:
+
+**From build/config files:**
+- Project name and version
+- Entry points and main modules
+- Dependencies (count and key ones)
+- Build commands
+- Test commands
+
+**From README.md / CLAUDE.md:**
+- Stated architecture and component list
+- Stated feature list
+- Stated test counts
+- Stated build/run instructions
+- Stated directory structure
+
+### 0.3 Build Directory Manifest
+Walk the project tree and build a complete manifest:
+
+```markdown
+| Directory | Depth | Files | Has Docs | Doc Type | Key Content |
+|-----------|-------|-------|----------|----------|-------------|
+| src/ | 1 | 42 | ✅ | README.md | Application source |
+| src/api/ | 2 | 18 | ❌ | — | API endpoints |
+| tests/ | 1 | 31 | ✅ | README.md | Test suites |
+| ... | | | | | |
+```
+
+### 0.4 Establish Baseline Snapshot
+
+```markdown
+| Metric | Value | Source |
+|--------|-------|--------|
+| Project version | X.Y.Z | {config file} |
+| Total source files | N | Directory walk |
+| Total test files | N | Directory walk |
+| Directories with docs | N/M | Directory walk |
+| Documentation coverage | N% | Dirs with docs / total dirs |
+| Root doc files | N | README, CLAUDE, etc. |
+```
+
+---
+
+## Phase 1: Directory-Level Analysis
+
+For each directory in the manifest, perform deep content analysis.
+
+### 1.1 Content Fingerprinting
+For each directory, extract:
+
+| Artifact | How to Extract |
+|----------|---------------|
+| **Purpose** | Infer from filenames, imports, exports, README |
+| **Key files** | Files with most imports/references, entry points |
+| **Public API** | Exported functions, classes, endpoints, commands |
+| **Dependencies** | Import statements, require calls, use declarations |
+| **Dependents** | What imports/references this directory |
+| **Tech stack** | File extensions, framework imports |
+| **Test coverage** | Corresponding test directory or test files |
+| **Conventions** | Naming patterns, file organization, code style |
+
+### 1.2 Documentation Inventory
+For each directory that HAS documentation, catalog:
+
+| Field | Extract From Doc |
+|-------|-----------------|
+| Stated purpose | First paragraph / "Purpose" section |
+| Stated key files | "Key Files" table or list |
+| Stated dependencies | "Dependencies" section |
+| Stated conventions | "Conventions" / "Rules" section |
+| Stated build commands | "Build" / "Usage" section |
+| Version references | Any version numbers mentioned |
+| File paths mentioned | All `path/to/file` references |
+| Counts mentioned | Any numeric claims (N files, N tests, N endpoints) |
+
+### 1.3 Importance Classification
+Classify each directory for documentation priority:
+
+| Tier | Criteria | Documentation Requirement |
+|------|----------|--------------------------|
+| **Tier 1: Core** | Contains primary application logic, public API, or critical infrastructure | MUST have comprehensive docs |
+| **Tier 2: Supporting** | Contains utilities, helpers, internal services, tests | SHOULD have docs |
+| **Tier 3: Config/Infra** | Contains configuration, CI/CD, build scripts | MAY have docs |
+| **Tier 4: Generated/Vendored** | Contains generated code, vendored deps, build output | SKIP — no docs needed |
+
+---
+
+## Phase 2: Drift Detection Engine
+
+For each directory with existing documentation, run ALL drift checks.
+
+### 2.1 Structural Drift Checks
+
+| Check ID | Check | How |
+|----------|-------|-----|
+| SD-01 | **File existence** | Every file path in docs → verify file exists |
+| SD-02 | **File absence** | Important files in directory → verify mentioned in docs |
+| SD-03 | **Directory structure** | Stated structure → compare to actual `ls` output |
+| SD-04 | **Dead references** | File paths in docs that point to deleted/moved files |
+| SD-05 | **Orphan files** | Key files not mentioned in any documentation |
+
+### 2.2 Semantic Drift Checks
+
+| Check ID | Check | How |
+|----------|-------|-----|
+| SM-01 | **Purpose drift** | Stated purpose vs. actual content — does the description match? |
+| SM-02 | **API drift** | Documented exports/functions vs. actual code exports |
+| SM-03 | **Dependency drift** | Stated deps vs. actual import/require statements |
+| SM-04 | **Convention drift** | Stated patterns vs. actual code patterns |
+| SM-05 | **Architecture drift** | Stated architecture vs. actual file organization |
+
+### 2.3 Numeric Drift Checks
+
+| Check ID | Check | How |
+|----------|-------|-----|
+| ND-01 | **Version drift** | Version in docs vs. version in config files |
+| ND-02 | **Count drift** | Stated file/test/endpoint counts vs. actual counts |
+| ND-03 | **Metric drift** | Stated performance/size claims vs. verifiable reality |
+
+### 2.4 Command Drift Checks
+
+| Check ID | Check | How |
+|----------|-------|-----|
+| CD-01 | **Build command drift** | Documented build commands → attempt to validate syntax |
+| CD-02 | **Test command drift** | Documented test commands → attempt to validate syntax |
+| CD-03 | **CLI usage drift** | Documented CLI flags → verify against actual CLI help/source |
+
+### 2.5 Cross-Reference Drift Checks
+
+| Check ID | Check | How |
+|----------|-------|-----|
+| XR-01 | **Root alignment** | Sub-directory docs contradict root docs |
+| XR-02 | **Sibling alignment** | Directory A's docs claim about directory B → verify with B |
+| XR-03 | **Circular contradiction** | A says X depends on Y, Y says it doesn't export to A |
+| XR-04 | **Stale link targets** | Internal markdown links → verify targets exist and anchors resolve |
+
+---
+
+## Phase 3: Drift Severity Scoring
+
+### 3.1 Severity Classification
+
+| Level | Code | Meaning | Impact |
+|-------|------|---------|--------|
+| **CRITICAL** | `C` | Documentation will cause wrong code generation | AI assistants will hallucinate, developers will write bugs |
+| **HIGH** | `H` | Documentation is significantly misleading | Developers waste significant time following wrong instructions |
+| **MEDIUM** | `M` | Documentation is incomplete or partially wrong | Developers eventually figure it out but waste time |
+| **LOW** | `L` | Documentation is stale but not actively misleading | Cosmetic / completeness issue |
+| **INFO** | `I` | Suggestion for improvement, not actual drift | Nice-to-have |
+
+### 3.2 Severity Assignment Rules
+
+| Condition | Severity |
+|-----------|----------|
+| Wrong version number for a tool, SDK, or framework | CRITICAL |
+| Wrong build command | CRITICAL |
+| Referenced file does not exist | HIGH |
+| Stated API/export that doesn't exist in code | HIGH |
+| Wrong dependency direction | HIGH |
+| Count off by > 20% | MEDIUM |
+| Missing newly added key file from docs | MEDIUM |
+| Convention described but code uses different pattern | MEDIUM |
+| Count off by < 20% | LOW |
+| Purpose statement is vaguely correct but imprecise | LOW |
+| Missing optional section in docs | INFO |
+
+### 3.3 Drift Score Formula
+
+```
+Directory Drift Score = Σ(severity_weight × check_count) / total_checks
+
+Weights: CRITICAL=10, HIGH=5, MEDIUM=2, LOW=1, INFO=0
+```
+
+| Score | Rating | Action |
+|-------|--------|--------|
+| 0 | ALIGNED | No action needed |
+| 0.1 - 1.0 | MINOR DRIFT | Low priority updates |
+| 1.1 - 3.0 | MODERATE DRIFT | Schedule updates this session |
+| 3.1 - 5.0 | SIGNIFICANT DRIFT | Update before next feature work |
+| 5.1+ | SEVERE DRIFT | STOP — update immediately, docs are dangerous |
+
+---
+
+## Phase 4: Deep Semantic Analysis (skip with --quick)
+
+For directories with MODERATE+ drift, perform deeper investigation.
+
+### 4.1 Code-to-Doc Alignment Scan
+For each public function/class/endpoint in the directory:
+
+1. Read the implementation
+2. Read the corresponding documentation
+3. Compare: parameter names, return types, side effects, error conditions
+4. Flag any semantic mismatch
+
+### 4.2 Convention Archaeology
+When docs claim a convention but code doesn't follow it:
+
+1. `git log` the directory — did the convention change recently?
+2. Count files following vs. not following the convention
+3. Determine: is the doc wrong, or is the code drifting from convention?
+
+### 4.3 Dependency Graph Verification
+Build an actual dependency graph from import statements and compare to documented dependencies:
+
+```
+Actual: A → B → C → D
+Stated: A → B → D (missing C in the chain)
+```
+
+---
+
+## Phase 5: Missing Documentation Creation (requires --create)
+
+For Tier 1 and Tier 2 directories without documentation:
+
+### 5.1 Generic Documentation Template
+
+```markdown
+# {Directory Name}
+
+> Part of [{Project Name}]({relative path to root README or CLAUDE.md})
+
+## Purpose
+{1-3 sentences derived from actual file contents and directory name}
+
+## Tech Stack
+| Component | Value |
+|-----------|-------|
+| Language | {detected from file extensions} |
+| Framework | {detected from imports/config} |
+| Build | {detected from build files} |
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| {entry point or main file} | {description} |
+| {config file if present} | {description} |
+| {most-imported file} | {description} |
+
+## Architecture
+{How code is organized — inferred from file structure and imports}
+
+## Dependencies
+- **Depends on:** {extracted from import statements}
+- **Depended on by:** {extracted from reverse import search}
+
+## Conventions
+{Observed patterns: naming, file organization, code style}
+
+## Build & Test
+{Commands specific to this directory, if any}
+```
+
+### 5.2 Creation Rules
+- NEVER create docs in build output or generated directories
+- NEVER create docs in directories with < 3 source files (too trivial)
+- NEVER include secrets, credentials, or API keys
+- ALWAYS derive content from actual code — never guess
+- ALWAYS include relative path back to root docs
+
+---
+
+## Phase 6: Drift Repair (requires --repair)
+
+### 6.1 Auto-Fixable Drift
+These can be repaired automatically:
+
+| Drift Type | Fix |
+|-----------|-----|
+| Wrong version number | Update to match config file |
+| Wrong file count | Update to match actual count |
+| Dead file reference | Remove reference or update path |
+| Missing key file | Add to "Key Files" table |
+| Wrong test count | Update to match actual count |
+| Stale "last updated" date | Update to today |
+| Broken internal link | Fix path or remove link |
+
+### 6.2 Manual-Review Drift
+These are flagged but NOT auto-fixed:
+
+| Drift Type | Why |
+|-----------|-----|
+| Purpose statement drift | Subjective — needs human judgment |
+| Architecture description | Complex — may need redesign of docs |
+| Convention changes | Need team consensus on which is right |
+| Dependency direction disputes | Need architectural review |
+| Build command changes | Could break if wrong — verify first |
+
+### 6.3 Repair Safety Protocol
+Before modifying any file:
+1. Record the original content of lines being changed
+2. Make only minimal, targeted changes
+3. Never rewrite entire files — patch specific sections
+4. Add a comment or note indicating the drift repair date
+
+---
+
+## Phase 7: Cross-Project Synchronization (skip with --quick)
+
+### 7.1 Root Document Sync
+After all directories are walked, sync findings back to root documentation:
+
+1. **README.md** — Verify component/module counts, feature lists, directory descriptions
+2. **CLAUDE.md** — Verify architecture claims, test counts, build commands, conventions
+3. **CHANGELOG.md** — Verify latest version entry matches actual version
+
+### 7.2 Truth Cascade
+When root docs and sub-docs disagree:
+
+| Disagreement Type | Resolution |
+|-------------------|-----------|
+| Root says version X, sub says version Y | Root wins — update sub |
+| Root says build cmd X, sub says build cmd Y | Verify which works — update loser |
+| Root says A depends on B, sub-B says no | Check actual imports — update wrong doc |
+| Root lists N modules, actual count is M | Update root to M |
+| Sub has local convention not in root | Keep in sub — local conventions are sub's truth |
+
+---
+
+## Phase 8: Report Generation
+
+### 8.1 Executive Summary
+
+```markdown
+## Drift Walking Report
+
+**Project:** {name} v{version}
+**Date:** {date}
+**Directories walked:** {N}
+**Documentation coverage:** {N}% ({dirs with docs} / {total meaningful dirs})
+
+### Overall Health
+| Rating | Count | % |
+|--------|-------|---|
+| ALIGNED | N | N% |
+| MINOR DRIFT | N | N% |
+| MODERATE DRIFT | N | N% |
+| SIGNIFICANT DRIFT | N | N% |
+| SEVERE DRIFT | N | N% |
+| NO DOCS (Tier 1-2) | N | N% |
+```
+
+### 8.2 Directory Detail Table
+
+```markdown
+| Directory | Tier | Has Docs | Drift Score | Rating | Top Issue |
+|-----------|------|----------|-------------|--------|-----------|
+| src/core/ | 1 | ✅ | 0.5 | MINOR | Count drift (tests: 42 → 48) |
+| src/api/ | 1 | ❌ | — | NO DOCS | Tier 1 directory needs documentation |
+| src/utils/ | 2 | ✅ | 3.2 | SIGNIFICANT | 4 dead file references |
+| tests/ | 2 | ✅ | 0 | ALIGNED | — |
+```
+
+### 8.3 Critical Findings (CRITICAL + HIGH severity)
+
+```markdown
+### Critical Findings
+
+| ID | Directory | Check | Finding | Fix |
+|----|-----------|-------|---------|-----|
+| CF-01 | src/core/ | SD-01 | `handler.ts` referenced but was renamed to `router.ts` | Update reference |
+| CF-02 | README.md | ND-01 | States v2.1.0, actual is v2.3.1 | Update version |
+```
+
+### 8.4 Repair Log (if --repair was used)
+
+```markdown
+### Repairs Made
+
+| File | Change | Before | After |
+|------|--------|--------|-------|
+| src/core/README.md | Version update | v2.1.0 | v2.3.1 |
+| src/core/README.md | File count | 12 files | 15 files |
+| README.md | Module count | 8 modules | 10 modules |
+```
+
+### 8.5 Recommendations
+
+```markdown
+### Recommended Actions (by priority)
+
+1. **IMMEDIATE:** Fix {N} CRITICAL findings — these cause wrong AI output
+2. **THIS SESSION:** Fix {N} HIGH findings — these waste developer time
+3. **NEXT SESSION:** Create docs for {N} Tier 1 directories without documentation
+4. **BACKLOG:** Address {N} MEDIUM findings, {N} LOW findings
+```
+
+---
+
+## NEVER DO
+
+- Walk build output directories (`build/`, `dist/`, `node_modules/`, `target/`, `obj/`, `__pycache__/`, `.git/`)
+- Report PAN infrastructure files as project drift
+- Auto-fix purpose statements, architecture descriptions, or conventions without `--repair`
+- Create documentation for trivial directories (< 3 source files)
+- Include secrets, credentials, or API keys in any generated documentation
+- Guess at file contents — always read and verify
+- Modify code files — this command only touches documentation files
+- Override root documentation truth based on sub-directory claims (root is source of truth for project-wide facts)
+- Report drift without evidence (file path + line number for every finding)
+
+## ALWAYS DO
+
+- Read actual source files before claiming drift — evidence-based only
+- Include file paths and line numbers for every finding
+- Score every drifted directory with the drift score formula
+- Sort critical findings first in the report
+- Respect the truth hierarchy (code > root docs > directory docs > inline docs > external docs)
+- Walk ALL directories at the specified depth unless `--dir` constrains scope
+- Report documentation coverage percentage
+- Distinguish between "docs are wrong" and "docs are missing"
+- Provide specific, actionable fix guidance for every finding
+- Record repairs made if `--repair` is active