Intent brief

Purpose

An intent brief is the task contract for a software-factory run. It records the requested outcome, the allowed scope, the constraints, and the evidence that will count as completion. Workers use it to decide what to change. Evaluators use the same brief to decide whether the result satisfies the request.

The brief should be assigned an immutable identifier and version. If the intent changes during a run, issue a new version and record why. Do not silently edit the contract after work has started.

When to use

Create an intent brief before work crosses a trust boundary or consumes a meaningful budget. It is useful when a task can produce a code change, alter an environment, publish an artifact, or require another person to review a result.

A short conversational request may be enough for private exploration. Convert it into a brief before the workflow can merge, deploy, spend money, modify customer data, or make a public claim.

Inputs and outputs

Inputs:

• a requested outcome in observable terms;
• the repositories, services, files, or environments in scope;
• explicit exclusions and prohibited actions;
• acceptance checks and required evidence;
• budget, deadline, and authority constraints;
• the owner who can resolve ambiguity or approve a revised intent.

Outputs:

• a stable brief identifier and version;
• a normalized task contract that workers and evaluators can read;
• a list of unresolved assumptions, if any;
• a change record when a later version replaces the original.

Smallest useful interface

The smallest useful interface accepts a brief, validates the required fields, and returns a stored reference. The store should preserve prior versions.

type IntentBrief = {
  id: string;
  version: number;
  owner: string;
  outcome: string;
  scope: string[];
  exclusions: string[];
  acceptance: string[];
  constraints: string[];
  assumptions: string[];
};

type IntentBriefRef = {
  id: string;
  version: number;
  digest: string;
};

function registerIntent(brief: IntentBrief): IntentBriefRef;

Downstream records should carry the returned reference rather than copying a mutable description of the task.

Example

id: checkout-timeout-fix
version: 1
owner: payments-platform
outcome: Checkout requests return a controlled retry response when the tax service times out.
scope:
  - services/checkout
  - tests/integration/checkout
exclusions:
  - tax-service deployment
  - production configuration changes
acceptance:
  - The timeout path returns the documented retry response.
  - Existing successful checkout tests still pass.
  - The evidence packet includes the focused test output and changed-file list.
constraints:
  - Do not change the public success response.
  - Stop before merge and request human approval.
assumptions:
  - The existing tax client exposes timeout errors separately from other failures.

The worker can challenge the final assumption after inspecting the code. If it is false and changes the requested approach, the owner issues version 2 instead of letting the worker reinterpret the task on its own.

Failure modes

• The outcome describes an activity. “Improve checkout” does not say what should become observably different. Ask the owner for a result and a check.
• Scope names a repository but no boundary. A worker may make broad changes that are technically related. Add included paths, excluded systems, or both.
• Acceptance checks are written after implementation. The checks can end up favoring the chosen solution. Define them before assigning the worker.
• The brief changes in place. Evidence from different interpretations gets mixed into one run. Create a new version and link it to the superseded one.
• Unknowns are hidden as facts. Record assumptions explicitly. Route a disproved assumption to the owner when it affects scope, risk, or acceptance.
• The worker can approve its own reinterpretation. Give change authority to the named owner or another role outside the worker that proposes the change.

What it does not solve

An intent brief does not prove that the requested change is correct, worthwhile, or safe. It does not replace product prioritization, technical design, policy checks, evaluation, or approval. It also cannot remove ambiguity by adding more fields. When the owner cannot state an observable outcome, the workflow should remain in discovery rather than manufacture a precise-looking contract.

Related reading

• Policy gate
• Evidence packet
• Human approval checkpoint
• Build the checks before you build the agent