Kit Preamble — 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

Kit Preamble — scan

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

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.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

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).

CHECKPOINT — MANDATORY — NEVER SKIP Verify the scan_context contains all required sections: Project Identity, Architecture, Inferred Requirements, Quality Assessment. If any section is missing or empty: STOP and retry the codebase-scanner agent before proceeding.

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 Verify docs/prd_digest.md exists and contains all required sections (Goals, Target User, Must-have Features, Key NFRs, Scope Boundaries). If the file is missing or any section is empty: STOP and regenerate before proceeding.

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 Verify docs/requirements.md exists and contains Goals, Functional Requirements, and NFRs sections. If missing or incomplete: 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 Verify docs/architecture.md exists and contains Tech Stack and Modules sections. If missing or empty: 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 If data-modeler was invoked: verify docs/data_model.md exists and contains Schema section. If skipped: no checkpoint needed.

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 Verify docs/test_plan.md exists and contains Current State Assessment and Risk Matrix sections. If missing or incomplete: 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 Verify issues.md exists and contains at least one ISSUE entry with Evidence field. If missing or incomplete: 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.