Survey

Skill: survey

The pipeline's anchor on architecture. It produces docs/architecture-map.md — the single source of "what the system is" that specify (constraints), design (matches against it), data-model, and implement all read instead of re-discovering the code. It runs in one of two modes, auto-detected:

• Brownfield (the repo has source) → scan it once and persist the current architecture.
• Greenfield (empty / near-empty repo) → run a short, level-adaptive foundation session: pick the stack / structure / data approach / conventions with the user (defaults-heavy), fix them as the foundation + foundational ADRs, and emit a scaffold tasks.json that scaffold turns into a real skeleton. Greenfield detail → ./references/foundation.md.

Repo-level utility (one map serves every feature). The scan is delegated to explorer; question phrasing → ../_shared/ask-style.md; depth → ../_shared/size-matrix.md.

Map prose follows artifact_language (carry the language in the explorer's dispatch prompt) — frontmatter keys like test_cmd / reflects_commit stay machine-form, module/file names stay as-is → ../_shared/artifact-language.md.

Owner

Architect / Tech Lead — they own the architecture (brownfield: confirm it reflects reality; greenfield: decide the foundation).

Inputs

• (Optional) a path/scope hint (default: repo root).
• (Read, never overwrite) an authored architecture doc if present (docs/architecture.md, ARCHITECTURE.md, root CLAUDE.md, ADRs) — a strong input the map reconciles with, never clobbers.
• (Optional, greenfield) docs/idea-brief.md — the intent G3 would otherwise ask for; present → confirmed, not re-asked.

Protocol

1. Ensure the settings file (first thing, after this skill's own gate). If .claude/sdd.local.md is absent, create it now from the canonical template — documented defaults + the self-documenting body — and patch .gitignore; if it exists, read it and never overwrite. The one procedure lives in ../_shared/settings-file.md. Creating is unconditional; changing values is only ever offered by config. Say one line: «.claude/sdd.local.md created with documented defaults — /sdd:config to tune it». Then detect mode + freshness (incremental re-survey on stale). If docs/architecture-map.md exists and is fresh (its reflects_commit ≈ current HEAD) → «map is fresh (reflects <commit>). Reuse or refresh?»; STOP on reuse. If it exists but is stale, prefer the incremental re-survey: git diff --name-only <reflects_commit>..HEAD, group the changed paths by top-level module, and dispatch the step-3 explorer scoped only to the changed subfolders; update just the touched map rows/sections (module inventory, conventions, frontend, machine keys) and re-stamp updated_at + reflects_commit. Fall back to the full re-scan only when the diff spans more than half the modules in the inventory (or reflects_commit no longer resolves) — say which mode ran in the handoff. No map at all → decide the mode: brownfield if the repo has source (modules/packages beyond config), else greenfield (empty or only scaffolding like a bare go.mod / package.json).

Brownfield path (existing code)

2. Read authored docs first. Any hand-maintained architecture doc / root CLAUDE.md / ADRs → authoritative input; reconcile with it, never overwrite.
3. Scan via explorer. Dispatch the explorer agent — subagent_type: "sdd:explorer" (haiku/low, clean-isolated per ../_shared/agent-roster.md): «Report (a) language + frameworks + versions, (b) top-level module layout + per-module layers, (c) layering / wiring conventions, (d) datastores + access, (e) inter-module comms, (f) cross-cutting conventions (errors, IDs, tests, migrations) with one cited example each, (g) 2–3 representative features as precedents, (h) if a frontend exists — the component library / design system, design tokens (colors/spacing/typography), styling approach (Tailwind / CSS-modules / styled-components / …), shared UI primitives, and a representative screen/component as the UI precedent to reuse.» Large repo → fan out per subtree. (Fallback subagent_type: "Explore".) Item (h) is the reuse invariant's source: the §Frontend / UI foundation section it fills is what design / tasks / implement later compose against instead of reinventing — new UI work reuses these components / tokens / the single styling approach, and review flags from-scratch UI that duplicates them. An incomplete inventory here silently licenses a second design system downstream.
4. Synthesize + stamp + validate + write. Fill ./templates/architecture-map.md (C4 of what exists, module inventory, cited conventions, datastores, the Frontend / UI foundation if a frontend exists, precedent guide, constraints) with real file:line anchors. Fill the machine-readable frontmatter keys (language, build_cmd, test_cmd, lint_cmd, migration_tool, frontend) from the explorer's findings — a key with no evidence stays "" (unknown), never a guess; implement's command-detection cascade reads test_cmd/lint_cmd from here. Record updated_at + reflects_commit: <short HEAD>. Validate the C4 Mermaid per ../_shared/mermaid-check.md (render-parse with mmdc if available, else the structural lint; fix before committing). Then the structural self-check (per ../_shared/self-check.md) — re-read the map from disk and verify: (1) every machine key holds an explorer-backed value or the explicit ""; (2) every convention line cites a file that exists; (3) the C4 validated; (4) reflects_commit = current short HEAD. Write + commit survey: architecture map (reflects <commit>). Then emit the stage-handoff block per ../_shared/handoff.md — What I did + Review (docs/architecture-map.md) + Run next (/clear, then /sdd:specify <slug>). (The greenfield path emits its own handoff in G6 — forward to /sdd:scaffold.)