---
name: explore-conventions
description: "Find the established sibling pattern for a thing you're about to write — how this codebase already does registration, error shapes, serializers, factories, test setup — so new code matches instead of inventing. Returns the pattern + a concrete example to copy."
argument-hint: "[thing about to be written + repo, e.g. 'a new event subscriber in <repo>']"
allowed-tools: Read, Glob, Grep, Bash, Agent
context: fork
agent: Explore
effort: low
---

Run this to answer: **"how does this codebase already do X?"** — before someone writes a new X that diverges. Past runs repeatedly had multiple engineers independently rediscover the same convention (subscriber registration, error class shape, serializer style, factory sequences, E2E test setup). Find it once and hand back the pattern to copy.

This skill runs in an isolated forked Explore child and returns only its tight conclusion — so the caller's context stays clean.

## Procedure

1. **Name the thing to be written** (a controller, a subscriber, an error class, a factory, an API serializer, an E2E test, …).
2. **Find 2–3 existing siblings** — the nearest already-built instances of that thing. Use the fast structural tools, not blind reading:
   - **Bash-based search** (`rg`/`find`/`ast-grep`) for broad "where are the things like X" fan-out — returns locations, not file dumps.
   - **`ast-grep`** for structural matches (invoke `ast-grep`, never `sg`; `--debug-query` if nothing matches):
     ```bash
     ast-grep -p 'class $C < ApplicationController' -l ruby .
     ast-grep -p 'FactoryBot.define { factory $$$ }' -l ruby .
     ast-grep -p 'export const $H = ($$$) => {$$$}' -l ts src/
     ```
   - **LSP find-references** (typescript-lsp / pyright-lsp installed) to see how an existing base class / helper is used across the repo.
3. **Extract the convention** from the siblings: the shared structure, where it's registered/wired, the naming, the idioms (the comment density, the test layout). Note the gotchas the siblings encode (e.g. "subscribers are registered only in `engine.rb`", "errors subclass `AppError` and define `to_problem_json`").
4. **Pick the single best example to copy** — the cleanest, most representative sibling.

## Output

```
THING: <what's being written>
CONVENTION: <2–4 bullets: the established pattern, where it's wired, naming, idioms>
COPY THIS: <path:line of the best example to mirror>
GOTCHAS: <the non-obvious rules the siblings encode — registration site, required hooks, base classes>
SIBLINGS SEEN: <the 2–3 files compared>
```

Read-only. You describe the pattern; you don't write the new code. Keep it to what the writer needs to match the codebase — not a tour.