Explain My Code

Explain My Code

Analyze a complete code repository as a senior software architect and produce one self-contained, production-grade Markdown document that lets anyone new to the project fully understand the system with no handover meetings or outside help.

When to Use

• User asks to document, explain, or map a codebase or repository
• User wants an onboarding document for people new to the project
• User wants a system/architecture overview with Mermaid diagrams
• User points at a repo and asks "what does this do / how does it work" AND wants it captured as a written document, not a one-line reply

Do NOT use for bug-finding code review, refactoring plans, or diagram-only output (see negative boundary in description).

Co-Load Precedence

When co-loading with codebase-to-mermaid: that skill owns standalone diagram generation; this skill embeds diagrams inside the full document. When co-loading with refactoring-analyst: that skill owns refactor planning; this skill only describes the system (Section 13 suggests improvements at a high level, it does not plan the refactor). When co-loading with a code-review skill (e.g. wordpress-architect-review): review owns defect findings; this skill owns architecture explanation (Section 12 lists observations/risks but does not perform line-level review).

Workflow

Phase 1: SCOPE THE TARGET

1. Determine the repository root. Default to the current working directory. If the user named a path, use that.
2. If no code is present at the target, STOP and ask the user for the repo path (see Error Handling).
3. Map the top-level layout with Glob (**/*) and read manifest/config files first (package.json, pom.xml, go.mod, requirements.txt, Cargo.toml, *.csproj, Dockerfile, compose files, CI configs).

Phase 2: IDENTIFY FOUNDATIONS

1. Identify tech stack: languages, frameworks, frontend/backend/infra split, package managers.
2. Classify architecture: monolith vs microservices vs modular.
3. Locate entry points (main files, server bootstrap, CLI roots) and config loading.

Phase 3: TRAVERSE SYSTEMATICALLY

1. Walk folder-by-folder, service-by-service, module-by-module.
2. Infer design patterns (MVC, Clean, Hexagonal, Factory, Observer, etc.) - record where and why each is used.
3. Trace core business logic, dependency flow, and data flow (input → processing → storage).
4. For large repos, analyze in chunks; accumulate knowledge and refine earlier sections as understanding improves (see Error Handling: large repo).

Phase 4: WRITE THE DOCUMENT

1. Produce ALL 13 sections in the order under Output Format. Do not skip any section.
2. Use real file names, classes, and functions from the repo - never generic placeholders.
3. Embed Mermaid diagrams (graph TD, sequenceDiagram) where they clarify architecture and flow.
4. Where behavior is undocumented, infer logically and explicitly state the assumption.

Phase 5: VERIFY BEFORE DELIVERY

1. Confirm every one of the 13 sections is present and non-shallow.
2. Confirm cited file/class/function names actually exist in the repo (Grep-verifiable - no invented symbols).
3. Confirm Mermaid blocks are syntactically valid.
4. Write the result to CODEBASE_DOCUMENTATION.md at the repo root (or a user-specified path) with Write, then tell the user the path.

Output Format

Single Markdown file, default name CODEBASE_DOCUMENTATION.md, containing these sections in order:

1. Project Overview - purpose, high-level functionality, key use cases
2. System Architecture - explanation, monolith/microservices/hybrid, Mermaid graph TD diagram
3. Repository Structure - folder hierarchy, role of each major directory, module responsibilities
4. Tech Stack & Dependencies - languages, frameworks, external libraries, package managers, dependency graph if possible
5. Core Components / Services - per component: responsibility, key classes/functions, interactions
6. Application Flow - 6.1 Startup flow (entry point, init sequence, config, DI); 6.2 Request/execution flow; 6.3 Auth flow if applicable; 6.4 Data flow; include Mermaid sequenceDiagram
7. Key Design Patterns - patterns used, where and why
8. Database & Models - schema overview, ORM usage, entity relationships
9. External Integrations - APIs, third-party services, queues, caches
10. Configuration & Environment - env vars, config files, build configs
11. Build & Deployment - build steps, scripts, CI/CD if present
12. Observations & Risks - code smells, tight coupling, scalability concerns, missing abstractions
13. Suggestions for Improvement - refactoring ideas, performance, architecture alternatives

Constraints (from source prompt, preserved):

• Be precise and technical; avoid generic explanations.
• Do NOT give shallow summaries or skip flows/architecture.
• Do NOT assume undocumented behavior without stating the reasoning.
• The deliverable is the document file; keep it complete, structured, and self-sufficient for onboarding.

Error Handling

No repository / empty target: Ask the user for the repo path. Do not fabricate documentation for code that was not read.

Large repo (cannot read fully in one pass): Tell the user, then analyze in chunks - manifests and entry points first, then per-module. Accumulate findings and refine earlier sections. Note any directories sampled rather than fully read.

Ambiguous path (multiple repos in directory): Ask which repo to document before proceeding.

Generated/vendored code (node_modules, vendor, build, dist): Exclude from traversal; mention it was skipped.

Section genuinely not applicable (e.g., no database): Keep the heading, state "Not applicable - ". Do not silently drop a section.

Quality Gates

• All 13 sections present and substantive (no shallow summaries)
• Cited file/class/function names verified to exist in the repo (accuracy gate)
• At least one architecture diagram and one flow diagram in valid Mermaid syntax (format gate)
• Assumptions about undocumented behavior are explicitly labeled
• Output written to a .md file and its path reported to the user

Examples

Standard case: User runs the skill in a Node/Express + React repo. The skill reads package.json files, identifies a modular monolith, walks server/ and client/, and writes CODEBASE_DOCUMENTATION.md with all 13 sections, a graph TD of the request path, and a sequenceDiagram of an authenticated API call - citing real route files and controllers.

Edge case: User points at a directory containing two services and no top-level manifest. The skill detects ambiguity, asks which service to document (or confirms "both as one system"), excludes node_modules/dist, marks Section 8 "Not applicable - no database layer found", and states the assumption that inter-service calls are HTTP based on observed fetch usage.