Clarifying Intent
Close the gap between what was asked and what is actually wanted, before you
build on it. When a skill already selected owns asking for the inputs still
open, leave that to it.
When to use
- A request is vague ("add auth", "make it faster") or has more than one reasonable reading.
- Assumptions are piling up before a plan or feature.
- A named decision still pending received information but no answer that
settles it.
- Skip when the current phase skill owns the uncertainty: new-initiative
outcomes and measures belong to
define-goals; open interface flow, state,
hierarchy, accessibility, and visual direction belong to ui-ux-design.
A missing product requirement that blocks either procedure is still a genuine
clarification or specification gap.
- Skip when the task is trivial or already fully specified.
- Skip when the task is clear and what blocks it is an obstacle, not a
decision: a failing command, an error, a missing piece you can find or
build. Fix it and continue to completion.
- Skipping never permits a silent decision. State an assumption that
falls in none of the categories that follow, with its reason, so the user can
redirect. Product, scope, architecture, execution-mode, destructive, or
external-state choices stay pending until the user decides them directly.
Step 1: Scan before you ask
- Read the request. Search the codebase and context for what is already
decided: conventions, similar features, libraries in use, naming.
- Never ask what the code already answers.
- If a caller invoked this one to settle a decision it named, keep that
decision and the step waiting on it. When a direct answer settles it
without changing the approved scope, record the answer and return to that
step; do not write another alignment brief or run another approval round.
If the answer brings new intent that changes that scope, continue below.
Step 2: Ask one question at a time
For each open decision, send one short message and end the turn:
Found: {{what the code or context already settles}}
Decision: {{the exact artifact or operation it controls}}
Recommendation: {{default}} — {{one line of reasoning}}
1. {{option}}
2. {{option}}
3. Something else
Wait for a direct answer before the next question. See What
closes a decision.
Use each answer to prune later questions. Ask only what could change the
outcome; a caller's decision, once settled, returns under Step 1.3.
Stop when another question would not change the outcome and every live
decision in a category named under When to use has a direct answer. A
general "go" answers no choice it does not name.
Step 3: Write the brief and present it
Fill assets/brief-template.md after Step 2.4's stop condition holds. Its
decision record (the ledger) stays outside the brief: add to it, never
rewrite it. A brief, not a spec.
Write it to .sdlc-skills/briefs/{{YYYY-MM-DD}}-{{topic}}.md or the
user-set path, preserving approved sections around it. Compute its
identity with using-sdlc-skills' artifact-layout.sh --hash FILE --brief
and record it in the ledger row. A tiny brief (a goal and one decision)
goes in the reply beside its decision record: path this reply, version
none.
Present and end the turn:
Brief {{path}} — version {{identity}}
Goal: {{one line}} Decisions: {{n}} Non-goals: {{n}} Open risks: {{n}}
1. Approve
2. Request changes
3. Reject
4. Cancel
Recommendation: {{option}} — {{one sentence}}.
Record its state (pending, changes requested, approved, rejected,
cancelled, or superseded) in that record outside the brief. Never edit the
proposed brief to show its state.
Only approval moves the work past the precondition this brief satisfies.
Return to the skill that invoked this one; do not assume planning follows.
What closes a decision
Information is not authorization. Praise, agreement with the reasoning, new
constraints, a partial answer, silence, or discussion of a neighboring choice
updates the context but leaves the question open. Incorporate it, say the
decision is still pending, and re-ask.
Only an explicit answer, a named option, or a standing default the user
granted for this kind of decision closes it. Approval covers only the version
shown and the next step named with it; a revision to any decision, non-goal,
or named next step reopens it. Changes requested, rejection, cancellation, or
abandonment closes that exact decision without approving anything.
Supersession requires an approved replacement.
The question offered three places to keep session data and recommended the
second. The reply: "Nice, the recommendation makes sense. Also, it has to work
offline." Nothing was chosen: that is agreement with the reasoning plus a new
constraint. Fold "works offline" into Found, say the decision is still
pending, and re-ask. "Sounds good" to a numbered question closes no more than
this did.
When an artifact carries the pending decision
Write supplied facts or constraints into it only when the
authority you hold now covers changing it. While its identity is not yet
issued, update the draft. Never edit an artifact once its identity is issued,
whether its decision is pending or closed: every change to what downstream
work relies on from it creates a new proposed successor that names its
predecessor, with a list per decision, non-goal, or stable ID of what was
added / changed / removed / preserved, and removing one needs its owner's
approval.
When a successor is approved, list everything bound to its predecessor and
mark each binding invalid until its owner validates it again. Record its
state (approved or accepted, rejected, cancelled, superseded) outside the
artifact, with evidence of the exact version each state applies to. Without
authority to change it, present the proposed update and keep both the
artifact and the decision pending.
The user's answer in this conversation is the authority for the current
transition. An Approval: field saved in a document is only a process record:
in a fresh context it cannot prove itself. Require the live answer, or a record
the project or harness issued that ties the answer to the user and to the
exact version; otherwise put the decision to the user again.
Gotchas
- An
Approval: line copied forward into a successor draft looks like proof
of approval, but it belongs to the predecessor's version; in a fresh context
it approves nothing about the successor.
1---2name: clarifying-intent3description: "Settles ambiguous user intent or an unanswered decision before work proceeds. Use when a request has several plausible readings that change the work, or when a pending decision receives praise, constraints, silence, or a partial reply instead of an explicit choice or cancellation, even if nobody asks for clarification. Skip inputs another skill's own procedure asks for."4metadata:5 source: https://skillmd.com/skills/augments-labs/clarifying-intent6---78# Clarifying Intent910Close the gap between what was asked and what is actually wanted, *before* you11build on it. When a skill already selected owns asking for the inputs still12open, leave that to it.1314## When to use1516- A request is vague ("add auth", "make it faster") or has more than one reasonable reading.17- Assumptions are piling up before a plan or feature.18- A named decision still pending received information but no answer that19 settles it.20- **Skip** when the current phase skill owns the uncertainty: new-initiative21 outcomes and measures belong to `define-goals`; open interface flow, state,22 hierarchy, accessibility, and visual direction belong to `ui-ux-design`.23 A missing product requirement that blocks either procedure is still a genuine24 clarification or specification gap.25- **Skip** when the task is trivial or already fully specified.26- **Skip** when the task is clear and what blocks it is an obstacle, not a27 decision: a failing command, an error, a missing piece you can find or28 build. Fix it and continue to completion.29- **Skipping never permits a silent decision.** State an assumption that30 falls in none of the categories that follow, with its reason, so the user can31 redirect. Product, scope, architecture, execution-mode, destructive, or32 external-state choices stay pending until the user decides them directly.3334## Step 1: Scan before you ask35361. Read the request. Search the codebase and context for what is already37 decided: conventions, similar features, libraries in use, naming.382. Never ask what the code already answers.393. If a caller invoked this one to settle a decision it named, keep that40 decision and the step waiting on it. When a direct answer settles it41 without changing the approved scope, record the answer and return to that42 step; do not write another alignment brief or run another approval round.43 If the answer brings new intent that changes that scope, continue below.4445## Step 2: Ask one question at a time46471. For each open decision, send one short message and end the turn:4849 ```text50 Found: {{what the code or context already settles}}51 Decision: {{the exact artifact or operation it controls}}52 Recommendation: {{default}} — {{one line of reasoning}}5354 1. {{option}}55 2. {{option}}56 3. Something else57 ```58592. Wait for a direct answer before the next question. See *What60 closes a decision*.613. Use each answer to prune later questions. Ask only what could change the62 outcome; a caller's decision, once settled, returns under Step 1.3.634. Stop when another question would not change the outcome and every live64 decision in a category named under *When to use* has a direct answer. A65 general "go" answers no choice it does not name.6667## Step 3: Write the brief and present it68691. Fill `assets/brief-template.md` after Step 2.4's stop condition holds. Its70 decision record (the ledger) stays outside the brief: add to it, never71 rewrite it. A brief, not a spec.722. Write it to `.sdlc-skills/briefs/{{YYYY-MM-DD}}-{{topic}}.md` or the73 user-set path, preserving approved sections around it. Compute its74 identity with `using-sdlc-skills`' `artifact-layout.sh --hash FILE --brief`75 and record it in the ledger row. A tiny brief (a goal and one decision)76 goes in the reply beside its decision record: path `this reply`, version77 `none`.783. Present and end the turn:7980 ```text81 Brief {{path}} — version {{identity}}82 Goal: {{one line}} Decisions: {{n}} Non-goals: {{n}} Open risks: {{n}}8384 1. Approve85 2. Request changes86 3. Reject87 4. Cancel8889 Recommendation: {{option}} — {{one sentence}}.90 ```91924. Record its state (pending, changes requested, approved, rejected,93 cancelled, or superseded) in that record outside the brief. Never edit the94 proposed brief to show its state.955. Only approval moves the work past the precondition this brief satisfies.96 Return to the skill that invoked this one; do not assume planning follows.9798## What closes a decision99100**Information is not authorization.** Praise, agreement with the reasoning, new101constraints, a partial answer, silence, or discussion of a neighboring choice102updates the context but leaves the question open. Incorporate it, say the103decision is still pending, and re-ask.104105Only an explicit answer, a named option, or a standing default the user106granted for this kind of decision closes it. Approval covers only the version107shown and the next step named with it; a revision to any decision, non-goal,108or named next step reopens it. Changes requested, rejection, cancellation, or109abandonment closes that exact decision without approving anything.110Supersession requires an approved replacement.111112The question offered three places to keep session data and recommended the113second. The reply: "Nice, the recommendation makes sense. Also, it has to work114offline." Nothing was chosen: that is agreement with the reasoning plus a new115constraint. Fold "works offline" into Found, say the decision is still116pending, and re-ask. "Sounds good" to a numbered question closes no more than117this did.118119## When an artifact carries the pending decision120121Write supplied facts or constraints into it only when the122authority you hold now covers changing it. While its identity is not yet123issued, update the draft. Never edit an artifact once its identity is issued,124whether its decision is pending or closed: every change to what downstream125work relies on from it creates a new proposed successor that names its126predecessor, with a list per decision, non-goal, or stable ID of what was127`added / changed / removed / preserved`, and removing one needs its owner's128approval.129130When a successor is approved, list everything bound to its predecessor and131mark each binding invalid until its owner validates it again. Record its132state (approved or accepted, rejected, cancelled, superseded) outside the133artifact, with evidence of the exact version each state applies to. Without134authority to change it, present the proposed update and keep both the135artifact and the decision pending.136137The user's answer in this conversation is the authority for the current138transition. An `Approval:` field saved in a document is only a process record:139in a fresh context it cannot prove itself. Require the live answer, or a record140the project or harness issued that ties the answer to the user and to the141exact version; otherwise put the decision to the user again.142143## Gotchas144145- An `Approval:` line copied forward into a successor draft looks like proof146 of approval, but it belongs to the predecessor's version; in a fresh context147 it approves nothing about the successor.