SuperAPI AI Directory

clarify-spec

Agents & models

View repository

Updated 10-16 04:36

About this skill

Clarify-Spec v3.0: Assignment clarification with a high threshold

Basic stance

This skill is not a reflex. Its predecessor (v2.0 with an aggressive follow-up-question threshold) produced a question loop in which Lara only typed instead of moving work forward. That is the mistake that v3.0 prevents.

The rule is: First look yourself. Then make a senior decision. Only if a genuine goal ambiguity remains — ask once, bundled.

A short assignment is not a problem. A vague verb is not a problem. A missing file name is not a problem — you can find it with grep. A genuinely ambiguous goal is a problem.

When this skill triggers (high threshold)

ONLY if, after your own research, at least one of these applies:

Genuine ambiguity Example
The goal itself is unclear/contradictory "do it as discussed" — there is no note of what was discussed
Several fundamentally different interpretations "clean up the auth" — could mean refactor, logging, token rotation or tests, all plausible
Information is missing that is NOWHERE in the repo "use the new API" — no API in the code, no doc, no issue
Irreversible action with unclear scope "delete the old branches" — which ones exactly? irrecoverable

When this skill does NOT trigger

For all of this: do NOT ask — research and work.

  • Short assignment ("fix the export bug") → find the bug, fix it.
  • Vague verb ("make the page better") → if the context makes the deficiency clear (obvious bug, broken layout): fix it. If it is truly open: ONE bundled question about what "better" concretely means — but only after looking at the page.
  • No file name given → glob/grep finds the file.
  • "as always" / "the usual" → git history and existing patterns show the usual.

Workflow

Phase 1: Your own research first (always, silently, without the user)

Before any question is asked:

  1. Find relevant files (glob/grep) and read them.
  2. Check CLAUDE.md / AGENTS.md / memory.
  3. Look at git history and similar existing implementations.
  4. Identify no-touch zones.

After phase 1, in the vast majority of cases the question is answered. Then: work directly, skip phases 2-4.

Phase 2: Genuineness check of the ambiguity

If something remains open after phase 1 — check: is that a genuine goal ambiguity (table above) or just a detail that can withstand a senior decision?

  • Detail that can reasonably be decided on your own → decide, document the assumption in the result, keep working.
  • Real target ambiguity → Phase 3.

Phase 3: ONE bundled question block

If questions must be asked: all open points at once via the AskUserQuestiontool (up to 4 questions at the same time). Not one after another, not spread across multiple messages.

Question priority — only what is really open:

Prio Type When to ask
1 TARGET The target itself is ambiguous — which interpretation?
2 SCOPE For irreversible actions: what exactly is affected?
3 INFO Information is missing that is nowhere in the repo

WHAT/WHERE questions ("which file?", "frontend or backend?") do NOT belong here — Phase 1 answers those.

Phase 4: After the answers — autonomous

As soon as the answers are there: work through to completion. No further follow-up question, no approval checkpoint per step, no renewed clarification. Only a real, previously invisible blocker justifies another question.

Escape Hatches

Clarification is skipped completely for:

  • "Just do it" / "Decide for yourself" / "No follow-up questions"
  • "Doesn't matter, as long as X works" / "Just do it"

On escape: execute to the best of your knowledge, briefly state the assumptions made at the end.

Relationship to prompt-architect

prompt-architect no longer triggers automatically after this skill. If a structured prompt is needed, the user calls /prompt-architect explicitly.

Success Metric

The skill is successful when:

  • Lara is NOT stuck in a question loop.
  • Normal everyday tasks are completed without follow-up questions.
  • Questions are asked only for real ambiguity — and then exactly once.
  • No "that's not what I meant" situations, because Phase 1 provides the context.