wiki-scan

Wiki Scan — Deep Codebase Analysis

Perform a comprehensive scan of the codebase using Serena's semantic analysis tools and write all wiki pages as Serena memories. Uses parallel agents to scan multiple areas of the codebase simultaneously for maximum speed.

CRITICAL: Serena is REQUIRED

All operations use Serena — both code analysis AND wiki storage. Check that Serena MCP tools are available (prefixed mcp__plugin_serena_serena__).

If Serena is NOT available — STOP. Tell the user:

"Serena is required. Install it first: /plugin install serena@claude-plugins-official"

Prerequisites

• Wiki must be initialized. Use mcp__plugin_serena_serena__read_memory with memory_name: "wiki/schema". If it doesn't exist, tell the user to run wiki-setup first.
• Read wiki/schema before generating any pages — follow its conventions exactly.

STEP 1: Ask the User — Scan Mode

Before doing any analysis, you MUST ask the user these two questions:

Question 1: Scan depth

How deep should I scan?

Full Scan — Every module, every pattern, every decision. Reads deeply into every corner of the codebase. Produces the most comprehensive wiki possible. Uses more tokens but gives you a complete knowledge base. No caps on pages.

Partial Scan — Focuses on the most important parts: main architecture, core modules, dominant patterns. Skips peripheral utilities, test helpers, and minor modules. Faster and lighter. Caps at ~15 module pages, ~5 pattern pages, ~3 decision pages.

Question 2: Module focus (optional)

Any specific areas to prioritize or skip?

For example: "Focus on the API and auth modules" or "Skip the test utilities" or "Everything, don't skip anything"

Wait for the user's answers before proceeding.

Scan Modes

Full Scan

• No caps on number of pages — document everything worth documenting
• Read every module, not just top-level ones — go into subdirectories
• Use get_symbols_overview at depth 2-3, not just depth 1
• Trace ALL cross-module dependencies, not just key ones
• Document ALL recurring patterns, not just the top ones
• Read actual function bodies with read_file when needed for deeper understanding
• Create architecture pages for every significant concern (auth, state, deployment, testing, etc.)
• Infer as many decisions as possible — tech choices, library picks, data model design, API style
• For each module: read every source file's symbols, trace every export's consumers

Partial Scan

• Cap at ~15 module pages, ~5 pattern pages, ~3 decision pages
• Focus on top-level modules only (depth 1)
• Use get_symbols_overview at depth 1
• Only trace dependencies for the most-imported modules
• Document only the 5 most prevalent patterns
• Skip: utility modules, test helpers, generated code, config-only directories
• Architecture: system-design page only (skip data-flow unless it's the core of the app)
• Decisions: only the most obvious technology choices

---

STEP 2: Discovery (you do this yourself — do NOT delegate)

Goal: Map the project structure and identify module boundaries. This must be done in the main context because the results determine how to split work across agents.

1. Use mcp__plugin_serena_serena__list_dir with relative_path: ".", max_depth: 2
2. Identify modules — top-level directories containing source code:
   • JS/TS: src/, lib/, packages/*/, apps/*/
   • Python: directories with __init__.py, src/*/
   • Go: directories with .go files, cmd/*/, internal/*/
   • Rust: src/, crates/*/
   • Java/Kotlin: src/main/java/*/, Gradle/Maven modules
   • Exclude: node_modules/, vendor/, dist/, build/, .git/, test fixtures
3. Identify entry points: main files, config files, route definitions
4. Apply user's focus/skip preferences from Step 1
5. Build the final list of modules to scan and the architecture concerns to document

---

STEP 3: Dispatch Parallel Agents

This is where the speed comes from. After discovery, dispatch multiple agents in parallel using the Agent tool. Each agent works independently — they can all write Serena memories concurrently without conflicts because each writes to a different memory name.

How to split the work

Launch up to 5 agents in a single message (all Agent tool calls in one response). Split the work like this:

Agent 1: Architecture

Prompt the agent with:

• The project structure you discovered in Step 2
• The list of entry points and top-level modules
• The scan mode (Full or Partial)
• Instructions to:
  1. Use mcp__plugin_serena_serena__get_symbols_overview on each top-level module
  2. Use mcp__plugin_serena_serena__find_referencing_symbols to trace cross-module dependencies
  3. Write wiki/architecture/system-design via mcp__plugin_serena_serena__write_memory
  4. If Full scan: also write wiki/architecture/data-flow and pages for every significant concern (auth, state, deployment, testing, database, etc.)
  5. If Partial: just system-design and data-flow if applicable
  6. Follow the page format from wiki/schema (tell the agent the format)
  7. Report back: list of pages created with one-line summaries

Agent 2: Modules Batch A (first half)

Prompt the agent with:

• The first half of the module list from Step 2
• The scan mode (Full or Partial)
• For each module, instructions to:
  1. Use mcp__plugin_serena_serena__get_symbols_overview (Full: depth 2-3, Partial: depth 1)
  2. Use mcp__plugin_serena_serena__find_referencing_symbols on key exports
  3. If Full: use mcp__plugin_serena_serena__read_file on key files for deeper understanding
  4. Write wiki/modules/{module-name} via mcp__plugin_serena_serena__write_memory
  5. Include: Purpose, Key Symbols table, Dependencies, Internal Structure, Notable Patterns
  6. Report back: list of pages created with one-line summaries

Agent 3: Modules Batch B (second half)

Same as Agent 2 but with the second half of the module list.

Agent 4: Patterns

Prompt the agent with:

• The project structure from Step 2
• The scan mode
• Instructions to:
  1. Use mcp__plugin_serena_serena__search_for_pattern for each pattern category: error handling, logging, auth, API, config, testing, state management, DI
  2. Full: document all patterns with 2+ occurrences, no cap
  3. Partial: top 5 patterns with 3+ occurrences only
  4. Write wiki/patterns/{name} via mcp__plugin_serena_serena__write_memory
  5. Also write wiki/patterns/code-conventions for naming and style patterns
  6. Report back: list of pages created with one-line summaries

Agent 5: Decisions

Prompt the agent with:

• The project structure from Step 2
• The scan mode
• Instructions to:
  1. Use mcp__plugin_serena_serena__search_for_pattern for decision markers: WHY:, DECISION:, NOTE:, RATIONALE:, HACK:, TRADEOFF:
  2. Check for docs/adr/, docs/decisions/ directories
  3. Infer decisions from tech choices, architecture style, dependency picks
  4. Full: document all decisions found, no cap
  5. Partial: top 3 decisions only
  6. Write wiki/decisions/{slug} via mcp__plugin_serena_serena__write_memory
  7. ADR format: Context, Decision, Options Considered, Consequences, Status
  8. Report back: list of pages created with one-line summaries

Scaling rules

Codebase size	Agents	Split strategy
Small (< 10 modules)	3	Architecture + Modules (1 agent) + Patterns & Decisions (1 agent)
Medium (10-25 modules)	4	Architecture + 2 Module batches + Patterns & Decisions combined
Large (25+ modules)	5	Architecture + 2 Module batches + Patterns + Decisions

For small codebases, combine work into fewer agents — don't spawn 5 agents for 5 modules.

Agent prompt template

Each agent prompt MUST include:

1. Context: "You are scanning a codebase to build wiki pages stored as Serena memories."
2. Serena tools available: list the full prefixed tool names they need
3. Their specific assignment: which modules/patterns/decisions to analyze
4. Scan mode: Full or Partial and what that means for their work
5. Page format: the exact markdown structure from wiki/schema (paste it in)
6. Memory naming: exact wiki/{category}/{name} pattern to use
7. Output: "Report back the list of wiki memory names you created with a one-line summary for each"

CRITICAL: Tell each agent the exact Serena tool names with the full prefix mcp__plugin_serena_serena__. Agents won't know the prefix unless you tell them.

---

STEP 4: Collect Results and Build Index (you do this yourself)

After all agents complete, collect their reports. Each agent returns a list of pages created.

4a. Rebuild wiki/index

Use mcp__plugin_serena_serena__list_memories with topic: "wiki" to verify all memories.

Use mcp__plugin_serena_serena__write_memory to overwrite memory_name: "wiki/index":

# Wiki Index

> Last rebuilt: YYYY-MM-DD
> Total pages: N

## Overview
- wiki/overview — [summary]

## Architecture
- wiki/architecture/system-design — [summary]
[... all architecture pages from Agent 1, alphabetically]

## Modules
- wiki/modules/{name} — [summary]
[... all module pages from Agents 2+3, alphabetically]

## Patterns
- wiki/patterns/{name} — [summary]
[... all pattern pages from Agent 4, alphabetically]

## Decisions
- wiki/decisions/{slug} — [summary]
[... all decision pages from Agent 5, alphabetically]

## External
_No pages yet. Run wiki-enrich to add external context._

4b. Append to wiki/log

Use mcp__plugin_serena_serena__edit_memory on wiki/log, mode "regex", needle \Z:

## [YYYY-MM-DD HH:MM] SCAN | [Full/Partial] codebase scan completed
- Scan mode: [Full/Partial]
- Agents dispatched: N
- Generated N architecture pages
- Generated N module pages
- Generated N pattern pages
- Inferred N architectural decisions
- Total: N pages indexed

4c. Inform the user

Report:

• Scan mode used
• Number of agents dispatched
• Pages created per category
• Any areas that couldn't be analyzed
• Suggest: "Run wiki-enrich to add external documentation."
• Suggest: "Ask questions — the wiki will be consulted first."

---

Serena Tools Reference

Code analysis (all prefixed mcp__plugin_serena_serena__):

• list_dir — recursive directory listing with depth control
• get_symbols_overview — catalog classes, functions, interfaces, types in a file
• find_symbol — locate specific symbols by name path
• find_referencing_symbols — trace who calls/imports a symbol (dependency chains)
• search_for_pattern — regex search across the codebase
• read_file — read file contents with optional line ranges

Wiki CRUD (all prefixed mcp__plugin_serena_serena__):

• write_memory — create a wiki page: memory_name: "wiki/{category}/{name}"
• read_memory — read a wiki page
• edit_memory — update a wiki page by pattern matching
• list_memories — browse wiki pages by topic
• delete_memory — remove a wiki page

Important Guidelines

• Parallelize aggressively — the whole point is speed. Use as many agents as makes sense.
• Each agent writes its own memories — no conflicts because memory names are unique per page
• Discovery is sequential — you must identify modules before splitting work
• Index is sequential — you must wait for all agents before rebuilding the index
• Follow wiki/schema — all agents must follow the same format
• For large codebases: read references/scan-strategy.md for ecosystem-specific guidance