AI / Agentic
Turn a Feature Request into an Agent Brief with Acceptance Cases
By Vivek Jalondhara · 5 min read
Published
Write an agent brief for an archived-notes filter, with observable outcomes, repository context, scope, and evidence for review.
An instruction such as add an archived-notes filter sounds specific until an agent has to choose what the filter means. Does enabling it show only archived notes or include them beside active notes? Does the preference survive navigation? A plausible implementation can answer both questions differently from the product owner.
This walkthrough turns that request into an actionable brief for an illustrative SmackDab CRM feature. Assume the fictional starting application already stores a note's archive state. The proposed filter and acceptance cases describe an exercise, not the private CRM's behaviour.
Start with the user's decision
The user wants to find older notes without losing access to current ones. Express that purpose before naming components: the default view contains active notes; an Include archived option adds archived notes the user can already access. Archive state and authorisation remain separate filters.
Add a concrete fixture. Note A is active and visible, note B is archived and visible, and note C is archived but inaccessible. The default returns A. Enabling the option returns A and B. C never appears. These expected identifiers remove the ambiguity that the word archived leaves behind.
Inspect the path the change must follow
Ask the agent to locate the existing note-list request, server query, visibility policy, and filter controls. It should report actual files and current behaviour before assuming a new service or schema is necessary. The useful result is a short dependency map, not a directory inventory.
Separate discovered facts from proposed decisions. If the repository already persists list preferences, reuse that convention unless it conflicts with the request. If no convention exists, choose a bounded initial behaviour and document it. An agent should not invent a global settings system to settle one missing preference.
Write cases as context, action, and outcome
Gherkin's Given, When, and Then structure provides one way to express a scenario. The value here is the separation of starting conditions, action, and observable result; adopting a new testing framework is unnecessary. The brief can use plain text while existing tests implement the checks.
Cover both positions of the toggle, clearing it, an empty result, and a rejected request. Specify that a failed refresh keeps the filter state visible and offers recovery rather than pretending the empty list is authoritative. This makes failure behaviour part of the feature instead of an afterthought.
Bound scope without hiding necessary integration
A small task can still span frontend and backend files. State that the option must reach the authorised server query and that the response must render consistently. A frontend-only filter over one page of results would misrepresent an archive distributed across several pages.
Keep unrelated work explicit: sorting, note editing, archive actions, and new preference storage are outside this exercise. Existing visibility and pagination contracts remain constraints. If a necessary integration cannot fit those constraints, the agent should describe the conflict before expanding the feature.
Name the evidence required for acceptance
Request focused examples proving the returned identifiers, plus a check that inaccessible notes remain excluded. Ask for the relevant test commands and observed results, including failures or checks that could not run. A statement that the task is complete is weaker than evidence connected to each scenario.
Review the actual query and the UI behaviour together. Google's code-review guidance calls attention to design, functionality, and how changes fit surrounding code. Applied here, that means checking whether the toggle changes the intended result set and whether the rest of the list still behaves coherently.
Keep the brief useful as discovery continues
Treat the brief as an agreed snapshot, not a command to ignore evidence. A discovered rule that archived notes require an additional capability changes the acceptance cases. Record that decision once and update both the task and verification expectations before continuing.
The tradeoff is a little more preparation in exchange for fewer hidden product choices. Avoid specifying every helper and line of code: that makes the brief brittle without clarifying behaviour. A good brief leaves implementation freedom while making the important outcomes difficult to misunderstand.
An archived-notes task brief
This practical brief gives the agent enough information to inspect and implement one feature. The fixture describes expected results independently of the eventual query.
Illustrative example · Task brief · Simplified for explanation
Task: add Include archived to the CRM notes list.
Default: show active notes the actor can access.
Enabled: show active and archived accessible notes.
Fixture: A active/visible, B archived/visible, C archived/hidden.
Expect default [A]; enabled [A, B]; cleared [A].
Preserve: visibility checks, ordering, and pagination.
Inspect: list UI, request contract, server filter, existing tests.
Deliver: focused change, acceptance evidence, unresolved assumptions.- Define the visible outcome
- Inspect the connected request path
- Write acceptance cases
- Implement and verify the bounded feature
Conceptual flow for the example above.
Tradeoff to keep in mind
The brief does not settle every product question. Its default behaviour and fixture are illustrative decisions that must be reconciled with the actual application's permissions and list conventions.