Skip to content
Agentic Coding Toolkit
This feature requires ACT Pro. Compare plans →

Refine Spec

Roast your spec before implementation. This command acts as an adversarial reviewer that catches problems before you start coding.

Usage

Section titled “Usage”
Terminal window
/act:workflow:refine-spec [spec-file]

Arguments:

  • Spec file path: ai_specs/auth-spec.md
  • No argument: ACT will browse ai_specs/ and let you pick a spec

What it checks

Section titled “What it checks”

The refine-spec command evaluates your spec across five dimensions:

1. Completeness

Section titled “1. Completeness”
  • Are there implied but unstated requirements?
  • Are success/failure criteria defined for every action?
  • Are there missing states (loading, empty, error, partial)?
  • Are permissions and access control addressed?

2. Assumptions

Section titled “2. Assumptions”
  • Does the spec assume packages, patterns, or APIs that don’t exist in your project?
  • Does it reference files or structures that don’t match reality?
  • Are there unverified assumptions about data availability or format?

3. UX coherence

Section titled “3. UX coherence”
  • Is the happy path intuitive?
  • Are error messages actionable? Can users recover?
  • Are there dead ends where users get stuck?
  • Is navigation logical — can users go back, cancel, or escape at every point?

4. Data model

Section titled “4. Data model”
  • Do models have all fields needed for every flow?
  • Are there fields in the UX that don’t appear in the data model (or vice versa)?
  • Does the persistence strategy make sense?

5. Codebase alignment

Section titled “5. Codebase alignment”
  • Does the spec follow your project’s actual directory structure?
  • Does it use your state management pattern correctly?
  • Would the implementation feel out of place next to existing features?

Output

Section titled “Output”

Findings organized by severity:

  • Critical — blocks implementation, must be resolved first
  • Important — would cause rework during implementation
  • Minor — worth improving for clarity

Each finding includes the problem (with evidence) and a suggested fix.

After the review

Section titled “After the review”

ACT offers these next steps:

  • Update spec — apply fixes for Critical and Important findings
  • Discuss findings — talk through specific findings before changing anything
  • Looks good — proceed to planning as-is
  • Re-run spec — the spec needs a full rewrite

When to use it

Section titled “When to use it”
  • After creating a spec for a complex feature
  • Before committing to an implementation plan
  • When you’re unsure if the spec covers enough edge cases

You can skip refine-spec for simple features where the requirements are obvious.

Section titled “Related commands”