Survey

Produce a fast architecture survey of the current repository without reading source implementation files.

Hard Gate

The output is research, not canonical Feature intent. Do not write Feature, Plan, or code artifacts from this skill. Do not invoke specstudio:retrofit automatically. </HARD-GATE>

When To Use

• A user wants a cheap architecture overview of an existing repository.
• A user is deciding whether retrofit is worth running.
• A future specstudio:retrofit run needs a survey-output-schema-v1 input.

Skip when the user wants behavior, requirements, or acceptance criteria derived from code. That is retrofit, not survey.

Inputs and flags

Supported invocations:

• specstudio:survey
• specstudio:survey --scope <subdir>
• specstudio:survey --slug <slug>
• specstudio:survey --output-dir <path>
• specstudio:survey --json

Flag behavior:

• --scope <subdir> limits the file inventory and manifest reads to that subtree, while repo state still records the whole-repo HEAD.
• --slug <slug> overrides slug derivation.
• --output-dir <path> overrides the default spec/research/.
• --json writes only the JSON artifact and skips Markdown rendering.

Unknown flags are refused.

Step 1 - Pre-flight

1. Determine repo root with git rev-parse --show-toplevel. If that fails, use the current directory and record git_available: false.
2. Resolve scope from --scope, defaulting to repo root.
3. Derive slug from, in order:
   • package.json#name
   • pyproject.toml [project].name
   • go.mod module basename
   • Cargo.toml [package].name
   • repository directory basename
   • --slug override, if supplied
4. Sanitize slug to lowercase a-z0-9-, collapse repeated dashes, and trim leading/trailing dashes.
5. Set output paths:
   • JSON: <output-dir>/<slug>-survey.json
   • Markdown: <output-dir>/<slug>-survey.md
   • Default output dir: spec/research/

Step 2 - File inventory

Prefer:

git ls-files

When scoped, filter the inventory to paths under the scope.

If git is unavailable, use find and exclude obvious generated or dependency directories:

• .git
• node_modules
• .venv, venv, __pycache__
• dist, build, target, .next, .turbo
• .cache, .pytest_cache

Record the scan method as git-ls-files or find-fallback.

Step 3 - Repo state

When git is available, record:

• head_sha: git rev-parse HEAD
• dirty_tree: whether git status --short is non-empty
• status_short: literal lines from git status --short

When git is unavailable, record:

• git_available: false
• head_sha: null
• dirty_tree: null
• status_short: []

Step 4 - Allowed manifest reads only

Read content only from the operational allowlist at skills/shared/survey-manifest-allowlist.md. The current v1 categories are:

• JavaScript / TypeScript: package.json, pnpm-workspace.yaml, lerna.json, nx.json, turbo.json, tsconfig*.json, next.config.*, vite.config.*, nuxt.config.*, astro.config.*, package-lock.json, pnpm-lock.yaml, yarn.lock
• Python: pyproject.toml, setup.py, setup.cfg, requirements*.txt, poetry.lock, Pipfile, Pipfile.lock, tox.ini
• Go: go.mod, go.sum, go.work
• Rust: Cargo.toml, Cargo.lock
• Other languages: Gemfile, composer.json, *.csproj, *.sln, pom.xml, build.gradle*
• Infra and ops: docker-compose*.yml, Dockerfile, terraform/*.tf, serverless.yml, helm/Chart.yaml, kustomization.yaml
• CI and tooling: .github/workflows/*.yml, .gitlab-ci.yml, .circleci/config.yml, Makefile, justfile, Taskfile.yml
• Release and packaging: .goreleaser.yml, .goreleaser.yaml, release-please-config.json, .release-please-manifest.json, .releaserc, .releaserc.json, .changeset/config.json
• Runtime pinning: .tool-versions, .nvmrc, .python-version, .ruby-version
• SpecScore: specscore.yaml
• Docs: root README*, ARCHITECTURE*, CONTRIBUTING*; top-level docs/** filenames only unless a doc file is small enough to read under the size cap

Generated release outputs remain excluded. Do not read dist/**, packaged archives, generated checksums, generated changelogs, or binary artifacts as release manifests.

Size cap for any single text read: 80 KB. If an allowlisted file exceeds the cap, do not read it. Record a warning: skipped due to size.

Step 5 - Monorepo detection

Detect monorepo signals before synthesis:

• pnpm-workspace.yaml
• nx.json
• lerna.json
• turbo.json
• go.work
• Cargo workspace members in root Cargo.toml
• multiple root package directories indicated by manifests

If monorepo signals are present and no --scope was supplied:

1. Refuse to synthesize a whole-repo survey.
2. Identify the signal paths.
3. Recommend rerunning with specstudio:survey --scope <subdir>.
4. Do not write artifacts.

Step 6 - Build the structured survey

Construct a JSON object with this minimum shape:

{
  "schema": "survey-output-schema-v1",
  "slug": "<slug>",
  "scope": "<scope-or-null>",
  "scan_method": "git-ls-files",
  "repo_state": {
    "git_available": true,
    "head_sha": "<sha>",
    "dirty_tree": false,
    "status_short": []
  },
  "file_inventory_summary": {
    "total_files": 0,
    "by_extension": {},
    "top_level_dirs": []
  },
  "manifest_inventory": [],
  "detected_frameworks": [],
  "architecture_summary": "",
  "directory_clusters": [],
  "research_zones": [],
  "sensitive_path_inventory": [],
  "warnings": []
}

Populate:

• file_inventory_summary: counts by extension, top-level directory counts, test path counts, docs path counts.
• manifest_inventory: allowlisted files read, skipped, or absent.
• detected_frameworks: framework/tool signals inferred from manifests and filenames.
• directory_clusters: hierarchical directory groups, max depth 3, max 12 children per parent.
• research_zones: proposed bounded zones for retrofit researchers, each with path roots, file counts, and one-line purpose.
• sensitive_path_inventory: filename-pattern hints only.
• warnings: dirty tree, skipped oversized manifests, monorepo refusal signals when scoped, ambiguous slug signals.

Do not invent behavior from source. If a conclusion depends only on file names or manifests, phrase it as inferred.

Step 7 - Sensitive path inventory

Flag filename-pattern hints for:

• .env*
• secrets/**
• *.pem
• *.key
• **/fixtures/**
• git-crypt markers
• submodule entries
• LFS pointer-looking files
• lockfile mismatch hints, such as multiple package-manager lockfiles

Label the section explicitly: "Filename-pattern hints only; not a content secret scan."

Step 8 - Write JSON first

Create the output directory if needed. Write the JSON artifact first. Sort object keys where practical and keep arrays in deterministic path order.

If --json is set, skip Markdown rendering and go to indexing/lint/staging.

Step 9 - Render Markdown from JSON

Render Markdown from the JSON artifact. The Markdown must contain:

1. # Survey: <title>
2. **Status:** Current
3. **Date:** <YYYY-MM-DD>
4. **Repo SHA:** <sha-or-unavailable>
5. **Scope:** <scope-or-repo-root>
6. **JSON:** <relative path to json>
7. ## Summary
8. ## Architecture
9. ## Directory Clusters
10. ## Research Zones
11. ## Detected Frameworks
12. ## Sensitive Path Inventory
13. ## Warnings
14. ## Open Questions
15. Footer: *This document follows the https://specscore.md/research-artifact-specification*

Use Mermaid diagrams only when they add clarity. Always include text lists so the artifact remains useful without Mermaid rendering.

Step 10 - Research index

For default output under spec/research/, ensure spec/research/README.md exists.

If absent, create:

# Research

Research artifacts produced by SpecStudio skills.

## Contents

| Artifact | Description |
|---|---|

## Open Questions

None at this time.

---
*This document follows the https://specscore.md/index-specification*

Add or update one row for the survey:

| [<slug>-survey](<slug>-survey.md) | Architecture survey for `<scope-or-repo>`. |

Do not duplicate rows for the same survey slug.

Step 11 - Lint and fix once

Run:

specscore spec lint

If lint fails, make one focused fix pass for the generated artifacts and rerun lint. If violations remain, surface them with paths and stop.

Step 12 - Stage

Stage all generated or updated files:

git add <json> <markdown-if-written> <research-index-if-updated>

Never commit. Report the staged paths.

Output summary

End with:

• JSON path
• Markdown path, unless --json
• Research index path, if updated
• Lint result
• Staged paths
• Any warnings, especially dirty tree and sensitive-path hints

Relationship to retrofit

specstudio:retrofit consumes the JSON artifact. Survey does not invoke retrofit automatically. If the user wants to continue, recommend running retrofit with the generated JSON path once retrofit ships.