generate-snapshot

# Generate Codebase Snapshot This skill generates a comprehensive code health snapshot using the analysis modules in `analysis/`. ## When to Use - During planning phase to identify work items - To find refactoring hotspots (high churn + high complexity) - To track technical debt over time - Before major releases to assess code health - To identify knowledge silos (bus factor risks) ## How to Generate ```powershell # From repository root python -m analysis.snapshot --output analysis-snapshot.json ``` Add `--pretty` flag to also print the JSON to stdout. **Note:** The snapshot is written to the repository root (`analysis-snapshot.json`). This path is ignored by `.gitignore`. ## Snapshot Structure The snapshot contains these sections: ### `summary` - High-level metrics dashboard - `files_with_changes`: Number of files with git changes - `total_churn`: Total lines added + deleted - `high_complexity_files`: Count of files with high complexity - `todo_count`, `fixme_count`: Debt marker counts - `circular_dependency_count`: Architectural issues - `single_author_file_ratio`: Bus factor indicator ### `priority_hotspots` - Top 20 refactoring candidates Files sorted by `priority_score = change_count × max_complexity` ```json { "path": "src/features/terminal/terminalManager.ts", "change_count": 45, "churn": 1200, "max_complexity": 18, "priority_score": 810 } ``` High priority_score = frequently changed AND complex = prime refactoring target. ### `git_analysis` - Change patterns - `hotspots`: Most frequently changed files - `temporal_coupling`: Files that change together (hidden dependencies) - `bus_factor`: Knowledge concentration risks ### `complexity` - Code complexity metrics - `by_language.typescript`: TypeScript file metrics (max_complexity, avg_complexity, function_count) - `high_complexity_functions`: Functions with cyclomatic complexity > 10 ### `debt_indicators` - Technical debt markers - `debt_markers.by_type`: TODO, FIXME, HACK comments by type - `large_files`: Files exceeding 500 lines of code - `long_functions`: Functions exceeding 50 lines ### `dependencies` - Module coupling analysis - `circular_dependencies`: Cycles in import graph - `highly_coupled_modules`: Modules with fan-out > 10 - `hub_modules`: Modules with fan-in > 10 - `layer_violations`: Lower layers importing from higher layers ## Interpreting Results ### Priority Hotspots 1. Sort by `priority_score` descending 2. Top items = files that change often AND are complex 3. These are prime candidates for: - Breaking into smaller modules - Adding tests before changes - Simplifying complex functions ### Temporal Coupling Files with `coupling_ratio > 0.8` changing together indicate: - Hidden dependencies not visible in imports - Copy-paste code that should be shared - Features spread across unrelated files ### Knowledge Silos Files with `author_count = 1` and `change_count >= 3`: - Single point of failure for knowledge - Consider documentation or pair programming - Higher risk for bugs during that author's absence ### Circular Dependencies Any cycles in the import graph: - Indicates tight coupling - Makes testing difficult - Consider introducing interfaces or restructuring ## Example Usage in Planning ``` User: What should we work on next? Agent: Let me generate a snapshot and analyze it... [generates snapshot] Based on the snapshot: Top 3 priority items: 1. **src/features/terminal/terminalManager.ts** (priority: 810) - 45 changes, complexity 18 - High churn indicates active development area - Recommend: Split terminal concerns into separate modules 2. **src/managers/common/nativePythonFinder.ts** (priority: 540) - 30 changes, complexity 18 - Multiple FIXME markers found - Recommend: Address type guards and cache issues 3. **src/features/interpreterSelection.ts** (priority: 360) - 24 changes, complexity 15 - Temporal coupling with settings files - Recommend: Reduce coupling with settings module ```