# Bring-Your-Own Spec Canvas - substrate (c)

> **For teams who bring their own idea.** You don't have to build `/recommend` or start from the blank skeleton - you can spec a small slice of something real to *your* world. This canvas keeps you honest: same spec-first discipline, same Definition of Done, scoped to one endpoint so you can actually finish in 55 minutes.
>
> Fill the six boxes top to bottom. Each box flows into the next - the contract is written *from* the acceptance criteria, the DoD checks the contract. That's [Way #1](../../ways-of-working.md). Freeze it at Gate 1 before you write code.

---

## The canvas - fill top to bottom

### 1. Problem (one sentence)
*What can't someone do today? Whose pain?*

> ▸ _______________________________________________

### 2. Consumers (who calls it, what they do with the answer)
*Name the caller and the screen/job. API-as-a-product (`REQ-API-1`).*

| Consumer | What they do with the response |
|---|---|
| | |
| | |

### 3. One endpoint (method + path)
*Exactly one. Pick the smallest slice that proves the idea.* (`ENG-PRIN-INCR-STMT` - small steps.)

> ▸ `GET /api/__________`  - or  `POST /api/__________`
>
> If it's a `POST` (a write), note that retries need an `Idempotency-Key` (`REQ-API-6`). If it's a `GET`, it's safe and idempotent already - no key needed.

### 4. Acceptance criteria (the demo checklist)
*Concrete, testable. These become your contract assertions and your tests.*

- [ ] …
- [ ] …
- [ ] Errors use the shared RFC 7807 `Problem` envelope (`REQ-API-5`).

### 5. Contract (the response shape)
*Write the schema BEFORE the code. Start from [`greenfield-openapi-skeleton.yaml`](greenfield-openapi-skeleton.yaml), rename the resource, fill in your fields. This is the machine-readable contract the whole team works from (`REQ-API-2`).*

> ▸ Schema name: ______________  ▸ Required fields: ______________________
>
> ▸ Lives in: `./<your-api>.openapi.yaml`

### 6. Definition of Done (`QUAL-PRINC-SDLC`)
*The same bar as everyone else - no shortcuts because it's your own idea.*

- [ ] Contract written and frozen (`REQ-API-2`)
- [ ] One unit test for the core logic at the lowest viable layer (`QTEST-EARLY`)
- [ ] One contract test: the response validates against your OpenAPI schema (`REQ-API-7`, `QTEST-CONTRACT`)
- [ ] One E2E happy path (`QTEST-E2E`)
- [ ] A human reviewed and approved - no self-merge (`ENG-PRIN-REVIEW-STMT`, [Way #2](../../ways-of-working.md))
- [ ] One ADR capturing the key trade-off ([`adr-template.md`](adr-template.md), [Way #5](../../ways-of-working.md))

---

## Guardrails - non-negotiable

| Rule | Why |
|---|---|
| **No secrets in prompts.** No API keys, tokens, credentials, real customer data, or PII. | [Way #3: Mind what you feed it](../../ways-of-working.md). Treat every prompt like a public postcard. |
| **No prod systems.** Don't connect to anything real - no live databases, internal APIs, or production endpoints. | This is a sandbox. Blast radius = zero. |
| **One endpoint only.** Resist scope creep; ship one slice that works. | `ENG-PRIN-SIMPLE-STMT` (YAGNI), `ENG-PRIN-INCR-STMT` (small steps). A finished slice beats a half-built epic. |
| **Synthetic data only.** Invent rows. Anonymise anything inspired by reality (Person A, Vendor 1). | [Way #3](../../ways-of-working.md). |
| **Same DoD as everyone.** The bar in box 6 applies to your idea too. | `QUAL-PRINC-SDLC` - fairness and a real teaching point. |

---

*Stuck for an idea? The `/recommend` worked example in [`feature-spec-template.md`](feature-spec-template.md) is the reference shape. The five ways: [ways-of-working.md](../../ways-of-working.md).*