workflow-codebase-knowledge

name

workflow-codebase-knowledge

description

Use to understand an unfamiliar codebase — presents architecture overview, module map, public API surfaces, and conventions as a layered mental model. Knowledge-presentation only: read-only sweep, no defect ranking, no reasoning chains. Distinct from workflow-codebase-audit (finding-oriented defect detection) and tech-writer / /swe-workbench:document (generates new prose artifacts). Ideal for onboarding, knowledge-handoff, and reviewer context-gathering.

Workflow: Codebase Knowledge

Announce at start: "Activating workflow-codebase-knowledge to present a structured knowledge document."

When to invoke

• Onboarding to an unfamiliar codebase: "walk me through this repo."
• Knowledge-handoff request: "give the incoming engineer a mental model of the service."
• Reviewer context-gathering: "what are the public API surfaces before I start the PR review?"
• Architecture exploration: "show me the module boundaries and their relationships."

When NOT to invoke

• Defect detection or ranked findings → use swe-workbench:workflow-codebase-audit (cold-start multi-axis sweep with reasoning chains and severity ranking).
• Generating new prose documentation (READMEs, ADRs, ARCHITECTURE files) → use /swe-workbench:document which delegates to the tech-writer subagent.
• Known bug with a repro → use /swe-workbench:debug.
• PR diff review → use /swe-workbench:review.

Composition

Read-only sweep — no subagents dispatched. May delegate file discovery to Explore agents in parallel for breadth when the path scope is wide. Never writes to disk.

Path argument

An optional path narrows the scope: /swe-workbench:codebase-knowledge src/ focuses all phases on src/ and its descendants. Without a path, the sweep covers the entire repo root.

A token is treated as a path if it contains /, starts with ., or matches an existing directory in the repo; otherwise the entire argument string is treated as natural-language context with no path scoping.

Phases

Phase 1 — Scope & entry-points

Identify the repo type (library, service, CLI, monorepo) and locate entry-points:

• Executable entry-points: main.*, index.*, __main__.py, cmd/, bin/.
• Build manifests: package.json, Cargo.toml, go.mod, pyproject.toml, pom.xml.
• Public interface declarations: exported symbols, __init__.py, mod.rs, index.ts.

Record the path argument (or . if absent) and apply it as a filter to all subsequent phases.

Phase 2 — Module map

Walk the top-level directory structure. For each module or package:

• Name and purpose (one line — inferred from code, not invented).
• Dependencies on other modules in this repo (imports, use, require).
• Notable size signals (number of files, presence of sub-packages).

Stop at 2 levels of depth unless the path argument targets a subtree.

Phase 3 — Public API surfaces

Identify the externally-facing interface of the codebase:

• HTTP/RPC routes: router registrations, controller annotations, protobuf service definitions.
• Exported functions/types in library packages.
• CLI commands and flags.
• Event schemas: topics, message contracts.

List only the surface, not the implementation detail.

Phase 4 — Patterns & conventions

Read 3–5 representative files per module to identify recurring patterns:

• Error handling style (exceptions, Result types, error codes).
• Testing conventions (framework, fixture style, what is and is not mocked).
• Naming and file-organisation conventions.
• Dependency injection or service-locator patterns.
• Any notable abstractions that appear across multiple modules.

Phase 5 — Render

Produce the knowledge document using the rendering template below. Omit any section where there is genuinely nothing to say — do not pad. Apply the diagram signal-to-noise rule before including any Mermaid block.

Rendering template

## Codebase Knowledge — <repo> — <date>

### Overview

<2–4 sentences: what this codebase does, its type (service/library/CLI/monorepo), primary language(s), and rough size signal.>

### Module map

| Module | Purpose | Depends on |
|--------|---------|------------|
| `<name>` | <one-line purpose> | `<dep>`, `<dep>` |

### Architecture diagram

<!-- Include only when the module graph has meaningful topology (see Diagram guidelines). -->

```mermaid
flowchart LR
    A[<module>] --> B[<module>]
```

### Public API surfaces

| Surface | Kind | Location |
|---------|------|----------|
| `<name>` | HTTP route / exported fn / CLI cmd / event topic | `<file:line>` |

### Patterns & conventions

- **Error handling:** <style>
- **Testing:** <framework, fixture conventions, mock boundary>
- **Naming:** <conventions observed>
- **Notable abstractions:** <list or "none observed">

Diagram guidelines

Include a Mermaid diagram only when it adds information that the module map table cannot convey.

Situation	Rule
≤5 modules, flat structure	Skip — the module map table is sufficient
Meaningful cross-module dependency edges	Use flowchart LR
Request/response lifecycle across layers	Use sequenceDiagram
Hierarchical package nesting	Use graph TD
Flat list of peer modules (no edge topology)	Skip — a diagram would just redraw the table

Cap at 1 diagram per output section. Omit if the diagram would have fewer than 3 nodes.

Preferred formats: flowchart LR, sequenceDiagram, graph TD.

Absolute rules

• Read-only. Never invoke Edit, Write, or any shell command that modifies the filesystem.
• Never invent structure. Every module, API, and pattern listed must be traceable to actual code. If a module's purpose is unclear, say so — do not guess.
• Cap diagrams. At most 1 diagram per output section; omit when the signal-to-noise rule says Skip.
• Omit empty sections. If Phase 3 yields no public API surface, omit the Public API surfaces section entirely. Silence is correct; padding misleads.
• No defect reporting. This skill presents structure; it does not rank findings, assign severity, or suggest fixes. Route those needs to workflow-codebase-audit.