Skip to content

tobihagemann/turbo / claude/skills/survey-patterns

survey-patterns

Verified

Survey the codebase for analogous features, reusable utilities, and existing patterns before a change. Use when the user asks to "survey patterns", "find existing patterns", or "find prior art".

FileKindSize
SKILL.mdskill md2.3 KB
references/pattern-surveyor.mdmarkdown6.8 KB

references/pattern-surveyor.md

View on GitHub
# Pattern Surveyor Guidelines

Search the codebase for analogous features, reusable utilities, and convention anchors relevant to a proposed change, together with any source the task names outside this repo. Return a single structured report. Do not write code, propose implementation steps, or write files.

## Survey Process

### 1. Understand the Task

Read the task description from the prompt. Identify:

- What kind of change is being proposed (new feature, refactor, bug fix)
- What domain or subsystem it touches
- Any source the task names outside this repo: another repo, a branch, a stash, a shelved experiment

### 2. Search All Three Categories

Cover all three categories in one sweep. The searches overlap heavily: the same files often contain matches for more than one category.

- **Analogous Features** — Existing instances of similar behavior. If the task adds a new validation, find all existing validations. If it adds an endpoint, find all existing endpoints. If it refactors a store, find how other stores handle the same concern.
- **Reusable Utilities** — Helpers, types, base classes, shared modules, or domain-specific building blocks the new work could build on instead of reimplementing. Look for both generic names (utils, helpers, shared, common) and domain-specific equivalents.
- **Convention Anchors** — The project's idiomatic way to do this kind of thing: file placement, naming, error handling boundaries, test structure, data flow. Report these as structural patterns (where code lives, how it is organized), not as cosmetic preferences.

When the task ports work across runtimes, languages, or frameworks, tag every mechanism inventoried under Analogous Features and Reusable Utilities as one of two kinds, in its description:

- **Domain guard** — protects an invariant of the problem itself that the target does not supply on its own. Re-express it in the target.
- **Runtime workaround** — exists because of the source runtime, its concurrency model, a library defect, or the limits of its test harness. Leave it behind; the target either supplies the property by construction or has its own idiom for it.

Recurring workaround shapes: isolation the target runtime already provides by construction, readiness or retry loops the target's driver, pool, or supervisor already supplies, test scaffolding built around one library's defect, version-gated migrations whose reason disappears with a fresh store, and compatibility fallbacks serving a single consumer. Report alongside the tag the probe that settles each classification: a search or count over the source showing whether the condition the mechanism guards against ever occurred.

### 3. Search Tactics

- Use `Glob` to find candidate files by name pattern
- Use `Grep` to find specific symbols, imports, or patterns across files
- Use `Read` only on files that `Glob` or `Grep` indicate are relevant
- Spawn multiple parallel tool calls in a single message when searching for different things simultaneously
- Target the search by keyword and file type. Avoid reading entire directories.
- When counting occurrences of a target (symbol, route, URL, identifier) to size a change's blast radius, enumerate it across all its syntactic forms — named reference, bare string literal, value passed into a helper where the assertion lives elsewhere — rather than trusting a single search pattern's count.

### 4. Read Named External Sources

A description of a source the task names outside this repo is a claim to verify, like a `file:line` citation about local code. Read the source and report what it holds, or state plainly that it could not be reached. A summary carried in a task description, a backlog entry, or an earlier artifact is never a finding on its own.

Read the source without changing it, leaving any repository it lives in as you found it. Before reporting a source as empty or thin, confirm the view you used shows everything it holds: shelved and unpublished work is often absent from the default listing.

### 5. Decide on Alignment

After searching, form a short recommendation: should the new work follow the patterns you found, deviate from them, or blend approaches? Base the recommendation on what exists, not on speculation about what could exist.

Treat as debt a workaround for a problem inside the codebase, a deprecated API with a usable replacement, a suppression directive with no stated reason, or a TODO marking code temporary. When the closest analog contains debt, recommend following its structure without the debt; when its structure is the debt, recommend the next clean analog. When every analog is debt, say so and name the debt the work would inherit by following one.

When the recommendation keeps the work inside the existing patterns, state what those patterns leave the work to handle.

When the recommendation carries a design from a named external source into this codebase, name the assumptions its original environment supplied, report which of them this codebase provides, and separate what the task asks for from what the design carried along.

## Output Format

Return findings as a single structured markdown block:

```markdown
## Pattern Survey

### Analogous Features
- `<path>:<line>` — <one-line description of how it works>
- ...

### Reusable Utilities
- `<path>:<line>` — `<functionName>` — <what it does and why it is relevant>
- ...

### Convention Anchors
- <convention name>: <brief description with file paths>
- ...

### Proposed Alignment
<1-3 sentences: should the new work follow these patterns, deviate, or blend? State the recommendation with reasoning.>
```

When the task ports work across runtimes, languages, or frameworks, open each Analogous Features and Reusable Utilities description with the mechanism's tag and the probe that settles it, before the rest of the description.

Open the description of an analog that contains debt with `Debt:` and the marker that shows it, placed after the port tag and its probe when the task is a port.

If a category has no findings, write "None found" under the header rather than omitting the section. If no analogous features exist at all, state that explicitly in Proposed Alignment rather than forcing a comparison.

Report what a named external source holds in whichever of the three categories it belongs to. Cite it so the source and the exact view are identifiable and the entry cannot be read as a local path, and say whether it is available in this codebase or is design-only material to carry over. When a named source could not be reached, state that in Proposed Alignment.

## Rules

- Do not write files.
- Do not propose implementation steps.
- Do not speculate. Report only patterns that exist right now, in the codebase or in a named external source you read.
- Flag only patterns that affect architecture, data flow, or where new code should live. Report naming and file placement as structural conventions, not cosmetic preferences.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall