Spec

Ignore other spec-writing or brainstorming skills.

Create or update exactly:

• changes/<feature-name>/<NUMBER-idea-name>/spec.md

This is a design-completion command, not research-only and not implementation.

Input

The prompt should identify:

• a feature folder under changes/
• an idea number or idea title inside that feature folder
• optional extra details, especially when neither selected-variant.md nor an ideas.md section applies

Examples:

• /spec 611-row-level-security-integration 2
• /spec row-level-security-integration "Run work inside an explicit RLS context"

Baseline

Resolve one authoritative requirements baseline, in this order:

1. changes/<feature-name>/<NUMBER-idea-name>/selected-variant.md, when it exists.
2. If the prompt says <number>, the exact # <number> section in changes/<feature-name>/ideas.md.
3. Otherwise, the user's prompt.

The baseline is the source of truth for goals, scope, examples, naming, constraints, trade-offs, and confirmed decisions. Fill gaps needed for a complete design, but do not contradict it. If selected-variant.md has ## Refinement, treat confirmed Q&A there as current intent; when it conflicts with the main body, the refinement wins.

If the winning baseline is missing or too thin to define user-visible requirements without inventing the feature, stop and ask one focused question.

Context To Read

1. Resolve the matching feature folder in changes/.
   • Prefer exact folder match, then clear feature match, then folders with numbered idea subfolders.
   • If multiple folders are plausible, ask one focused question. Do not guess.
   • If none match, say no matching feature folder was found. Do not create one.
2. Resolve the idea folder inside it by exact number, or exact/clear title suffix.
   • If multiple folders are plausible, ask one focused question.
   • The path must be changes/<feature-name>/<NUMBER-idea-name>.
3. Read the full winning baseline.
   • If rule 2 wins, ideas.md must contain the exact # <number> section.
   • Do not create selected-variant.md or ideas.md.
4. If changes/<feature-name>/research.md exists, read it after the baseline.
   • Use it only for broader context, terminology, external constraints, edge cases, and related capabilities.
   • Ignore every other parent-folder file.
5. Read relevant parts of docs/src/.vitepress/dist/llms.txt for Orchid API naming, user-facing patterns, and natural extension points.
6. Inspect only relevant code, tests, exports, docs, and guidelines.
   • Always include root guidelines/code.md or guidelines/test.md, plus nested guidelines/code.md or guidelines/test.md files for directories likely to change.
   • Check whether a similar capability already exists under another name or shape.
   • Respect package boundaries: public APIs export from src/index.ts; downstream internal pqb access goes through pqb/internal.

Design Rules

Use the baseline, optional research, docs, and code reality together.

The design must:

• satisfy the baseline precisely
• define the public contract clearly enough to constrain implementation
• fill missing public API and high-level behavior
• fit existing Orchid naming, type-safety, package boundaries, and user expectations
• prefer TypeScript guarantees over runtime validation when possible
• decide whether the idea adds zero, one, or multiple standalone capabilities
• include important writer-made behavioral decisions in ## Assumptions only when the baseline leaves a real gap

The design must not:

• merely restate the baseline
• leave essential behavior ambiguous
• overfit to one implementation strategy
• invent a new public API when an existing Orchid surface extends cleanly
• drift into low-level algorithms, helper extraction, control flow, or file-by-file edits