Standards Discovery

# Setup: Standards Discovery

**Purpose:** Extract your team's opinionated coding patterns from existing source code into documented, reusable standards.
**When to run:** After `stack-discovery.md` and `architecture-discovery.md`. Run once per focus area; repeat for additional areas as needed.
**Output:** Standard files in `.smiddy/governance/standards/<category>/` and an updated `.smiddy/governance/standards/index.yml`.

> **What this is not:** This prompt does not rediscover the tech stack (tools, versions) or system architecture (components, data flows). It discovers *how* your team writes code within that stack — patterns that a new developer or AI agent would not know without being told.

---

## Instructions

Your job is to read existing source code and surface patterns that are opinionated, tribal, or repeated — then document them as concise standards that future agents can use without re-reading the whole codebase.

### Step 1 — Check existing standards

Read `.smiddy/governance/standards/index.yml` to see what has already been documented. This prevents duplicating standards already captured.

If the file does not exist or is empty, there are no existing standards yet.

### Step 2 — Identify focus areas

Scan the top-level source directories to identify 3–5 candidate focus areas. A focus area should correspond to a part of the codebase with enough code to have consistent patterns.

Examples of useful focus areas:

- **Conventions** — naming, file structure, error handling patterns, commit format. Start here if running standards-discovery for the first time; these are the highest-value standards for a new agent to know.
- **API routes** — how requests are handled, responses structured, errors returned
- **Database** — how queries are written, transactions managed, migrations structured
- **Testing** — how tests are named, structured, what gets mocked vs. faked
- **Error handling** — error classes, codes, propagation strategy
- **Frontend components** — component structure, state management, styling patterns
- **Validation** — where and how input is validated
- **Logging** — what gets logged, at what level, with what context

If `stack-discovery.md` was run first, it may have noted observed conventions as suggested starting areas — use those as candidates.

Present the areas you identified and ask the user to select one to start with.

### Step 3 — Analyse the chosen area

Read 5–10 representative source files from the chosen area. Look specifically for patterns that are:

- **Opinionated** — choices that could have gone differently (e.g. cursor-based pagination instead of offset)
- **Tribal** — things a new contributor would not know without being told (e.g. custom error codes, specific response shapes)
- **Consistent** — patterns repeated across multiple files, not one-offs

Do not surface patterns that are standard framework behavior, widely documented library conventions, or obvious from the tooling.

### Step 4 — Present findings

List 3–6 candidate standards found in the chosen area. For each, provide:

- A short name
- One sentence describing the pattern observed
- 2–3 example files where you found it

Ask the user which to document. They can select all, a subset, or suggest corrections.

### Step 5 — For each selected standard, capture the rationale

Process one standard at a time. Before drafting, ask 1–2 clarifying questions to understand the *why*. For example:

- "What problem does this pattern solve? Why not use [the common alternative]?"
- "Are there situations where this pattern should not be used?"
- "What is the most common mistake a new developer or AI agent makes with this?"

Wait for the user's response before drafting.

### Step 6 — Draft the standard

Using the user's answers, draft the standard following this format exactly: