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

Java source repository with readable .java files (compilation not required)
pom.xml or build.gradle / build.gradle.kts accessible (Maven or Gradle project)
Basic file system permissions for analysis
Sufficient storage for comprehensive documentation output
NO compilation, building, or execution of code required or permitted
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:

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.

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):

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:

## 🎯 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:

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):

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

No execution — Strictly static code analysis. No building, compiling, executing code, or running tests at any stage.
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"
Severity scale — Use ONLY: High, Medium, Low
No empty files — Every file must have meaningful content
Output location — Create all documentation in JadeDocumentation/ in the project root
Update, don't recreate — If JadeDocumentation/ already exists, update files in place
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)

Structure: All required files exist in JadeDocumentation/ with meaningful content (no empty files or folders)
Next Steps Recommendation: Appears at top of JadeDocumentation/technical-debt-report.md in the exact format from Step 3.1
Architecture Documentation: Files in architecture/ (system-overview.md, components.md, dependencies.md, patterns.md) with system design and architectural patterns
Behavioral Documentation: Files in behavior/ (business-logic.md, workflows.md, decision-logic.md, error-handling.md) with business rules and process flows
Diagrams: Text-based diagrams in diagrams/ subdirectories (structural/, behavioral/, architecture/) for visual documentation
Reference Documentation: Files in reference/ (program-structure.md, interfaces.md, data-models.md, api-reference.md) with all classes, interfaces, and public methods documented
Analysis Documentation: Files in analysis/ (code-metrics.md, complexity-analysis.md, dependency-analysis.md, security-patterns.md) with quality metrics
Migration Documentation: Files in migration/ (component-order.md, test-specifications.md, validation-criteria.md) with migration planning
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
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.

codebase-analysis

SKILL.md.claude/skills/codebase-analysis/SKILL.md