Codebase Analysis

---
name: codebase-analysis
description: >-
  Performs deep static analysis of a codebase to generate a comprehensive, hierarchical,
  cross-referenced documentation ecosystem. Use this skill whenever the user wants to
  analyze, document, understand, or audit a codebase — even if they phrase it as
  "document my project", "analyze the repo", "generate docs", "audit technical debt",
  "understand this codebase", or "create documentation for this code".

  This skill covers: program structure extraction, architectural documentation, behavioral
  analysis, technical debt identification, dependency mapping, and migration planning.
  Always use this skill before exploring a codebase for documentation purposes — it tells
  you exactly how to approach the analysis and what to produce.

  Triggers: "analyze codebase", "document the project", "create docs", "audit tech debt",
  "understand this repo", "generate documentation", "what's the architecture", "map the code",
  "analyze dependencies", "find outdated components", "technical debt report".
---

# Comprehensive Codebase Analysis

## Objective
Transform source code into a complete, navigable documentation ecosystem that captures program structure, behavior, business logic, and architectural patterns with sufficient detail for reimplementation, maintenance, and comprehensive understanding. End with actionable next-steps recommendations based on the analysis findings.

## Summary
This skill performs deep static analysis of codebases to generate hierarchical, cross-referenced documentation covering all aspects of the system. It combines behavioral analysis, architectural documentation, and business intelligence extraction to create a comprehensive knowledge base organized for maximum usability and navigation. The skill places special emphasis on technical debt analysis, providing prominent, actionable insights on outdated components and maintenance concerns at the root level.

**This skill operates strictly on static code analysis and NEVER attempts to build or execute the code.**

## Entry Criteria
1. Java source repository with readable `.java` files (compilation not required)
2. `pom.xml` or `build.gradle` / `build.gradle.kts` accessible (Maven or Gradle project)
3. Basic file system permissions for analysis
4. Sufficient storage for comprehensive documentation output
5. NO compilation, building, or execution of code required or permitted
6. NO running of tests within the codebase is permitted

## IMPORTANT: Exclusions
Exclude these directories during analysis to focus on actual application code:

**Package/dependency cache:** .gradle, .m2, .ivy2

**Build output:** build, target, out, output, bin, obj, release, releases, compiled

**Generated code/docs:** generated, auto-generated, autogenerated, gen, .gen, docs, documentation, javadoc, apidoc, swagger, openapi

**Version control/tooling:** .git, .svn, .hg, .bzr, .github, .gitlab, .circleci, .idea, .vscode, .vs

---

## Implementation Steps

### Step 1: Project Initialization and Structure Analysis

#### 1.1 Create Documentation Structure

Create all documentation in the project root under `JadeDocumentation/`.

**If `JadeDocumentation/` already exists: UPDATE existing files rather than recreating.**

If it does not exist, run:
```bash
mkdir -p JadeDocumentation/{architecture,behavior,diagrams/{structural,behavioral,architecture},technical-debt,reference,analysis,migration,specialized}
touch JadeDocumentation/README.md
touch JadeDocumentation/project-overview.md
touch JadeDocumentation/technical-debt-report.md
touch JadeDocumentation/architecture/{system-overview,components,dependencies,patterns}.md
touch JadeDocumentation/behavior/{business-logic,workflows,decision-logic,error-handling}.md
touch JadeDocumentation/technical-debt/{summary,outdated-components,maintenance-burden,remediation-plan}.md
touch JadeDocumentation/reference/{program-structure,interfaces,data-models,api-reference}.md
touch JadeDocumentation/analysis/{code-metrics,complexity-analysis,dependency-analysis,security-patterns}.md
touch JadeDocumentation/migration/{component-order,test-specifications,validation-criteria}.md
```

#### 1.2 Assess Codebase Size

Count Java source files only — exclude compiled bytecode, build artifacts, and generated sources.

```bash
find . -type f -name '*.java' \! -path '*/.gradle/*' \! -path '*/.m2/*' \! -path '*/.ivy2/*' \! -path '*/build/*' \! -path '*/target/*' \! -path '*/out/*' \! -path '*/output/*' \! -path '*/bin/*' \! -path '*/obj/*' \! -path '*/release/*' \! -path '*/releases/*' \! -path '*/compiled/*' \! -path '*/generated/*' \! -path '*/auto-generated/*' \! -path '*/autogenerated/*' \! -path '*/gen/*' \! -path '*/.gen/*' \! -path '*/javadoc/*' \! -path '*/.git/*' \! -path '*/.github/*' \! -path '*/.gitlab/*' \! -path '*/.circleci/*' \! -path '*/.idea/*' \! -path '*/.vscode/*' -exec cat {} + 2>/dev/null | wc -l
```

If the codebase contains **more than 1,000,000 lines of code**, it is a **large codebase**. If so, prepend this disclaimer to every file in `JadeDocumentation/` (use exactly as written):
```bash
for f in $(find JadeDocumentation -name '*.md' -type f); do printf '> ⚠️ **Large Codebase Notice**: This repository was identified as a large codebase. Some sections may contain higher-level summaries rather than exhaustive detail. For deeper analysis, consider running the analysis on individual modules or sub-projects separately.\n\n' | cat - "$f" > "$f.tmp" && mv "$f.tmp" "$f"; done
```

---

### Step 2: Comprehensive Code Analysis

#### 2.1 Project Discovery and Inventory
- Read existing `JadeDocumentation/` files if they exist to get context
- Scan all `.java` source files; identify frameworks, Spring modules, and third-party integrations
- Extract project metadata from `pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, and `gradle.properties`
- Document directory and package structure

#### 2.2 Extract Program Structure
- Document classes, interfaces, functions, and modules
- Map inheritance hierarchies and composition relationships
- Extract method signatures, parameters, and return types
- Identify design patterns and architectural styles

#### 2.3 Analyze Dependencies and Relationships
- Map internal component dependencies (package-to-package, class-to-class)
- Identify ALL external library usage with exact versions from `pom.xml` / `build.gradle` / `build.gradle.kts`
- Create dependency graphs with criticality analysis
- Document data flow between components
- Analyze threading and concurrency patterns
- Document build tool dependencies (Maven plugins, Gradle plugins)
- Identify transitive dependencies where relevant
- **Identify technical debt and outdated components**

#### 2.4 Extract Behavioral Information (Application Code Only)
- **Document ONLY workflows that represent core application business logic**
- **EXCLUDE build/test/lint/publish workflows from workflow documentation**
- Document control flow and execution paths for business operations
- Map conditional logic and branching patterns in application code
- Extract business rules and validation logic
- Identify state machines and lifecycle patterns
- Document exception handling and error recovery

---

### Step 3: Technical Debt Analysis and Documentation

#### 3.1 Root-Level Technical Debt Summary

Create `technical-debt-report.md` at the root level for maximum visibility.

**At the TOP of `technical-debt-report.md`, include the Next Steps Recommendation section using EXACTLY this format:**

```markdown
## 🎯 Next Steps Recommendation

### Recommended Actions

[Brief 2-3 sentence summary of the most impactful next steps based on the codebase analysis. Focus on the highest-severity findings — e.g., EOL runtimes, critical dependency upgrades, or architectural concerns that pose the greatest risk.]
```

Then include:
- Executive summary of technical debt findings
- Prioritized list of critical issues with severity ratings (High/Medium/Low)
- **Always prioritize findings in this fixed order: (1) EOL/deprecated/outdated runtimes and frameworks, (2) outdated dependencies, (3) code quality and architectural issues**
- Navigation links to detailed technical debt sections
- Visual indicators for severity and impact

#### 3.2 Dedicated Technical Debt Section

Organize detailed findings in `technical-debt/`:
- `summary.md`: Overview of all technical debt findings
- `outdated-components.md`: Detailed analysis of obsolete components
- `maintenance-burden.md`: Areas requiring significant maintenance attention
- `remediation-plan.md`: Prioritized action items

#### 3.3 Comprehensive Technical Debt Identification

**Outdated Components Analysis:**
- Analyze language/runtime versions and EOL status
- Identify deprecated frameworks and libraries with exact versions
- Document ALL outdated dependencies (not just a subset)
- Include build tool versions (Gradle, Maven)
- Document deprecated algorithms or cryptographic methods
- Assess coding conventions and standards compliance
- Prioritize by risk level:
  - **High** — Outdated/EOL/deprecated runtimes and frameworks
  - **Medium** — Outdated runtime/production dependencies (libraries used at runtime)
  - **Low** — Outdated developer/build dependencies (test frameworks, linters, formatters, build tools, type definitions, dev-only tooling)

**Additional Technical Debt:**
- Detect complex or unmaintainable code patterns
- Detect performance bottlenecks and architectural issues

#### 3.4 Actionable Remediation Recommendations
- Provide specific upgrade paths for outdated components
- Suggest architectural improvements with concrete examples
- Prioritize issues by risk level (High/Medium/Low)
- Document specific requirements for addressing each debt item
- Reference industry best practices and migration patterns

---

### Step 4: Generate Remaining Documentation Content

Populate all remaining files with analysis results from Step 2. Every file must have meaningful content — focus on completeness over verbosity.

#### 4.1 architecture/
- `system-overview.md`: High-level system architecture, technology stack, deployment model, and key architectural decisions
- `components.md`: Major system components, their responsibilities, interfaces, and interactions
- `dependencies.md`: Internal component dependencies, external libraries/services, and dependency graphs with version information
- `patterns.md`: Architectural patterns used (MVC, microservices, event-driven, etc.), design patterns, and anti-patterns identified

#### 4.2 behavior/ *(Early Access)*

Prepend this disclaimer to every file in `JadeDocumentation/behavior/`:

**Standard disclaimer:**
```bash
for f in $(find JadeDocumentation/behavior -name '*.md' -type f); do printf '> ⚠️ **Early Access**: Behavior documentation is in early access. Please review critically.\n\n' | cat - "$f" > "$f.tmp" && mv "$f.tmp" "$f"; done
```

**Large codebase disclaimer (>1M LOC):**
```bash
for f in $(find JadeDocumentation/behavior -name '*.md' -type f); do printf '> ⚠️ **Early Access**: Behavior documentation is in early access. For large codebases, behavior analysis produces more detailed and accurate results when run against individual modules or components separately. Please review critically.\n\n' | cat - "$f" > "$f.tmp" && mv "$f.tmp" "$f"; done
```

Files:
- `business-logic.md`: Extracted business rules and processes. **Document ALL block-level/component-level business rules for every major class/module — do not selectively omit components**
- `workflows.md`: High-level process flows and user journeys. **ONLY application-level workflows. EXCLUDE build/test/lint/CI/CD/publish workflows. Define one workflow per top-level public entry point or primary class — utility classes and helper components should be documented within the workflow of their caller, not as separate workflows**
- `decision-logic.md`: Decision trees and business rules. **Document ALL decision points found in application code — do not add risk assessments or editorial analysis that may vary**
- `error-handling.md`: Exception patterns and recovery

#### 4.3 reference/
- `program-structure.md`: Complete structural hierarchy
- `interfaces.md`: All public APIs and contracts
- `data-models.md`: Type definitions and relationships
- `modules.md`: Module organization and dependencies

#### 4.4 analysis/
- `code-metrics.md`: Complexity measurements and quality indicators
- `dependency-analysis.md`: Internal and external dependency mapping
- `security-patterns.md`: Code-level security implementations
- `tech-debt.md`: Comprehensive technical debt assessment

#### 4.5 diagrams/ (text-based for universal readability)

If large codebase (>1M LOC), prepend the large codebase disclaimer to files under `diagrams/`.

**structural/**
- Component diagrams showing system structure
- Class/type diagrams with relationships
- Package/module dependency graphs
- Deployment architecture diagrams

**behavioral/**
- Sequence diagrams for key interactions
- Activity diagrams for business processes
- State machine diagrams for complex entities
- Data flow diagrams showing information movement

**architecture/**
- System context and boundaries
- Integration patterns and external connections
- Service maps and communication flows
- Security boundaries and access patterns

#### 4.6 specialized/

If large codebase (>1M LOC), prepend the large codebase disclaimer to files under `specialized/`.

Include only what applies to the codebase:
- Database schemas and query patterns (if detected)
- API documentation with request/response examples (if detected)
- UI component documentation (if detected)
- Message queue and event patterns (if detected)
- Infrastructure and deployment configurations (if detected)

#### 4.7 migration/
- `component-order.md`: Component migration order based on dependencies
- `test-specifications.md`: Test case specifications for validation
- `validation-criteria.md`: Criteria for validation of a successful migration

---

### Step 5: Cross-Reference and Navigation
- Link all documentation files bidirectionally
- Reference source code locations with line numbers
- Create searchable index of all components
- Generate table of contents for each document

---

## Constraints and Guardrails

1. **No execution** — Strictly static code analysis. No building, compiling, executing code, or running tests at any stage.
2. **Qualitative terms only** — Express priority, complexity, effort, and urgency using ONLY qualitative terms:
   - ✅ CORRECT: "Critical priority", "High complexity", "Immediate action needed", "Significant effort required"
   - ❌ FORBIDDEN: "2 weeks", "3 days", "1-2 hours", "X person-months", "Timeline: 2 weeks"
3. **Severity scale** — Use ONLY: **High**, **Medium**, **Low**
4. **No empty files** — Every file must have meaningful content
5. **Output location** — Create all documentation in `JadeDocumentation/` in the project root
6. **Update, don't recreate** — If `JadeDocumentation/` already exists, update files in place
7. **Recommendation format** — The top of `technical-debt-report.md` MUST contain the Next Steps Recommendation section in the exact format specified

---

## Validation / Exit Criteria

All validation must be performed on static documentation output only — never on executed code.

### PHASE 1: Validation Checks (All must pass)

1. **Structure**: All required files exist in `JadeDocumentation/` with meaningful content (no empty files or folders)
2. **Next Steps Recommendation**: Appears at top of `JadeDocumentation/technical-debt-report.md` in the exact format from Step 3.1
3. **Architecture Documentation**: Files in `architecture/` (system-overview.md, components.md, dependencies.md, patterns.md) with system design and architectural patterns
4. **Behavioral Documentation**: Files in `behavior/` (business-logic.md, workflows.md, decision-logic.md, error-handling.md) with business rules and process flows
5. **Diagrams**: Text-based diagrams in `diagrams/` subdirectories (structural/, behavioral/, architecture/) for visual documentation
6. **Reference Documentation**: Files in `reference/` (program-structure.md, interfaces.md, data-models.md, api-reference.md) with all classes, interfaces, and public methods documented
7. **Analysis Documentation**: Files in `analysis/` (code-metrics.md, complexity-analysis.md, dependency-analysis.md, security-patterns.md) with quality metrics
8. **Migration Documentation**: Files in `migration/` (component-order.md, test-specifications.md, validation-criteria.md) with migration planning
9. **Technical Debt Documentation**: Files in `technical-debt/` (summary.md, outdated-components.md, maintenance-burden.md, remediation-plan.md) with severity ratings and prioritized action items
10. **Navigation**: Master `README.md` provides clear navigation to all documentation sections with cross-references functional between files

### PHASE 2: Completion

Once all Phase 1 checks pass, report to the user:
- Summary of what was documented
- Key technical debt findings and their severity
- Recommended next steps from `technical-debt-report.md`
- Location of the generated documentation (`JadeDocumentation/`)

The analysis produces a comprehensive, navigable documentation ecosystem that serves as both a complete reference and a migration/maintenance guide, enabling deep understanding and accurate reimplementation of any codebase.