The Default Feature Contract

Feature Contract

Your spec, ready for a coding agent.

The Feature Contract is the default structure GapTrap uses to turn your brain-dump into a spec a coding agent can build from without guessing. You paste in what you want; GapTrap shapes it into eight clear sections, flags anything it had to assume, and holds the spec back until the gaps are closed. The result is a hand-off a coding agent can act on without inventing auth models, fabricating data schemas, or quietly building features you never asked for.

If your work needs a different shape, you can build your own template in GapTrap's template library. The eight sections below are what the default Feature Contract captures.

Why a contract, not a PRD or a brief

The Feature Contract exists to block the specific ways a coding agent goes wrong when it's handed a loose spec: invented login flows, made-up role hierarchies, fabricated database tables, edge cases nobody asked for, and adjacent features that balloon a one-day job into a four-week one.

Not a PRD. Not a brief. A contract.

A PRD implies a completeness this artifact doesn't promise. A brief implies looseness. Contract signals what this actually is: a binding hand-off from you to the agent, where every requirement can be tested as pass or fail.

What the contract consists of your words → eight sections → gated hand-off → agent

Intent

1Outcome & Why
2Actor & Trigger

Acceptance

3Functional Criteria
4Quality Floor

Boundaries

5Out of Scope
6Deferred
7Constraints

The gate

8Unresolved Assumptions

Blocks hand-off until resolved.

The principles behind it

What and why, never how.You describe the outcome you want and the reason behind it. The agent decides how to build it. Implementation choices aren't your job to guess.
Acceptance is binary.Every behaviour you ask for is written so it clearly passes or fails. Vague words you can't test — "robust", "seamless", "better", "fast" — don't survive, because nobody can confirm them.
Every value traces back to your words.Nothing in the finished spec is untethered. Each value is tagged with where it came from, and you can click to see the exact sentence of yours it rests on.
The empty box is a feature.When you haven't said something, GapTrap leaves the box empty and turns it into a question — rather than inventing a plausible-sounding answer that reads as if you'd decided it.
A focused set of eight sections.Each section guards against a specific failure. They aren't merged or padded, because every merge lets one of those failures back in. If you need a different shape, you build a different template — you don't stretch this one.

The eight sections

Each section below lists its purpose, when it's required, how to write it well, and an example paired with its anti-example. The How GapTrap fills it line tells you whether GapTrap will draft the section from your words or always stop and ask you.

Outcome & Why

Anchor the agent to the actual goal so it doesn't optimise toward a nearby goal it imagined.

Required: Yes
How GapTrap fills it: Drafts it from your words, then asks you to confirm — this is where a summary can drift, so your review matters most here.
How to write it: "Actor can observable outcome so that business or user reason." No solution verbs ("build", "implement", "integrate"). No adjectives without a referent ("better", "faster").

Example

"A logged-in customer can export their order history as CSV so that they can reconcile against their accounting tool."

Anti-example

"Improve the export experience for users."

Actor & Trigger

Stop the agent inventing entry points (a job? a webhook? a new dashboard?) and inventing roles and permissions.

Required: Yes
How GapTrap fills it: Uses what you stated; asks you when the actor or trigger is missing.
How to write it: A named role plus a concrete trigger event, tied to an existing screen where possible. No bare "user". No hints about the underlying mechanism.

Example

"Authenticated admin clicks Export on the existing orders page."

Anti-example

"Every 5 minutes a job runs and exports orders."

Functional Acceptance Criteria

Binary pass/fail checks. They close the loop — the agent can verify its own work against them.

Required: Yes
How GapTrap fills it: Drafts one criterion per thing you actually described; never invents a criterion you didn't imply.
How to write it: Given / When / Then. Up to four checks (extra ones move to Deferred). Each "Then" points to something observable. No "etc.", "and similar", "handles gracefully", "works smoothly".

Example

"Given the admin has 0 orders, When they click Export, Then a CSV with a header row only downloads."

Anti-example

"The export flow works well."

Quality Floor & Cheapest Acceptable Failure

Stop the agent inventing targets, retry loops and accessibility goals — and cap over-engineering by naming the ugliest failure you can live with.

Required: Optional. If you don't state one, GapTrap writes it down as "none stated; agent may pick a reasonable default and surface it."
How GapTrap fills it: Always asks you — never guesses. Asked for a number, people tend to invent one, so GapTrap won't put a number here on your behalf.
How to write it: Pair every threshold with a failure mode. No bare numbers. No naked adjectives. An acceptable failure is something observable.

Example

"Up to 10k rows export inline; beyond that, show 'too large — contact support'. If the export fails, show 'Export unavailable, try again' — no automatic retry, no alerting."

Anti-example

"Must be fast and reliable."

Out of Scope (the knife)

Force you to name, out loud, the capabilities the agent must NOT build even though they sit right next to what you asked for.

Required: Yes — the slot is mandatory. You may write "none", but only after you've reviewed it.
How GapTrap fills it: Drafts exclusions from things you ruled out ("not", "don't", "ignore"); otherwise asks you.
How to write it: Concrete excluded behaviours, not categories. No "advanced features later".

Example

"Does NOT include scheduled or recurring exports. Does NOT include XLSX or JSON formats. Does NOT include per-customer drilldown."

Anti-example

"Keep it MVP."

Deferred (with a revisit trigger)

Separate "not now" from "never". The agent won't pre-build for deferred items, but they aren't forgotten.

Required: Yes — the slot is present; it may be empty.
How GapTrap fills it: Drafts an item only when you also gave a condition for revisiting it; otherwise it asks you instead of recording a vague "later".
How to write it: "Item — revisit when observable condition." No bare dates without a trigger. No "later", "v2", "phase two".

Example

"XLSX/JSON export — revisit when more than 20% of CSV exporters ask for alternatives."

Anti-example

"Better export later."

Load-Bearing Constraints

Preserve the real-world facts the agent must obey — an existing service, a regulatory limit, a contract you're locked into — while filtering out casual technology preferences.

Required: Optional — the slot may be empty.
How GapTrap fills it: Records only constraints you stated explicitly, in your own words. It never infers a constraint.
How to write it: "Constraint because what breaks if it's dropped." If you can't say what breaks, it's a preference, not a constraint.

Example

"Must integrate with Stripe because we already have an active corporate Stripe account with monthly invoicing set up."

Anti-example

"Must use MongoDB." (No failure named — a preference dressed up as a constraint.)

Unresolved Assumptions (blocks hand-off)

Surface the known unknowns as questions the agent must ask — not invent. This section blocks the hand-off until they're answered.

Required: Yes — GapTrap fills this slot for you, from the gaps it finds elsewhere.
How GapTrap fills it: Always as questions, never as answers it decided for you.
How to write it: Each item names the missing decision as a yes/no or multiple-choice question, says which other section it's blocking, and may offer choices with a default and its trade-off — but never a default you haven't approved.

Example

"Q1 — Should the export rate-limit per user? (A) No until abuse is observed [default; cheaper]. (B) Yes, 10/hour [+1 day]. Blocks: Quality Floor."

Anti-example

"Probably yes for security."

How GapTrap stays honest

Every value in every section is tagged with where it came from, down to the individual check — so one acceptance criterion can be grounded in your words while another is flagged as a guess. The tags are:

StatedYou said this in your text. GapTrap keeps the exact quote.

InferredGapTrap proposed this from context — and still links it to the supporting sentence of yours.

ElicitedYou typed or chose this inside GapTrap after the first draft.

Not statedGapTrap refused to fill it; the question lives in Unresolved Assumptions instead.

Beside each section, a coloured band shows which tag applies — green for stated, yellow for inferred, blue for elicited, grey for not stated. Click any band to see the original sentence behind the value. The "Hand off to agent" button stays locked while any guessed value remains untouched by you.

The rule underneath all of this: if GapTrap can't point to your words to support a guess, it turns the guess into a question rather than putting words in your mouth. That one rule is what stops a hallucination from quietly becoming an authoritative-looking line in your spec.

When GapTrap drafts a section vs asks you

GapTrap never invents permissions, edge cases, performance numbers, or constraints. Where it has your words to lean on, it drafts and asks you to confirm. Where it doesn't, it asks.

Section	GapTrap drafts it when…	GapTrap asks you when…
Outcome & Why	Both the outcome and a reason are present — it drafts, then confirms with you.	There's no "so that", "because", or observable-change verb in your text.
Actor & Trigger	A named role and a trigger event are both stated.	Either the role or the trigger is missing.
Functional Acceptance	At least two observable conditions are present — one criterion per thing you described.	Fewer than two observable conditions are present.
Quality Floor	Never auto-fills — this is the false-precision trap.	Always, unless you gave both a number and a failure mode ("timeout", "drop", "degrade", "block").
Out of Scope	You ruled something out explicitly.	You named no exclusions.
Deferred	An item and its revisit trigger are both present.	An item is named with no revisit condition.
Load-Bearing Constraints	A constraint comes with its "because / what breaks" rationale.	A constraint is stated with no rationale.
Unresolved Assumptions	— this section collects the questions from everywhere else.	—

What the Feature Contract deliberately leaves out

Some things look like they belong in a spec but actually invite the agent to guess. The Feature Contract has no slot for them, and GapTrap will not fill them in:

	Left out	Why
	Tech stack / framework choice	The agent's call. Your guesses lock in architecture you may not want.
	Data model / schema / tables	Forces design too early; only user-visible state belongs in acceptance.
	Architecture / system design	That's "how", which belongs to the agent.
	Implementation hints	Casual mentions of a queue, a token scheme, or a cache get treated as hard requirements.
	User stories ("As a user, I want…")	The agent reads "manage users" and builds four weeks of role management you never asked for.
	Priority / effort estimate	GapTrap would fabricate it, and it isn't something the agent can act on.
	Success metric beyond the Outcome	Invites invented KPIs like "50% reduction in time-to-find".
	Background / context summary	A favourite place for invented detail, and it duplicates Outcome and Trigger.
	User persona description	GapTrap would invent demographics; the Actor section already covers who.
	Risks	Open-ended — gets filled with generic placeholders.
	Design inspiration / UI vibes	Agents copy irrelevant behaviour unless it's turned into a concrete acceptance check.
	Future vision	It belongs in Deferred with a revisit trigger, or it doesn't exist yet.

Checks GapTrap runs before hand-off

An automatic review of your spec

Before you even see the draft, GapTrap catches vague wording, acceptance criteria with no observable result, deferred items with no revisit trigger, and constraints with no rationale. Anything it catches becomes a question in Unresolved Assumptions.

The hand-off gate

No guessed value leaves GapTrap without you looking at it. The "Hand off to agent" button stays locked until every yellow-banded value has been reviewed.

A codebase cross-check Coming later

When GapTrap has access to your existing code, it will compare what the spec implies against your current conventions, data, and login flow, and surface any conflicts. This one is planned, not available today.

Where you still need judgment

No template catches everything. Here's what this one still leaves to you, and how it tries to help:

Watch out for	What helps
A summary that quietly shifts the subject	The Outcome reads as grounded but names the wrong person — so reviewing it is mandatory, and GapTrap shows the original sentence right below it.
A preference disguised as a constraint	"Must use MongoDB" with an invented reason — GapTrap flags technology-flavoured wording in Constraints for your review, though a determined phrasing can slip past.
Edge cases between the checks	Race conditions, two people editing at once — keeping acceptance strict and testable is a deliberate trade-off for early-stage work; it's not built to cover everything at scale.
A made-up performance number	Prompted for one, you reach for "2 seconds" with no evidence — so the Quality Floor offers an explicit "none stated" path; you're never forced to invent a figure.
"Let's do both" creeping back in	Reopening a decision in free-text — Unresolved Assumptions favours multiple-choice questions with a clear default wherever the options are known.