Writing Good Specs

The spec is the single highest-leverage artifact in the ACT workflow. A clear spec produces a focused plan and correct implementation. A vague spec produces guesswork.

What makes a spec good

Good specs share four qualities:

Specific --- requirements describe observable behavior, not intent. “Show a loading spinner while fetching” rather than “handle loading.”
Testable --- every requirement can be verified with a concrete check. If you cannot describe how to test it, the requirement is too vague.
Bounded --- the spec states what is out of scope just as clearly as what is in scope.
Independent --- the spec can be implemented without depending on other unfinished work.

The spec structure

ACT generates specs with these sections (see Spec command for details):

Section	Purpose
Goal	What to build and why it matters
Background	Tech stack, constraints, project context
User flows	Happy path, alternative flows, error/recovery flows
Requirements	Numbered, testable requirements grouped by category
Boundaries	What is explicitly out of scope
Implementation notes	Patterns to follow, files to modify, things to avoid
Validation	How to verify the feature works correctly
Done when	Measurable completion criteria

You do not need to write all of this yourself. Give ACT a clear task description, answer the clarifying questions well, and it generates the structure. Your job is to review and refine the output.

Common mistakes

Too vague

“Add authentication” --- which provider? What happens on failure? What screens need auth guards?
“Improve performance” --- which screen? What metric? What is the target?

Fix: Describe the specific user-facing behavior you want to see.

Too broad

“Build the entire settings screen with all options” --- this bundles unrelated features (theme, notifications, account, privacy) into one spec.

Fix: Split into one spec per concern. See Breaking Down Large Tasks.

Missing edge cases

Specs that only describe the happy path. What happens when the network is down? When the user has no data? When the input is invalid?

Fix: After writing the spec, ask yourself “what could go wrong?” for each user flow. Or use /act:workflow:refine-spec to catch gaps automatically.

Mixing requirements with implementation

“Use a StatefulWidget with a TextEditingController and call setState on every keystroke” --- this over-constrains the implementation and may conflict with your project’s patterns.

Fix: Describe the behavior (“real-time search filtering as the user types”), not the mechanism. Let the plan stage decide the implementation approach.

Good vs bad requirements

Bad	Good
”Handle errors"	"Show a retry button with the error message when the API returns a non-200 status"
"Make it fast"	"The list renders within 300ms for up to 500 items"
"Support offline"	"Previously loaded data is available when the device has no network connection; a banner indicates offline status"
"Add validation"	"Email field rejects input without @ and a domain; password requires 8+ characters with one number”

Tips for better task descriptions

When you run /act:workflow:spec, the quality of your initial description matters:

State the user goal, not the technical task. “Users can bookmark articles for later reading” beats “add a bookmarks table and API endpoint.”
Mention constraints early. If you use Riverpod, need offline support, or have a specific API --- say so upfront.
Reference existing features. “Similar to how favorites work in the current app” gives ACT a concrete pattern to follow.
Answer clarifying questions thoroughly. These questions exist because the AI detected genuine ambiguity. Brief answers lead to assumptions.

After writing the spec

Review the spec yourself, then optionally run /act:workflow:refine-spec for adversarial review. Once you are satisfied, proceed to /act:workflow:plan.

Spec command --- how to generate specs
Refine Spec command --- adversarial spec review
Breaking Down Large Tasks --- when one spec is not enough
Choosing the Right Model --- which model to use for spec generation