Brief

The brief is the first step of the Flow workflow. In this guide, you will learn:

• What the brief skill does and why the brief avoids technology
• How the interview works
• What the brief produces

Overview

The brief skill interviews you about a feature the way a product manager would, and writes down what the feature does from the user's point of view. The result is a product brief, free of databases, routes, and frameworks.

You start a new change by invoking the skill with a short name for it:

/flow-brief project-archiving

That name becomes the change's folder under .flow/changes/, where every later step writes its output.

One feature, one journey

A brief covers exactly one journey: one entry point, one goal, one continuous experience for the user. If you describe something that spans several journeys, the skill stops and proposes splitting it into separate changes, each planned on its own. A brief that blurs several journeys together blurs the decisions too, so it is better to split early.

The interview

The skill walks the user's journey from the entry point to completion, one step at a time. At each step it resolves what the user sees, what they can do, what state they are in, and what happens on both success and failure. It asks one question at a time and waits for your answer, because a batched list of questions tends to collect shallow, batched answers.

When a decision comes up, the skill names the alternatives, recommends one, and records why, including the option you rejected. That recorded reasoning is the part of the brief most likely to matter later, because it explains a choice that the code alone cannot.

The skill reads your codebase whenever a question can be answered there instead of asked. Reading existing code is fine. What the skill will not do is record implementation detail in the brief itself.

Why the brief avoids technology

The brief names what the user sees, such as a form, a field, or a confirmation message, and what the user decides, such as a validation rule or the wording of an error. It does not prescribe how any of that is delivered.

Models, schemas, routes, and frameworks are out of scope, and so are user-experience delivery mechanics: whether an error appears inline or as a toast, whether input is preserved on a failed submit. Those are real decisions, but they belong to the blueprint. Keeping them out of the brief means the brief survives a future re-platform, and the blueprint inherits a clean problem to solve rather than a half-made one.

If you volunteer a technical detail during the interview, the skill acknowledges it, sets it aside for the blueprint, and steers back to the journey.

What the brief produces

The skill writes two kinds of file into the change's folder.

• brief.md is the product brief: the journey step by step, the decisions made with their rejected alternatives, and the constraints the journey places on the implementation.
• delta/<capability>.md is a behavior delta, one per capability the change affects. A capability is a named area of behavior, such as "projects" or "billing"; the skill asks which capabilities this change touches. A delta records the change as a difference against what the capability already does: which behaviors are added, which are modified, and which are removed.

The brief feeds the blueprint. The deltas are set aside until sync, which uses them to update Flow's canonical state once the change is built.

Next step

• Hand off to the Blueprint skill to turn the brief into a technical plan.