/survey

name: survey
model: inherit
effort: medium
agents: [explorer]
description: >
  Use to establish the repo's architecture map the rest of the pipeline reads. Two modes: on an
  EXISTING codebase it scans once and persists what's there; on an EMPTY/greenfield repo it runs a
  short, level-adaptive foundation session — picks the stack / folder structure / data approach /
  conventions WITH you (defaults-heavy), fixes them as the foundation + foundational ADRs, and emits
  a scaffold tasks.json that the scaffold skill materializes into a real skeleton. Triggers on "survey the
  codebase", "map the architecture", "set up a new project", "bootstrap the foundation",
  "/sdd:survey", "вивчи кодову базу", "карта архітектури", "новий проєкт", "заклади фундамент".
  Output: docs/architecture-map.md (+ adr/ + scaffold tasks.json on greenfield). Records
  reflects_commit for staleness; reads, never overwrites, an authored architecture doc.

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`](../scaffold/SKILL.md) turns into a real skeleton. Greenfield detail → [`./references/foundation.md`](./references/foundation.md).

Repo-level utility (one map serves every feature). The scan is delegated to [`explorer`](../../agents/explorer.md); question phrasing → [`../_shared/ask-style.md`](../_shared/ask-style.md); depth → [`../_shared/size-matrix.md`](../_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`](../_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`](../_shared/settings-file.md). Creating is unconditional; **changing values is only ever offered by [`config`](../config/SKILL.md)**. 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`](../../agents/explorer.md) agent — `subagent_type: "sdd:explorer"` (`haiku`/`low`, clean-isolated per [`../_shared/agent-roster.md`](../_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.** Copy [`./templates/architecture-map.md`](./templates/architecture-map.md) to `do