/scan

name: scan
description: "Analyze an existing codebase. Maps structure, architecture, conventions, and concerns."
allowed-tools: Read, Write, Bash, Glob, Grep, Task, AskUserQuestion
argument-hint: "[--focus tech|arch|quality|concerns]"

**STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.**

Step 0 — Immediate Output

**Before ANY tool calls**, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► SCANNING CODEBASE                          ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

/pbr:map-codebase — Codebase Analysis

You are running the **scan** skill. Your job is to analyze an existing codebase and produce a comprehensive map of its structure, architecture, conventions, and concerns. This is the entry point for brownfield projects — codebases that already have code before Plan-Build-Run is introduced.

This skill **spawns 4 parallel Task(subagent_type: "pbr:codebase-mapper")** agents for analysis.

---

Context Budget

Reference: `skills/shared/context-budget.md` for the universal orchestrator rules. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

Additionally for this skill:

• **Never** analyze the codebase yourself — delegate ALL analysis to the 4 parallel codebase-mapper subagents
• **Minimize** reading mapper outputs — read only frontmatter or first 20 lines of each output document
• **Delegate** all file reading, pattern analysis, and architecture mapping to the codebase-mapper subagents

---

Core Principle

**Understand before you change.** Scanning a codebase is about building a mental model of what exists. Every file produced by this skill becomes context that the planner and executor use to make informed decisions. Accuracy matters more than speed.

---

Flow

Step 1: Load Init Context

Run the CLI to get scan metadata:

pbr-tools init map-codebase

Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`, `intel_enabled`, `has_intel_dir`, `depth_profile`.

If the CLI fails, display a branded ERROR box: "Failed to load scan context. Ensure pbr-tools.js is available." and stop.

Step 2: Check for Existing Analysis

Use `has_maps` from init context.

**If `has_maps` is true:**

Present to user via AskUserQuestion:

question: "A codebase analysis already exists. What would you like to do?" header: "Scan" options:

• label: "Refresh all" description: "Delete existing and remap codebase"
• label: "Refresh specific" description: "Re-scan only one area (tech, arch, quality, or concerns)"
• label: "Keep existing" description: "Use existing codebase map as-is"

• If user chooses "Keep existing": display a summary of existing analysis and stop
• If user chooses "Refresh specific": ask which area, then spawn only that agent in Step 4
• If user chooses "Refresh all": proceed with full scan

**If `has_maps` is false:** **CRITICAL: Create the codebase directory NOW. Do not skip this step.**

• Create `.planning/codebase/` directory if needed:

  mkdir -p .planning/codebase

• Also create `.planning/` if it doesn't exist (scan can be run before begin)
• Proceed with full scan

Step 3: Resolve Mapper Configuration

Use `depth_profile` from init context to determine how many mappers to spawn and which focus areas.

**Default mappings by depth:**

• `quick`: 2 mappers — `tech` and `arch` only. Produces STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md.
• `standard`: 4 mappers — all areas. Full analysis.
• `comprehensive`: 4 mappers — all areas. Full analysis.

**Extended context override:** If `features.extended_context` is `true` in `.planning/config.json`, always spawn 4 mappers regardless of depth profile.

Step 4: Spawn Analysis Agents

Display to the user:

◐ Spawning {mapper_count} codebase mapper(s) in parallel...
  → Technology stack analysis
  → Architecture patterns
  → Code quality assessment
  → Concerns & risks

(Only list the focus areas that will actually be spawned.)

Spawn `{mapper_count}` parallel `Task(subagent_type: "pbr:codebase-mapper")` agents, one for each focus area. All should be spawned in a single response for maximum parallelism.

For each agent, read `${CLAUDE_SKILL_DIR}/templates/mapper-prompt.md.tmpl` and fill in the placeholders:

• `{focus_area}`: one of `tech`, `arch`, `quality`, `concerns`
• `{project_path}`: the working directory
• `{output_path}`: `.planning/codebase/`

| Agent | Focus | Output Files | When | |-------|-------|-------------|------| | 1 | tech | STACK.md, INTEGRATIONS.md | Always | | 2 | arch | ARCHITECTURE.md, STRUCTURE.md | Always | | 3 | quality | CONVENTIONS.md, TESTING.md | standard + comprehensive | | 4 | concerns | CONCERNS.md | standard + comprehensive |

Step 5: Collect Results

As each agent completes, check the Task() output for the `## MAPPING COMPLETE` marker:

• If `## MAPPING COMPLETE` is present: display `✓ {focus_area} analysis complete`
• If the marker is missing: warn:

  ⚠ Codebase mapper ({focus_area}) did not report MAPPING COMPLETE.
  Output may be incomplete — check .planning/codebase/ for partial results.

Step 6: Verify Output

After all agents complete, verify the expected files exist:

ls -la .planning/codebase/
wc -l .planning/codebase/*.md

**Verification checklist:**

• All expected documents exist (7 for standard/comprehensive, 4 for quick)
• No empty documents (each should have >20 lines)

For any missing files, display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚════════════