Skip to content
Agentic Coding Toolkit

Refine Spec

Roast your spec before implementation. This skill 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 browses ai_specs/ and lets you pick a spec

What it checks

Section titled “What it checks”

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

1. Completeness

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

2. Assumptions

Section titled “2. Assumptions”
  • Does the spec assume packages, patterns, or APIs that do not exist in your project?
  • Does it reference files or structures that do not 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?
  • Are there dead ends where users get stuck?
  • Can users go back, cancel, or recover?

4. Data model fit

Section titled “4. Data model fit”
  • Do models have all fields needed for every flow?
  • Are there fields in the UX that do not 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 resulting implementation feel out of place next to existing features?

Output

Section titled “Output”

Findings are 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, evidence, and a suggested fix.

After the review

Section titled “After the review”

ACT usually 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 whether the spec covers enough edge cases

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

Section titled “Related”