explain-my-code

name	explain-my-code
description	This skill should be used when the user asks to "document this codebase", "explain my code", "generate architecture docs", "write an onboarding doc", "analyze this repo", or wants self-contained technical documentation produced from source. Signal tokens include "codebase", "repo", "architecture diagram", "onboarding", "system overview", "tech stack", ".md doc". Casual phrasings (when paired with an onboarding/documentation intent) include "help a new dev understand this whole codebase", "write up how this project works", "map out this code into a doc". Also trigger when the user points at a repository and asks for a single Markdown write-up with Mermaid diagrams. Do NOT use for a quick one-line "what does this do" answer, for line-by-line code review or bug-finding (that is wordpress-architect-review or a review skill), for refactoring or modernization plans (that is refactoring-analyst), or for producing diagrams alone (that is codebase-to-mermaid).
version	1.0.0

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.