Spec an AI app's inputs, outputs and model stages before any code

Write the input/output spec for an AI web app before any code exists. The spec is the contract the build follows: it names every input, every output, every model call and every check, so the model's job inside the app stays narrow and testable.

App idea:
{{app_idea}}

Users: {{users}}
Constraints (stack, storage, sign-in, language, currency, units): {{constraints}}
Model budget per run (if blank, propose one): {{model_budget}}

Write Markdown with exactly these sections, in this order. Prefer tables to prose, one line per row.

0. Decisions. Open with one line naming the file that will hold the types: the single source of truth for every shape below. Then list each decision the idea leaves open, with the simplest choice marked **Assumed**. Never assume a country, currency, language or unit system the idea doesn't state.

1. Flow. Every step from first input to export, including steps with no model call. Columns: Step | Input | Processing | Output | Model calls.

2. Inputs. One table per input object. Columns: Field | Type | Range / values | Default | Used for.
- "Used for" names the stage that reads the field. Cut any field no stage reads.
- Give each enum value its meaning in numbers ("quick = under 20 min"), not just its name.
- Defaults are neutral. Required fields default to blank and block the run with a message naming the missing field.

3. Outputs. The stored shape, JSON-schema style. Columns: Field | Type | Content. Every number has a unit (minutes, grams, currency) and a basis (per person, per group, per unit). Give id formats and enum values. Mark the origin of every editable item or value (model or user). Then a "Coercion" line: how code turns loose model JSON into this exact shape (numbers parsed from strings, missing ids generated, unknown enum values fall back to a named default, an empty result rejected). Then the job-state shape (status, stage, partial results, cost so far) and a storage table: Key | Value | Retention | Who can delete it.

4. Pipeline. Columns: Stage | Who (model, code, or code lookup: <library or API>) | Input | Output.
- The model proposes; code derives. Anything computable from other values (dates, counts, sums, totals, verdicts, final times, ids) is computed in code. Ask the model for unit values, never totals. Any sentence that states a derived number (summaries, verdicts, assumptions, check messages) is written by code from a template using the same variables.
- Facts a library or API can supply (calendars and holidays, weather, daylight, exchange rates, distances) are looked up in code. Name the source. A model value is only a labelled fallback when the lookup fails.
- Split any "write the whole thing" call into stages whose output can each be checked. Batch repeated units, with a stated batch size, so one bad unit can be redone alone.
- For each model stage, state the model tier (fast or strong), reasoning effort, tools (web search or none) and the JSON it returns. Keep that JSON small and flat. Use the API's structured-output mode with it where available, and still coerce in code: code checks ranges and lengths, and a refusal or max_tokens stop can still break the shape.
- Code computes each unit's constraints and passes them in as short lines, with a list of what is already used so nothing repeats.
- If a fact can't be verified, the model returns it empty and code uses a named safe fallback. The model never invents one. Code also checks each fact the model does give against a bound it can verify (an enum, a distance, a range); a fact that fails takes the same fallback.

5. Checks in code. Columns: Check | Level | Rule | On failure.
Levels: P0 consistency (totals recompute from their lines, counts agree, ids unique, numbers quoted in text match the computed values), P1 feasibility (real-world limits), P2 fit to the user's input, P3 data quality. On failure: repair in code, or re-prompt only the failing unit, with its current version and the violations listed, and tell it to change nothing else. At most 2 rounds, then ship with the failed check visible. Store the results on the output and show them to the user. Never grade content the user wrote (use the origin marks from section 3).

6. Re-runs. If users can edit the output and regenerate, a table of what a re-run keeps and how: locked items, items the user added, values the user changed on model-made items (kept, never overwritten), and ids (never reused for a different thing, so references don't move).

7. Cost per run. Columns: Action | Model calls | Tier | Tools | Typical input / output tokens | Cap. Say what is metered (input tokens, output tokens including thinking, cache reads and writes, searches), what context is cached across calls, and the per-visitor caps. Fit the model budget. Give each charge or cap increment a unique ref so a retry never counts twice, and state what a failed or cancelled run counts. Don't quote prices from memory: write cost as a formula over per-token prices the builder fills in.

8. Failures. Columns: Failure | Detected by | Fallback | What the user sees. Cover at least: malformed or truncated JSON (repair, then one retry), rate limit or quota (one short backoff, then a fallback model or provider; state the SDK's own retry setting so retries don't stack), a run longer than one request should last (a server-side job the client polls, which survives reloads), a cancelled run, checks still failing after the last round, and every fallback from section 4.

9. API. Columns: Method | Path | Auth | Body → Response. Keep every route under /api. Long model work is a POST that creates a job, then a GET that polls it. End with one line of error codes, each with its JSON body.

10. Test fixtures. Three regression inputs (typical, edge case, hostile) and a scripted mock model that returns known-bad output. Name the checks each one must trip and the ones it must pass.

Write the spec only, no code. If the idea is too thin for a section, fill it with assumptions marked **Assumed** rather than skip it.

Show all 44 lines