Design Prompts

Design prompts produce artifacts humans approve; they do not produce production code. Run in plan mode. If the output is good enough to reuse, commit it as a spec or ADR — don't leave it in chat (Prompts vs Specs). Companion reading: Exploring Options, Decision Records.

Database design

Design a schema with ownership, constraints, and migration risk made explicit.

Inputs: <domain description>, <existing tables or "greenfield">, <DB engine>, <consistency requirements>

Design a database schema — no application code.

Domain: <domain description>
Existing schema: <existing tables or "greenfield">
Engine: <DB engine>
Consistency requirements: <consistency requirements>

Deliver:
1. Entity list with ownership (which service/module writes).
2. Tables: columns, types, nullability, defaults, PK/FK, unique
   constraints, indexes (and why each index exists).
3. Invariants that must hold (express as CHECK / app-enforced /
   both).
4. Migration plan from current state (steps, expand/contract if needed).
5. Dangerous queries you expect (list) and how indexes cover them.
6. Explicit non-goals (no soft-delete everywhere, no EAV, etc. unless
   justified).

Flag any decision that needs an ADR. Do not invent entities outside
the domain description.

Expected output: schema design + migration plan + invariants + index rationale.

Evaluate: Every index has a query. Invariants aren't "hope the app remembers." Migration is expand/contract safe if you have zero-downtime needs.

Variations:

• Require Postgres-specific features only / forbid them.
• Add multi-tenant isolation model as a first-class section.

API design

Specify HTTP (or RPC) contracts before handlers exist.

Inputs: <capability>, <auth model>, <error envelope example path>, <compatibility constraints>

Design the API for: <capability>
Auth model: <auth model>
Match error envelope in: <error envelope example path>
Compatibility: <compatibility constraints>

Produce an API design doc:
1. Resources and route table (method, path, authz, idempotency).
2. Request/response JSON schemas (fields, types, required).
3. Error cases with status codes mapped to the existing envelope.
4. Pagination / filtering / sorting conventions — match repo if one
   exists; otherwise propose one and mark it as a convention decision.
5. Versioning / compatibility notes.
6. Sequence diagram for the critical write path (mermaid).

Do not implement handlers. List open questions that block coding.

Expected output: route table, schemas, errors, conventions, sequence diagram, open questions.

Evaluate: Idempotency called out on writes. Errors match the envelope file. No "flexible JSON blob" where a schema belongs.

Variations:

• Constrain to OpenAPI 3.1 output only.
• Design events/webhooks instead of request/response.

Data model

Clarify domain objects and transitions without jumping to tables or UI.

Inputs: <feature or domain>, <existing model files>, <lifecycle events>

Define the domain data model for: <feature or domain>
Existing models to respect: <existing model files>
Lifecycle events that matter: <lifecycle events>

Output:
1. Objects + fields (conceptual, not ORM).
2. Allowed state transitions (table or mermaid stateDiagram).
3. Derived vs stored fields.
4. Identity and uniqueness rules.
5. Cross-object invariants.
6. Mapping notes to persistence (what becomes a column vs JSON vs
   separate table) — recommendations only.

Do not write migrations or UI. Call out where the existing models
conflict with this design.

Expected output: conceptual model, transitions, invariants, persistence mapping notes.

Evaluate: Illegal transitions are named. Conflicts with existing models are explicit, not papered over.

Variations:

• Focus only on money/ledger semantics.
• Produce TypeScript types as the canonical model artifact.

UI / screen design

Specify screens and states an implementer can build without inventing UX policy.

Inputs: <user job>, <existing design system / component paths>, <breakpoints>, <accessibility bar>

Design UI for: <user job>
Reuse components from: <existing design system / component paths>
Breakpoints: <breakpoints>
A11y bar: <accessibility bar>

Deliver a screen design brief:
1. Screen list + primary user path.
2. Per screen: purpose, key components (reuse names from the design
   system), empty/loading/error/success states.
3. Copy guidelines (tone, must-have strings, forbidden patterns).
4. Form validation rules (field-level).
5. Navigation and permission-gated elements.
6. Non-goals (no new design system primitives unless justified).

Do not write React/Vue/etc. yet. If a needed component doesn't exist,
propose the minimal primitive — don't invent a second design system.

Expected output: screen briefs with states, validation, reuse map, non-goals.

Evaluate: Empty/error states exist. Components map to real paths. No parallel design language.

Variations:

• Add analytics events per interaction.
• Constrain to mobile-first only.

ADR drafting

Turn a decision into a durable Architecture Decision Record.

Inputs: <decision title>, <context>, <options considered>, <constraints>

Draft an ADR for: <decision title>

Context: <context>
Options we considered: <options considered>
Constraints: <constraints>

Use this structure:
# ADR-XXX: <title>
## Status: Proposed
## Context
## Decision
## Consequences (positive / negative / neutral)
## Alternatives considered (and why rejected)
## Compliance (how we will notice if this is violated)

Be specific to THIS codebase — cite paths and systems. No generic
cloud essays. Keep it ≤ ~1 page. Do not implement the decision.

Expected output: one ADR markdown ready to commit under docs/adr/ (or your convention).

Evaluate: Decision is one clear choice. Consequences include downsides. Alternatives aren't strawmen. See Decision Records.

Variations:

• Status Accepted with date and decider name.
• Add a "Migration plan" section for reversible decisions.

Architecture options comparison

Compare approaches with evidence, not vibes.

Inputs: <problem>, <must-haves>, <nice-to-haves>, <options to compare or "propose 3">

Compare architecture options for: <problem>
Must-haves: <must-haves>
Nice-to-haves: <nice-to-haves>
Options: <options to compare or "propose 3">

For each option:
- How it works (10 lines max)
- Fit to must-haves (pass/fail per item)
- Cost: build, operate, migrate
- Failure modes unique to this option
- What it makes harder later

Then recommend one option OR recommend a time-boxed spike.
Include a decision matrix table. Cite repo evidence where relevant.
Do not write code.

Expected output: options write-up, matrix, recommendation or spike.

Evaluate: Must-haves are pass/fail, not narrative. Recommendation names what evidence would overturn it.

Variations:

• Force inclusion of "do nothing / delay" as an option.
• Limit to options that reuse an existing deployable.

Threat modeling sketch

Produce a lightweight threat model before security-sensitive work.

Inputs: <system or feature>, <trust boundaries>, <data classes>, <attacker assumptions>

Sketch a threat model for: <system or feature>
Trust boundaries: <trust boundaries>
Data classes: <data classes>
Attacker assumptions: <attacker assumptions>

Deliver:
1. Data-flow diagram (mermaid) with trust boundaries marked.
2. STRIDE-style threats per boundary (table: threat, impact,
   likelihood, mitigation, residual risk).
3. Abuses of the happy path (authz bypass, IDOR, replay, injection).
4. Logging/alerting gaps that would hide an exploit.
5. Test ideas that would catch the top 5 threats.
6. What is OUT of scope for this sketch.

Do not implement mitigations yet. Rank findings by exploitability
in OUR deployment, not generic OWASP lists.

Expected output: DFD, threat table, abuse cases, test ideas, out-of-scope.

Evaluate: Threats map to your boundaries. Mitigations are concrete. Top risks have test ideas. Not a copy-paste OWASP dump.

Variations:

• Focus only on multi-tenant isolation.
• Pair with Security review after implementation.

Interface contract freeze

Freeze shared interfaces so parallel agents don't invent conflicting shapes.

Inputs: <modules that will be built in parallel>, <owner of the contract>, <compatibility rule>

Define and freeze interface contracts for parallel work.

Modules: <modules that will be built in parallel>
Contract owner: <owner of the contract>
Compatibility rule: <compatibility rule>

Produce:
1. Shared types / DTOs / events (canonical definitions).
2. Error and empty-state semantics.
3. Versioning / compatibility rule restated as enforceable checks.
4. Fixture examples (valid + invalid) for each contract.
5. "Change control": what requires a human ADR vs a PR comment.

Output as a single markdown contract file. Do not implement modules.
Mark anything still ambiguous as BLOCKING.

Expected output: contract markdown with fixtures and change-control rules.

Evaluate: Fixtures exist. Ambiguities are BLOCKING, not TODOs. Parallel modules could implement against this without chatting.

Variations:

• Emit JSON Schema or OpenAPI as the frozen artifact.
• Use before Interface-first parallel prep.

Related

• Exploring Options — comparison discipline
• Decision Records — ADR lifecycle
• Constraints & Validation — making designs enforceable
• What Not to Delegate — design decisions that stay human
• Writing Effective Specs — turning design output into committed specs
• Architecture & Research Prompts — pattern rationale