Scan

---
name: scan
description: Analyze an existing codebase and generate context documents (architecture, requirements, test plan) for downstream skills.
argument-hint: '[directory path, or omit for project root]'
disable-model-invocation: true
allowed-tools: Task, Read, Glob, Grep, Write, Edit, Bash
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — scan

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.
## Algorithm

### Phase 1 — Discovery
1) Ensure `docs/` directory exists.
2) Determine scan target: if `$ARGUMENTS` is provided and is a valid directory path, use it as the scan root. Otherwise, use the project root.
3) Check for `--force` flag in `$ARGUMENTS`: if present, skip existing-file prompts and overwrite all.
4) Check for `--audit` flag in `$ARGUMENTS`: if present, produce only `docs/scan_report.md` (read-only mode, no other docs generated).
5) Inventory existing `docs/` files. If any target documents already exist and neither `--force` nor `--audit` is set, ask the user: overwrite or keep existing?
6) Invoke the **codebase-scanner** agent via Task tool:
   - Prompt: "You are the codebase-scanner agent. Analyze the codebase at [scan root]. Follow your agent guidelines precisely."
   - Pass: scan root path, list of existing docs
   - The agent returns a structured scan_context (do NOT write it to disk — it is an internal intermediate artifact).
7) Verify the returned scan_context contains all required sections: Project Identity, Architecture, Inferred Requirements, Quality Assessment. If any section is missing or empty, retry the codebase-scanner agent before proceeding. (scan_context is an in-memory artifact by design — no script checkpoint can back this verification; the first scripted gate is Phase 1.5's prd-digest below. ISSUE-057/SPEC-057.)

### Phase 1.5 — PRD Digest
Using the scan_context and README (if present), generate `docs/prd_digest.md`:
  - Goals (inferred from README + code purpose) — tag `[CONFIRMED]` if README states it, `[INFERRED]` otherwise
  - Target User (inferred from UI/API design)
  - Must-have Features (inferred from core code paths)
  - Key NFRs (from config: timeouts, rate limits, caching)
  - Scope Boundaries (In: what the code does; Out: what it notably doesn't)

All items should carry confidence tags: `[CONFIRMED]` (documented/tested) or `[INFERRED]` (code-only).

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill scan --phase prd-digest`
> Verifies `docs/prd_digest.md` exists and contains all required sections (Goals, Target User, Must-have Features, Key NFRs, Scope Boundaries).
> If exit code ≠ 0: STOP and regenerate before proceeding. The script checks presence, not depth — also self-check that no section is empty.

### Phase 2 — Run Subagents (dependency-aware, parallel where possible)

**Step 1: scan-analyst → `docs/requirements.md`**
- Context to pass: Full scan_context + `docs/prd_digest.md` content + README content (if exists)
- Agent produces: Goals, user stories with confidence tags, FRs, NFRs — all with `[CONFIRMED]`/`[INFERRED]` tags and source file references
- Verify output exists before proceeding

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill scan --phase requirements`
> Verifies `docs/requirements.md` exists and contains Goals, Functional Requirements, and NFRs sections.
> If exit code ≠ 0: STOP and retry the scan-analyst agent before proceeding.

**Step 2 & 3 — MUST invoke both subagents simultaneously via two parallel Task tool calls in a single message:**

**scan-architect → `docs/architecture.md`**
- Context to pass: scan_context + `docs/prd_digest.md` + `docs/requirements.md`
- Agent produces: As-is architecture with tech stack, modules, data model, API design — all with confidence tags and file references

**(Conditional) ux-designer → `docs/ux_spec.md`**
- Only invoke if scan_context detected a frontend (web UI, mobile app, desktop app).
- Context to pass: scan_context + `docs/prd_digest.md` + `docs/requirements.md`
- If no frontend detected, skip this agent silently.

**After both/all Task calls return**, verify outputs exist before proceeding.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill scan --phase architecture`
> Verifies `docs/architecture.md` exists and contains Tech Stack and Modules sections.
> If exit code ≠ 0: STOP and retry the scan-architect agent before proceeding.

**Step 4 (Conditional): scan-data-modeler → `docs/data_model.md`**
- Only invoke if scan_context detected database usage (ORM models, migrations, schema files, or database config).
- Context to pass: scan_context + `docs/prd_digest.md` + `docs/requirements.md` + `docs/architecture.md`
- Agent produces: Schema extraction, indexes, migrations, access patterns — all with source file references
- If no database detected, skip this agent silently and note in STATUS.md.

> **CHECKPOINT — CONDITIONAL**
> Run: `bash scripts/checkpoint.sh --skill scan --phase data-model`
> If database usage was detected: verifies `docs/data_model.md` exists with a Schema section. If no database was detected, the script reports SKIP and exits 0 — no action needed.
> If exit code ≠ 0: STOP and retry the scan-data-modeler agent before proceeding.

**Step 5: scan-qa-designer → `docs/test_plan.md`**
- Context to pass: scan_context + `docs/prd_digest.md` + `docs/requirements.md` + `docs/architecture.md` + `docs/data_model.md` (if exists)
- Agent produces: Test inventory, coverage gaps, risk matrix, improvement plan
- Verify output exists before proceeding

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill scan --phase test-plan`
> Verifies `docs/test_plan.md` exists and contains Current State Assessment and Risk Matrix sections.
> If exit code ≠ 0: STOP and retry the scan-qa-designer agent before proceeding.

**Step 6: scan-planner → `issues.md`**
- Context to pass: scan_context + `docs/prd_digest.md` + `docs/requirements.md` + `docs/architecture.md` + `docs/data_model.md` (if exists) + `docs/test_plan.md`
- Agent produces: Improvement issues derived from scan observations (test gaps, tech debt, schema issues, risk items)
- Must run after scan-qa-designer (uses Coverage Gaps and Risk Matrix from test_plan.md)
- Verify output exists before proceeding

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill scan --phase issues`
> Verifies `issues.md` exists and contains at least one ISSUE entry with an Evidence field.
> If exit code ≠ 0: STOP and retry the scan-planner agent before proceeding.

### Phase 3 — STATUS.md Generation
Create/update `STATUS.md` with:
- Scan summary: date, target path, documents generated
- Confidence distribution: count of `[CONFIRMED]` vs `[INFERRED]` tags across all documents
- Coverage summary: modules with tests vs modules without
- Issue summary: total issue count, priority distribution (P0/P1/P2), category distribution (test gap, tech debt, schema, security, performance)
- Skipped agents: list any agents that were skipped and why (no DB, no frontend)
- Next steps suggestions:
  - If many `[INFERRED]` tags: suggest reviewing and confirming key requirements
  - If test gaps found: suggest `/implement` for high-risk test cases
  - If architecture is clear: suggest `/implement ISSUE-001` or `/kickoff` for formal planning

### Phase 4 — Verification + Report
1) Verify all generated documents exist:
   - `docs/prd_digest.md` (always)
   - `docs/requirements.md` (always)
   - `docs/architecture.md` (always)
   - `docs/data_model.md` (only if DB detected)
   - `docs/test_plan.md` (always)
   - `issues.md` (always)
   - `STATUS.md` (always)
2) Validate `issues.md`:
   - Run `scripts/validate_issues.py issues.md` if the script exists
   - If validation fails: retry scan-planner once with error feedback
   - Cross-document check: verify PRD-Ref values in issues reference valid FR-NNN/NFR-NNN from `docs/requirements.md`
3) Report summary to the user:
   - Number of FRs/NFRs identified (confirmed vs inferred)
   - Architecture style detected
   - Test coverage state (existing tests / gaps)
   - Issues generated: total count, priority breakdown, category breakdown
   - Documents generated (list with paths)
   - Suggest next step: `/implement ISSUE-001` to start fixing identified issues, or `/kickoff` for formal planning from scratch

### Audit Mode (`--audit`)
If `--audit` flag is present:
1) Run Phase 1 (Discovery) as normal.
2) Run Phase 1.5 (PRD Digest) internally but do NOT write to disk.
3) Skip Phase 2 subagents entirely.
4) Write `docs/scan_report.md` with:
   - Project identity summary
   - Architecture overview (from scan_context)
   - Test health summary (from scan_context)
   - Confidence assessment
   - Recommendations
5) Report to user and exit. No other documents are created or modified.

## Subagent Invocation Pattern

When invoking each subagent via the Task tool:
- Include the agent name in the prompt (e.g., "You are the scan-analyst agent")
- Pass the full content of input documents — do NOT just pass file paths
- Specify the exact output file path
- Include: "Write your output to `docs/<file>.md`. Follow your agent guidelines precisely."
- Include the confidence tagging rules: `[CONFIRMED]` = test-backed or config-documented, `[INFERRED]` = code-only evidence

## Error Handling
- If a subagent fails (Task tool returns error):
  1. Retry the failed subagent once with the same context.
  2. If it fails again, skip with a warning message and continue with remaining subagents.
  3. Log the skipped subagent in `STATUS.md` under a `## Warnings` section.
- If the scan target directory does not exist: stop immediately and report the missing path.
- If `docs/` cannot be created: stop immediately and report the filesystem error.
- If a subagent produces empty or malformed output: treat as failure, retry once.

## Rollback
- Scan is additive (writes new files); no destructive rollback is needed.
- If partially completed, re-running `/scan` overwrites all outputs — safe to retry.
- Use `--audit` for a non-destructive read-only analysis.

## Guidelines
- The dependency order is critical: scan_context → prd_digest → requirements → (architecture + optional UX in parallel) → optional data_model → test_plan → issues.
- **scan-architect + ux-designer (if applicable) MUST be invoked in parallel**: Both only need requirements and have no dependency on each other.
- Each subagent should receive ALL prior outputs as context for maximum coherence.
- Do NOT modify subagent outputs after they are written — each agent owns its document.
- Confidence tagging is mandatory for all scan-generated documents. This distinguishes scan output from kickoff output.
- When the `--audit` flag is used, the skill MUST NOT write any document except `docs/scan_report.md`.