Skip to content
Agentic Coding Toolkit

Refine Spec

Use act-refine-spec as an adversarial review before turning a Spec into Work Items.

A Spec is a requirements document that describes what should be built before code changes start.

When to use it

Section titled “When to use it”

Use this skill when the Spec is non-trivial, high-risk, ambiguous, or likely to affect multiple parts of the codebase. It looks for issues that would make downstream Work Items unsafe, ambiguous, or wasteful.

Use act-refine-spec-flutter when the project or task is Flutter/Dart. It adds checks for Flutter/Dart codebase facts, UI states, platform assumptions, testing seams, accessibility, and architecture fit.

Invoke it

Section titled “Invoke it”
Terminal window
/act-refine-spec <path/to/spec.md or GitHub issue>

Inputs

Section titled “Inputs”
  • A Spec reference. If none is provided, the agent asks for it.
  • The Interview Ledger beside the Spec, when present.
  • Relevant project docs, GLOSSARY.md, code paths, tests, packages, commands, and conventions named or implied by the Spec.

What it checks

Section titled “What it checks”

The review is intentionally narrow. It checks the Spec’s claims and assumptions; it does not restart discovery or remap the whole repository.

Typical findings include:

  • contradictions inside the Spec
  • requirements that are vague, missing, untestable, or too broad
  • Interview Ledger decisions missing from the Spec
  • deferred questions treated as resolved
  • technical assumptions that do not match the codebase
  • missing testing seams or unclear automation/manual testing split
  • out-of-scope gaps that could expand the product surface
  • terminology drift from project docs or GLOSSARY.md

What the report looks like

Section titled “What the report looks like”

Findings come first, ordered by severity:

1. **High: Multi-argument behavior is not specified**
Spec: `ai_specs/0001-image-alt-generator-cli/spec.md:24-25, :67-68`
Evidence: The Spec says the CLI accepts “exactly” one positional `<image_path>` and must not expose extra options, but it does not say what happens when a user passes two or more positional arguments. Ledger L4 resolves the v1 surface to one required argument only.
Why it matters: Downstream implementation could silently ignore extra args, reject them, or accidentally preserve the shell script’s `[max_words]` `[max_tokens]` behavior. That weakens an exact CLI contract.
Recommended Spec change: Add an explicit requirement for `arguments.length > 1`, including exact stderr text, usage output if any, and non-zero exit behavior.

The agent also reports any strengths and residual risks.

Editing behavior

Section titled “Editing behavior”

By default, act-refine-spec reports findings only. It edits the Spec only when you explicitly approve changes.

After findings, the agent may ask what to do next:

1. **Update Spec**: Apply focused edits for the findings you approve.
2. **Discuss Findings**: Talk through findings or revise recommendations before editing.
3. **Leave Spec As-Is**: Keep recommendations unapplied.

If you choose Update Spec, the agent applies focused edits to the same Spec and summarizes what changed.

Next Steps

Section titled “Next Steps”

Start a /new session and continue to act-create-issues only when the Spec is accurate enough to create bounded Work Items.