AI / Agentic
Five Artefacts to Inspect Before Accepting an AI-Written Feature
By Vivek Jalondhara · 4 min read
Published
Review a proposed CRM note-pinning feature through its behaviour contract, connected diff, evidence, data change, and handoff.
A generated feature needs more than a convincing demo. Reviewers need enough evidence to understand what it promises, how the change fits the application, and what remains uncertain. A small set of artefacts can make that review concrete without creating a large approval document.
This illustrative SmackDab CRM feature lets a user pin one accessible note to a record for their own view. Pinning another note replaces their previous pin for that record. The behaviour and artefacts below are proposed examples, not private implementation details.
1. The behaviour contract
The first artefact states who acts, what changes, and what stays independent. Here, a pin belongs to the current user and record. It does not change the note's visibility, alter another user's pin, or grant access to the note. Removing a pin changes the personal association, not the note itself.
Use two actors and two notes in the acceptance example. Actor A pins note one and then note two; A sees note two pinned, while actor B's view is unchanged. Include the case where access to a pinned note is later removed. Decide whether the UI hides the association or presents an unavailable state without exposing protected content.
2. The connected change
A focused diff is the second artefact, accompanied by a short map of the affected path: control, request, authorisation, persistence, and list response. The map helps a reviewer locate the consequence of each change without reading unrelated modules. The actual code remains the evidence; the map does not replace inspection.
Watch for a generated implementation that updates only local state or derives the acting user from an editable request field. Check that pinning a note requires access to the relevant record and note relationship. Google's review guidance emphasizes examining how a change works with surrounding code, which is especially useful when the visible button is only the start of the operation.
3. The acceptance evidence
The third artefact ties observed results to the contract. It should show that the second pin replaces the first for the same actor and record, that another actor is unaffected, and that an inaccessible note cannot be pinned. An error response should accompany unchanged associations when the request is rejected.
Check uncertain network outcomes too. Repeating a request to pin the same note should have a defined result rather than creating duplicate associations. Name which checks exercised actual persistence and which used a mocked service. A single screenshot can demonstrate placement and labels, but cannot establish authorisation, isolation, or retry behaviour.
4. The data and compatibility change
The fourth artefact explains any stored-data change and how existing records behave. A possible design stores at most one association for a workspace, actor, and CRM record. PostgreSQL unique constraints can enforce a declared key; the application still needs to validate the note relationship and the actor's authority.
Consider two concurrent pin requests and decide whether the final association follows the last successful update or requires a version check. Describe the no-association state for existing records and how older clients handle a new optional response field. A generated migration is reviewable only when its assumptions and compatibility consequences are visible.
5. The handoff with limits and recovery
The fifth artefact is a concise account of what was verified, what failed, and what the next maintainer needs to know. Include the relevant commands or observations and identify missing checks. Do not replace an unavailable integration test with an unqualified claim that everything passes.
Describe how to disable the feature if the UI misbehaves and what happens to stored pin associations afterward. Removing a control does not automatically remove data or repair an incorrect association. The tradeoff is a little evidence organization in exchange for a feature that can be assessed and maintained; keep the handoff proportional to the actual change.
An evidence manifest for a personal note pin
This JSON template names the review artefacts and required evidence. It is a proposed checklist, not a report of completed tests. Replace the requested evidence with observed results for a concrete feature.
Illustrative example · JSON · Simplified for explanation
{
"feature": "personal note pin per CRM record",
"artifacts": {
"contract": "actor A replacing a pin does not change actor B",
"changeMap": "control -> request -> policy -> store -> response",
"evidence": "replacement, rejection, isolation, repeated request",
"data": "one association per workspace, actor, and record",
"handoff": "observed checks, missing checks, disable behavior"
}
}- Read the behaviour contract
- Inspect the connected change
- Assess acceptance and data evidence
- Review the handoff and remaining limits
Conceptual flow for the example above.
Tradeoff to keep in mind
These five artefacts guide attention; they are not proof of correctness or a requirement for five separate documents. A small feature can keep them together in one review description with links to the actual change and results.