code-analyzer

CRITICAL RULES

1. Never assume context that doesn't exist. Only report what the code explicitly shows.
2. Never invent dependencies. If a dependency isn't visible in imports, configs, or code, don't add it.
3. If information is missing, say so explicitly. Document unknowns as unknowns, not guesses.
4. Never copy full source code into the report. Explain how the code works — don't reproduce it.

• Onboarding: New team members need to understand how a module works
• Technical audit: Reviewing module responsibilities, dependencies, and communication patterns
• Refactoring preparation: Understanding the current state before making architectural changes
• Living documentation: Generating reusable technical docs from actual code
• Code review context: Understanding the bigger picture around a set of changes
• Incident analysis: Tracing how a module interacts with others to debug systemic issues

• Internal module behavior and execution flow
• Function/class responsibility mapping
• State management and error handling patterns
• Dependency identification (internal and external)

• Architectural pattern detection (MVC, Clean Architecture, Hexagonal, etc.)
• Module boundary and responsibility analysis
• Coupling and cohesion evaluation
• Design principle adherence (SOLID, DRY, etc.)

• Inter-module communication (sync/async)
• API surface analysis (what a module exposes and consumes)
• Event-driven patterns (pub/sub, event emitters, message queues)
• Shared state and data flow analysis

• Structured markdown reports
• Mermaid diagrams (flowcharts, sequence, class, C4)
• Executive summaries for non-technical stakeholders
• Detailed technical breakdowns for engineers

/src/modules/orders

v1

v2

v3

• "Analyze the module at

  /src/modules/payments

  "
• "Explain how

  /apps/core/auth

  works and how it connects to other modules"
• "Do a v3 analysis of

  /src/services/notification-service.ts

  "

{output_dir}

1. Infer the project name from the current directory name or git repository name
2. Set

   {output_dir}

   =

   .agents/staging/code-analyzer/{project-name}/

3. Create the directory if it doesn't exist
4. Present the resolved path to the user before proceeding

IMPORTANT: Every

{output_dir}

reference in this skill depends on this resolution.

1. Frontmatter: Every

   .md

   file includes the universal frontmatter schema (title, date, updated, project, type, status, version, tags, changelog, related)
2. Types: Use

   technical-report

   for REPORT.md,

   refactor-plan

   for REFACTOR.md
3. Wiki-links: When both REPORT.md and REFACTOR.md exist, cross-reference with

   [[REPORT]]

   /

   [[REFACTOR]]

4. Referencias: Every document ends with

   ## Referencias

   listing related analysis documents
5. Metrics: Use

   | Metric | Before | After | Delta | Status |

   format for code quality metrics, complexity scores, and coverage data
6. IDs: Use D- for debt items in refactor plans
7. Bidirectional: If REFACTOR.md references REPORT.md, REPORT.md must reference REFACTOR.md

1. Read the target path — identify all files, directories, and entry points
2. Detect the language and framework from file extensions, imports, and config files
3. Identify the module boundary (what's inside vs. outside the module)
4. List all files that belong to the module

1. Identify the module's main responsibilities — what does it do?
2. Map key functions/classes and their roles
3. Trace the primary execution flow — entry point to output
4. Analyze state management — how data flows and transforms
5. Analyze error handling — how failures are managed
6. List internal dependencies (other modules in the same project)
7. List external dependencies (third-party libraries, APIs, services)

1. Identify what the module consumes (imports, API calls, events listened to)
2. Identify what the module exposes (exports, API endpoints, events emitted)
3. Classify communication types: synchronous (function calls, HTTP) vs. asynchronous (events, queues, WebSockets)
4. Identify shared state (global stores, shared databases, caches)

1. Write the report following the Output Structure (see below)
2. Generate Mermaid diagrams for visual understanding
3. Save the report to

   {output_dir}/technical/module-analysis/{module-name}/

4. Add

   ## Referencias

   section at the end of the report (link to REFACTOR.md if v3, link to any other analysis documents for the same module)

1. Identify code smells and architectural issues
2. Suggest specific, actionable improvements
3. Rate each recommendation by impact and effort
4. Prioritize recommendations
5. Add

   ## Referencias

   section linking back to

   [[REPORT]]

   and any related analysis documents

{output_dir}/technical/module-analysis/
└── {module-name}/
    ├── REPORT.md              # Main technical report
    └── REFACTOR.md            # Refactoring recommendations (v3 only)

• /src/modules/OrderService

  →

  {output_dir}/technical/module-analysis/order-service/

• /apps/core/payments

  →

  {output_dir}/technical/module-analysis/payments/

• /src/services/notification-service.ts

  →

  {output_dir}/technical/module-analysis/notification-service/

• REPORT.md — Technical analysis report template with Executive Summary, Technical Analysis, Module Communication, Technical Diagrams, Metrics, and Referencias sections
• REFACTOR.md — Refactoring recommendations template (v3 only) with Code Smells, Recommendations, Priority Matrix, Implementation Plan, Impact Analysis, Testing Strategy, and Referencias sections

1. Executive Summary (module overview, purpose, criticality, technology)
2. Technical Analysis (responsibilities, key functions, execution flow, state management, error handling, dependencies)
3. Module Communication (consumes, exposes, communication types, shared state)
4. Technical Diagrams (Mermaid diagrams based on complexity)
5. Metrics (code quality metrics using standard format)
6. Referencias (bidirectional links to related documents)

1. Code Smells (issues with severity ratings)
2. Recommendations (actionable improvements with priority, impact, effort)
3. Priority Matrix (visual representation of recommendations)
4. Implementation Plan (phased refactoring roadmap)
5. Impact Analysis (affected components, risk assessment, expected benefits)
6. Testing Strategy (validation approach)
7. Referencias (link back to REPORT.md)

1. Confirm the target path exists — verify the module path before starting
2. Identify the project type — monorepo, single app, microservice, library
3. Check for existing documentation — READMEs, JSDoc, docstrings, OpenAPI specs
4. Ask for context if needed — don't guess business requirements

1. Start from entry points — find the main export, router, or handler first
2. Trace the happy path first — understand the normal flow before edge cases
3. Map dependencies as you go — build the dependency graph incrementally
4. Note patterns as you see them — architectural patterns emerge from reading, not guessing
5. Check test files — tests reveal intended behavior and edge cases

1. Review the report for accuracy — every statement must be backed by code you read
2. Verify diagram correctness — ensure diagrams match the textual analysis
3. Check for missing sections — all required output sections must be present
4. Save to the correct location —

   {output_dir}/technical/module-analysis/{module-name}/

1. Requires file access: Cannot analyze code that isn't readable via the filesystem. If the user provides code fragments, analysis is limited to what's visible
2. No runtime analysis: Analyzes static code only — cannot detect runtime behavior, performance characteristics, or dynamic dispatch patterns
3. Single module focus: Analyzes one module at a time. Cross-module analysis requires separate runs and manual correlation
4. No automated testing: Does not execute tests or verify that the code works — only analyzes structure and patterns
5. Framework detection: May not recognize custom or obscure frameworks. The user can provide framework context to compensate

1. Sync to Obsidian vault — use the

   obsidian

   skill (SYNC mode) to move the report to the vault
2. Move to custom path — user specifies a destination and files are moved there
3. Keep in staging — leave files in

   .agents/staging/code-analyzer/

   for later use

• 2.2 (2026-02-17): Staging pattern migration — deterministic .agents/staging/ output, {output_dir} rename, post-production delivery
• 2.0 (2026-02-11): Obsidian-native output — rich frontmatter, wiki-links, bidirectional references, metric tables,

  ## Referencias

• 1.0 (2026-01-29): Initial release with v1/v2/v3 analysis depths, Mermaid diagrams, and structured report output