survey
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.
genkovich · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add genkovich/sdd --skill 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.jsonthatscaffoldturns 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, rootCLAUDE.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
- Detect mode + freshness (incremental re-survey on stale). If
docs/architecture-map.mdexists and is fresh (itsreflects_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-stampupdated_at+reflects_commit. Fall back to the full re-scan only when the diff spans more than half the modules in the inventory (orreflects_commitno 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 barego.mod/package.json).
Brownfield path (existing code)
- Read authored docs first. Any hand-maintained architecture doc / root
CLAUDE.md/ ADRs → authoritative input; reconcile with it, never overwrite. - Scan via explorer. Dispatch the
exploreragent —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. (Fallbacksubagent_type: "Explore".) Item (h) is the reuse invariant's source: the §Frontend / UI foundation section it fills is whatdesign/tasks/implementlater compose against instead of reinventing — new UI work reuses these components / tokens / the single styling approach, andreviewflags from-scratch UI that duplicates them. An incomplete inventory here silently licenses a second design system downstream. - 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 realfile:lineanchors. 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 readstest_cmd/lint_cmdfrom here. Recordupdated_at+reflects_commit: <short HEAD>. **Validate the C4 Mermaid per [`.