How to turn a customer conversation into an engineering brief

Capture the observation before proposing a solution

A conversation often mixes a current problem, a feature suggestion, a promise, and an unrelated follow-up. Treat those as different inputs. Preserve the exact source and surrounding context before deciding which one deserves engineering work.

For example, “I restarted the import and lost my workspace” is an observed problem. “Add an AI assistant” is a suggested solution. “Send the presentation tomorrow” is a general commitment. The brief should not turn all three into code tasks simply because they appeared in the same meeting.

Ask what is known and what still needs confirmation. Which step failed? Can the user recover? Does the failure affect one account or a repeatable path? Use a redacted example on a public page; keep private customer records in the authorized workspace.

Decide whether this is your team’s engineering work

A problem can be relevant without belonging in your engineering queue. A vendor outage may need an external follow-up. A presentation may need an owner and deadline. A product defect in your repository may need an engineering investigation.

Name the product, repository, responsible owner, and authority to make the change. If ownership is uncertain, keep the task visible while resolving it. Avoid letting a fluent AI plan substitute for evidence that the work belongs to your team.

Use this brief structure

The following structure works for a human engineer or an AI coding agent. Each field answers a different review question. Keep it short enough to inspect, with links to the detailed evidence instead of copying an entire transcript.

1. Problem: describe the observed user failure and why it matters.
2. Evidence: link the conversation, reproduction, relevant product behavior, and open questions.
3. Outcome: state the behavior a user should experience after the change.
4. Ownership: identify the product, repository, and approval owner.
5. Scope: list the behavior to change and the boundaries that must remain intact.
6. Acceptance: define observable checks for success, invalid input, and repeated actions.
7. Delivery: require a reviewable diff, verification results, and unresolved limitations.
8. Approval: state who may start work, merge it, and release it.

Worked example: recover an interrupted import

This is an illustrative example, not a report about a real customer. The source request is: “Retry the import. Keep the original workspace.” Repository context shows an existing workspace identity and a saved import checkpoint.

The intended outcome is specific: retry resumes from the valid checkpoint in the same workspace. Existing rows remain intact. Repeating the retry does not create duplicate rows. An invalid checkpoint produces a clear recovery state instead of guessing a new workspace.

The first investigation should find the boundary that owns workspace identity and import recovery, and check analogous retry paths. The brief names the invariant—preserve identity and committed rows across retry—before naming a local patch. That prevents a fix in one button from contradicting the same rule elsewhere.

Completion evidence should include a diff and checks that exercise preserved rows, repeated retry, and invalid checkpoints. Passing those checks proves the tested behavior. It does not by itself prove the change was deployed or that customer time was saved.

Keep approval attached to the actual action

Approve the product decision, engineering scope, and release as distinct actions when your workflow requires distinct authority. Reading a brief or opening a notification should not silently approve code. A draft pull request gives the reviewer a concrete artifact to assess.

Actionairy connects the conversation and product evidence to decisions and work. Spec structures governed intent, and Compress carries approved engineering work into a reviewable run. The purpose is to retain the source, judgment, and verification as the work moves between systems.

After release, return to the original problem. Confirm the live behavior separately from local tests. Measure the relevant outcome if instrumentation exists, and record when it does not. That closes the loop without turning a completed task into an unsupported success claim.