Documentation
The Specification Workflow
Smart Scoping

Smart Scoping

Before generating a full specification, SpecWright analyzes your request to determine the right level of effort. Not every piece of work needs a spec — sometimes you should just start coding.

How scoping works

When you create a new project (via specwright new or the Web UI), you describe what you want to build in plain language. SpecWright's AI classifier reads your description and places it into one of three categories:

Work Directly

The request is small enough to implement without a specification. Bug fixes, config changes, single-component tweaks, copy updates.

Examples:

  • "Fix the login button color to match the design system"
  • "Add a loading spinner to the search results page"
  • "Update the footer copyright year"

What happens: SpecWright tells you to skip the spec and just start coding. If you're using a headless AI tool, it can generate a prompt to implement the change directly.

Project

The request needs a full specification. It involves multiple screens, an API, data storage, or touches enough of the system that you'd regret winging it.

Examples:

  • "Add Google Sign-in with session management"
  • "Build a task management board with drag-and-drop"
  • "Create an admin dashboard for managing users"

What happens: SpecWright creates a project folder and starts the specification workflow — PM → Designer → Engineer → Issue Breakdown.

Multi-Project

The request is large enough to split into multiple independent projects, each getting its own full spec.

Examples:

  • "Build an e-commerce platform with product catalog, shopping cart, checkout, and order management"
  • "Create a SaaS application with authentication, billing, team management, and a dashboard"

What happens: SpecWright splits the work into separate projects (e.g., "Product Catalog", "Shopping Cart", "Checkout"), each running its own specification workflow independently.

Creation modes

The Web UI offers two ways to create a project:

AI-assisted mode (default) — Describe what you want to build, and the AI classifier determines the scope. If it's a project, SpecWright generates the project request automatically and starts the specification workflow.

Manual mode — Enter a project name and description directly. Skips the scoping classification and creates a project immediately. Useful when you already know the scope.

Project settings at scoping time

When a request is classified as a project, you configure two settings that affect the entire specification workflow:

  • Question depth — How many questions each agent asks: light (2-3), standard (3-4), or thorough (4-6). See Settings Reference.
  • Document length — Target word count for generated documents: brief (600-900), standard (1,500-2,100), or comprehensive (3,600-4,500).

These can also be set from the CLI via specwright finalize-scope.

What's next?

Once scoping is complete:

  • Work Directly → Start coding in your preferred tool
  • Project or Multi-Project → Continue to the Product Manager Phase
OverviewProduct Manager Phase