oh-my-skills/skills/codebase-analysis/SKILL.md

---

name: codebase-analysis

description: Analyze, understand, document, map, explain, reverse-engineer, or discover the architecture of an existing codebase or repository without modifying it.

Codebase Analysis & Architecture Discovery

Purpose

Analyze an existing codebase to determine what the software does, how it is structured, how its main components interact, and how it behaves at runtime.

The primary goal is to produce a technical report that allows a developer unfamiliar with the repository to understand the system without requiring an exhaustive manual review of every file.

Scope

This skill is for analysis and architecture discovery only.

Do not:

• modify source files;
• refactor code;
• rewrite code;
• fix bugs;
• perform a security audit;
• perform a code quality review;
• recommend architectural changes;
• suggest optimizations;
• generate patches;
• create commits.

Do those only when explicitly requested by the user.

The analysis must distinguish between:

• verified facts;
• reasonable inferences;
• unknown or unverified information.

Never present an inference as a verified fact.

Core Objective

At the end of the analysis, answer this question:

If this codebase were handed to a developer who had never seen it before, would the report allow them to understand what the software does and how it works?

Analysis Strategy

Do not read every file indiscriminately.

Use a progressive discovery process:

1. Build a high-level repository map.
2. Identify technologies, frameworks, manifests, and configuration.
3. Locate application entry points.
4. Locate routing, controllers, services, modules, or equivalent architectural boundaries.
5. Identify persistence mechanisms and data models.
6. Identify external APIs and integrations.
7. Trace the most important runtime flows.
8. Inspect deployment, build, and operational configuration.
9. Deep-dive into important modules only when needed.
10. Consolidate findings into a structured report.

For large repositories, analyze by subsystem or directory and progressively merge findings.

Avoid repeatedly reading files that do not add meaningful information.

Phase 1: Repository Inventory

Inspect the repository structure and identify:

• top-level directories;
• source directories;
• application packages;
• libraries;
• tests;
• configuration directories;
• scripts;
• documentation;
• build artifacts;
• generated files;
• infrastructure files;
• dependency manifests.

Identify files that provide high information value, such as:

• README*
• package.json
• composer.json
• pyproject.toml
• requirements.txt
• Cargo.toml
• go.mod
• .csproj
• .sln
• pom.xml
• build.gradle
• Makefile
• Dockerfile
• compose files
• CI configuration
• environment examples
• application configuration
• router definitions
• dependency injection configuration

Do not assume the README accurately represents the implementation. Verify important claims against the code.

Phase 2: Technology Stack

Determine the technologies used by the project.

Include where applicable:

• programming languages;
• runtimes;
• frameworks;
• frontend frameworks;
• backend frameworks;
• database systems;
• ORMs;
• caches;
• queues;
• messaging systems;
• build tools;
• package managers;
• testing frameworks;
• infrastructure tooling;
• web servers;
• container tooling;
• CI/CD systems.

Separate direct evidence from inferred technologies.

Phase 3: Software Purpose

Determine what the software actually does.

Use evidence from:

• entry points;
• routes;
• controllers;
• services;
• domain models;
• user-facing components;
• API endpoints;
• commands;
• background jobs;
• integration code.

Describe:

• the primary purpose of the system;
• its main users or consumers when identifiable;
• the main functional areas;
• the major operations it performs.

Do not derive the purpose from filenames alone when implementation evidence is available.

Phase 4: Entry Points

Locate the principal execution entry points.

Examples include:

• web application bootstrap files;
• HTTP server startup;
• CLI commands;
• worker processes;
• scheduled jobs;
• framework bootstrap code;
• frontend application roots;
• serverless handlers;
• event consumers.

For each important entry point, explain:

• how execution begins;
• what initialization occurs;
• which major components are loaded;
• where control flows next.

Phase 5: Repository Structure

Describe the logical repository structure rather than merely listing directories.

For each important area, explain its responsibility.

Example:

src/
  controllers/    HTTP request handling
  services/       Application logic
  repositories/   Persistence abstraction
  models/         Domain/data models

Ignore directories that are purely generated, vendored, cached, or otherwise irrelevant unless they affect runtime behavior.

Phase 6: Architecture Discovery

Reconstruct the architecture from the implementation.

Identify where applicable:

• layered architecture;
• MVC;
• modular monolith;
• microservices;
• service-oriented architecture;
• hexagonal architecture;
• clean architecture;
• event-driven architecture;
• plugin architecture;
• client/server architecture;
• frontend/backend separation;
• monorepo structure.

Do not force the repository into a known architectural pattern.

If no clear formal architecture exists, describe the actual observed structure.

Document:

• architectural layers;
• subsystem boundaries;
• package boundaries;
• communication paths;
• dependency directions;
• ownership of major responsibilities.

Phase 7: Main Components

Identify the major components or modules.

For each important component, document:

• responsibility;
• important files or directories;
• dependencies;
• inputs;
• outputs;
• interactions with other components.

Focus on components that materially affect system behavior.

Phase 8: Dependencies

Analyze both external and internal dependencies.

External Dependencies

Identify important libraries and services that materially influence the application.

Do not enumerate every dependency unless useful.

Explain what the significant dependencies are used for.

Internal Dependencies

Describe relationships between:

• modules;
• packages;
• services;
• controllers;
• repositories;
• frontend features;
• shared libraries.

Highlight central components that many other areas depend on.

Phase 9: Runtime Flows

Trace the most important execution flows through the application.

Examples:

• HTTP request lifecycle;
• user login;
• API request;
• frontend action to backend request;
• database write;
• background processing;
• file upload;
• message consumption;
• scheduled execution.

For each flow, show the sequence of important components.

Example:

HTTP Request
  -> Router
  -> Controller
  -> Service
  -> Repository
  -> Database
  -> Response

Only include flows supported by the implementation.

Phase 10: Data and Persistence

Identify how data is stored and accessed.

Document where applicable:

• databases;
• schemas;
• models;
• entities;
• repositories;
• ORM usage;
• migrations;
• cache layers;
• files;
• object storage;
• session storage.

Describe how data flows between the application and persistence layer.

Do not perform a database quality assessment unless explicitly requested.

Phase 11: APIs and External Integrations

Identify external systems used by the codebase.

Examples:

• REST APIs;
• GraphQL APIs;
• payment providers;
• authentication providers;
• email services;
• cloud services;
• storage services;
• third-party SDKs;
• message brokers;
• webhooks.

For each meaningful integration, document:

• its purpose;
• where it is called;
• the direction of communication;
• how configuration or credentials are supplied, without exposing secrets.

Never include actual secret values in the report.

Phase 12: Authentication and Authorization

If present, identify:

• authentication mechanism;
• authorization mechanism;
• session handling;
• token handling;
• middleware;
• guards;
• roles;
• permissions.

Describe how the mechanism works based on implementation evidence.

This is architectural documentation, not a security assessment.

Phase 13: Configuration

Identify important configuration sources:

• environment variables;
• configuration files;
• runtime flags;
• feature flags;
• secrets references;
• framework configuration.

Explain how configuration reaches the application.

Do not expose secret values.

Phase 14: Build and Deployment

Determine how the project is built and run.

Identify where applicable:

• development startup process;
• production startup process;
• frontend build;
• backend build;
• package scripts;
• build pipelines;
• container configuration;
• server configuration;
• CI/CD;
• deployment manifests.

Describe only what can be established from the repository.

Phase 15: Background Processes

Identify asynchronous or non-request-driven execution such as:

• queues;
• workers;
• cron jobs;
• scheduled tasks;
• event listeners;
• message consumers;
• batch processes.

Explain how they are triggered and what they do.

Phase 16: Testing and Tooling

Identify:

• unit tests;
• integration tests;
• end-to-end tests;
• test frameworks;
• linting;
• formatting;
• static analysis;
• developer scripts.

Describe how these fit into the repository.

Do not evaluate test quality unless explicitly requested.

Phase 17: Important Files

Produce a concise list of the files that are most useful for understanding the application.

For each file, explain why it matters.

Prioritize files such as:

• application bootstrap;
• routing;
• dependency configuration;
• main services;
• domain models;
• persistence setup;
• central configuration;
• build/deployment configuration.

Avoid producing a large unfiltered file list.

Large Codebase Strategy

For large repositories:

1. inspect the top-level structure;
2. identify independent subsystems;
3. analyze each subsystem separately;
4. maintain a running architectural map;
5. trace cross-subsystem dependencies;
6. merge findings only after subsystem analysis;
7. revisit central files when new evidence changes the interpretation.

Prefer targeted exploration over exhaustive file reading.

When token or context limits matter, prioritize:

1. manifests and configuration;
2. entry points;
3. routing;
4. dependency wiring;
5. core services;
6. persistence;
7. major domain modules;
8. integration boundaries;
9. tests;
10. utility code.

Evidence Rules

Every important conclusion must be supported by repository evidence.

Classify conclusions as follows.

Verified

Directly established from code, configuration, dependency manifests, or other repository artifacts.

Inferred

Strongly suggested by the implementation but not conclusively established.

State why the inference was made.

Unknown

Information that cannot be determined from the available repository.

Do not invent missing behavior.

When evidence conflicts, explicitly describe the conflict.

Reporting Rules

The final report must:

• be concise enough to remain useful;
• be detailed enough to explain the architecture;
• describe actual observed behavior;
• avoid speculative claims;
• avoid recommendations unless requested;
• avoid code review commentary;
• avoid security findings unless requested;
• avoid refactoring suggestions;
• identify uncertainty explicitly.

Use diagrams in text form when they improve understanding.

Example:

Browser
   |
   v
Frontend SPA
   |
   v
HTTP API
   |
   v
Application Services
   |
   +----> External API
   |
   v
Database

Final Report Format

Use the following structure when applicable.

Codebase Analysis & Architecture Discovery

1. Executive Summary

Summarize the system, its purpose, and its high-level architecture.

2. What This Software Does

Explain the observable functional purpose of the application.

3. Technology Stack

List the significant technologies and their roles.

4. Repository Structure

Explain the important directories and logical organization.

5. Entry Points

Document how the major execution paths begin.

6. Architecture

Describe the observed architecture, layers, boundaries, and communication paths.

7. Main Components

Explain the responsibilities and relationships of major components.

8. Dependencies

Describe important external and internal dependencies.

9. Runtime Flows

Trace the most important application flows.

10. Data & Persistence

Explain storage, models, repositories, databases, caches, and data flow.

11. APIs & External Integrations

Document meaningful external systems and integration boundaries.

12. Authentication & Authorization

Describe authentication and authorization architecture when present.

13. Configuration

Explain the important configuration mechanisms.

14. Build & Deployment

Describe how the software is built, started, and deployed.

15. Background Processes

Describe workers, queues, cron jobs, listeners, and scheduled processes.

16. Testing & Tooling

Describe testing infrastructure and developer tooling.

17. Important Files

List the most informative files and why they matter.

18. Architectural Patterns

Identify architectural patterns only when supported by clear evidence.

19. Verified Facts

Summarize the most important conclusions directly established from the repository.

20. Inferences

List conclusions that are likely but not fully verified, including the evidence behind them.

21. Unknowns

List important aspects that could not be determined from the repository.

Completion Criteria

The analysis is complete when the report makes it possible to understand:

• what the software does;
• how execution starts;
• how the repository is organized;
• which components are central;
• how components communicate;
• how data moves through the system;
• where data is persisted;
• which external systems are involved;
• how the application is configured;
• how it is built and deployed;
• which conclusions are verified;
• which conclusions remain uncertain.

Do not continue exploring low-value files once these questions are sufficiently answered.