survey

Files (1)

• SKILL.md

SKILL.md (first lines)

# Survey

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

## Hard Gate

<HARD-GATE>
This skill MUST NOT read source implementation file contents. It may list source file paths and count them, but it must not open implementation files such as `*.js`, `*.ts`, `*.py`, `*.go`, `*.rs`, `*.java`, `*.cs`, `*.rb`, `*.php`, `*.swift`, or `*.kt`, unless the file is explicitly allowed as a structural manifest below.

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:

```bash
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`](../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`

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills