SuperAPI AI Directory

clarify

General & other

View repository

Updated 10-16 09:58

About this skill

clarify: requirements grilling

Positioning

Converge vague intent into executable determinism. Produce two things: a written draft spec (.issues/ inside the task directory), and an optional publishing artifact (Issue / PR description). Writing to disk is not a ritual—it is the prerequisite for multi-model, multi-harness cross-review, and also the working memory for resuming from a breakpoint.

This skill is only invoked explicitly by the user. When similar skills are installed in the environment (grill-me, brainstorming, etc.), they do not take over from each other; each is independent.

Process

Phase 0 Get in position

Detect git. If git exists and .issues/ is not ignored, write .issues/ into .git/info/exclude(without modifying the shared .gitignore) and tell the user in one sentence. If there is no git, skip the ignore step. Create the task directory .issues/<YYYY-MM-DD-主题>/, and the draft file is the spec.md。

Phase 1 Fact self-check

Do not ask the user about facts that can be looked up in the environment: first search the codebase, documentation, and configuration to clarify the "what is", and leave only the "what is wanted" decisions to the user. If unknowns found in the self-check affect subsequent decisions, turn them into grilling questions or write them into the "Open Questions" section of the spec; do not silently assume them as established facts.

Phase 2 Triage

Determine the depth based on the facts found in the self-check—do not draw a triage conclusion before the self-check is complete. Judge by two criteria, and declare to the user which tier is being used:

  • stakes: Is the cost of getting it wrong a recoverable small cost, or a hard-to-reverse large price? High-stakes anchors: external release, irreversible data changes, involvement of payment/privacy/security. Low-stakes anchors: local tools, small features that can be rolled back at any time.
  • Uncertainty: Is the existing information enough to draw a conclusion directly?

Low stakes and low uncertainty → Lightweight mode(at most 5 questions, stop once converged, do not add questions just to make up the number). Otherwise → Full mode(use the full question table as needed, high-stakes rows must be asked). When unsure which tier to use, count it as full mode; do not downgrade just to please a user who is in a hurry.

Phase 3 Grilling

Hard rules:

  • Ask only one question at a time. Sending multiple questions packed together leaves people with no way to start answering, and also forces out "you decide".
  • Every question must include a recommended answer. The user is approving or rejecting, not answering from scratch.
  • Each time a decision is confirmed, immediately append it to spec.md。 "It is all in the conversation" does not count as written to disk.
  • When the user says "you decide" = delegating the decision, not exempting the record. Adopt the recommended answer and continue, and still record the decision item by item. Moreover, the failure-judgment question (the reverse row of the question table) cannot be skipped—it defines "done", and without it acceptance is impossible; delegating it is equivalent to giving up acceptance. You may let the user answer only yes/no to the recommended failure judgment.

Questions take prototypes from the question table, use them according to the actual state of the conversation, and do not check them off row by row:

Lens Question prototype Timing
First principles "You say you want X—remove the word X, what are you really trying to change?" Must ask at the start
First Principles "Which of these constraints are facts, and which are merely conventions?" When the approach forks
Inversion "Under what circumstances does this feature count as a failure? What kind of implementation would be sent back?" Write the answer directly as acceptance criteria Must ask once the approach takes shape
Inversion "After launch, what is the most likely way it will be misused/abused?" Must ask when stakes are high
Systems Thinking "Which existing loop will change after integration? Who depends on the part being modified?" When an existing system is involved
Systems Thinking "After solving A, will that create B?" Full mode
Bias Firewall "Are we solving a problem, or rationalizing a decision already made?" When the user or you show attachment to a particular approach

Two lower bounds and one exception:

  • Lower bound: Regardless of tier, the opening reframe and the inversion failure-criteria questions are indispensable. Asking only implementation details like "what is the parameter called" does not constitute interrogation, and padding the count is invalid.
  • Acceptance criteria must cover at least two dimensions: new behavior is correct, and old behavior does not regress. For high stakes, add the abuse dimension.
  • Exception (bundled confirmation): After the user delegates the decision twice in a row ("you decide"), stop asking question by question—summarize the remaining undecided items into a single confirmation message according to the recommended approach; approval means convergence. This is confirmation, not a question, and does not violate the one-question rule. When the question count is exhausted but undecided branches remain, likewise use bundled confirmation.Only decision items go into the bundle(those involving behavior, scope, trade-offs); implementation details (thresholds, naming, etc.) do not enter the bundle—execute them per the recommendation and note them in spec.md ; do not dilute the user's attention on decision items with details.

Stop conditions (any one triggers Phase 4): the decision tree has no undecided branches. The user calls stop. Bundled confirmation is approved. Convergence takes priority over budget—if it converges in 3 questions, stop at 3.

Phase 4 Finalize and Publish

After the draft converges, read references/publish.md and execute: detect the exit (gh → glab → git only → no git), ask for the destination, rewrite from the conversation understanding using the whitelist template, and publish only after the full text has been reviewed and confirmed by the user. In no-git scenarios (such as non-development decisions): the draft is the final state; optionally distill the spec into a piece of text that can be sent directly to the user.

Phase 5 Wrap-up

A one-line consolidation prompt: if this round changed "the facts of the current code," prompt the user to update the corresponding sections of AGENTS.md / docs. Optionally suggest next steps (write the failing test first, ask another model to cross-review this spec); not mandatory, no hard jump.

Red Lines

  • Do not write implementation code before the interrogation has converged. When the user urges progress, first give "the decisions confirmed so far + the minimum remaining questions" and then let the user choose to continue the interrogation or start work on the confirmed parts.
  • spec.md If it is not written to disk, it does not count as converged.
  • The published text never copies the draft verbatim; it is only rewritten according to the template of references/publish.md .