git:20260515.7a2f96e to git:20260515.595977f

- description: Use when a DAE artifact (feature.md, acs.md, spec.md, plan.md, or CHARTER.md) has ambiguities that should be resolved before downstream work depends on it. Triggers include "/engineer.clarify", "clarify this spec", "resolve ambiguities in the ACs", "this plan is vague — tighten it", or naturally when a reader can't tell what an artifact means. Reads one artifact, identifies ambiguities, presents them one at a time as multiple-choice or open questions, and edits the artifact in place as each is resolved. Single-artifact only — flags downstream staleness but does not cascade (that is feature-edit's job).

- Resolve ambiguities in a single DAE artifact through an iterative interview. A cross-cutting quality gate — it can run on any artifact at any pipeline stage.

- The `clarify` *pattern* (read artifact → find ambiguities → ask → resolve) is also embedded directly inside artifact-producing skills (`discover-acs`, `plan`, etc.) for their own in-flight ambiguities. This standalone skill is for **ad-hoc cleanup** of an artifact after the fact.

- ## When this skill runs

- Any time, on any of: `feature.md`, `acs.md`, `spec.md`, `plan.md`, `CHARTER.md`. Not a checkpoint — `checkpoint: null` in the handoff.

- Invoked as `/engineer.clarify <slug> <artifact>` (e.g. `clarify customer-export acs`) or `/engineer.clarify <path>`.

- ### Step 1 — Resolve and load the target artifact

-

- Walk up to `.engineer/manifest.yml`; resolve `methodology_root`. Locate the target artifact from the slug + artifact-type argument, or from a direct path.

-

- Load the artifact. Also load its parent contract for grounding:

- - For `acs.md` / `spec.md` / `plan.md` → also load `feature.md` (the outcome the artifact serves)

- - For `feature.md` → also load `CHARTER.md`

- - For `CHARTER.md` → load it alone

-

- ### Step 2 — Identify ambiguities

-

- Read the artifact and flag, **within this one artifact**:

- - Language interpretable two different ways

- - Underspecified requirements — a behavior named but not pinned down

- - Undefined domain terms — a word used as if its meaning is settled when it isn't

- - Unclear scope boundaries — is X in or out?

- - Internal contradictions — two statements in the same artifact that disagree

-

- Out of scope for clarify: *cross-artifact* contradictions (acs.md disagrees with spec.md) — that's `consistency-check`. clarify works within one artifact.

-

- If no ambiguities are found, say so and stop — don't manufacture questions.

-

- ### Step 3 — Resolve ambiguities one at a time

-

- For each ambiguity, present it to the user as a single question:

- - **Multiple-choice** (AskUserQuestion) when the ambiguity has bounded resolutions — e.g. "Does 'recent' mean last 24h, last 7 days, or last 30 days?"

- - **Open-ended** when it doesn't — e.g. "What should happen when the export is empty?"

-

- One ambiguity per turn. Show where in the artifact it lives (quote the ambiguous line). Iterate until all are resolved or the user stops.

-

- ### Step 4 — Edit the artifact in place

-

- As each ambiguity is resolved, edit the **target artifact** to encode the resolution. Show the user the proposed edit (old → new) and confirm before writing.

-

- clarify edits **only the target artifact**. It does not touch any other file.

-

- ### Step 5 — Flag downstream staleness (do not cascade)

-

- A resolved ambiguity may invalidate downstream artifacts — e.g. tightening an AC in `acs.md` can make the corresponding `spec.md` scenario stale.

-

- clarify does **not** cascade. It detects and flags:

- - After editing, determine which downstream artifacts (if any) likely depend on what changed

- - List them in the handoff under "downstream staleness"

- - Recommend `/engineer.feature-edit`, which owns intent-driven multi-artifact propagation

-

- This keeps clarify simple and single-purpose; `feature-edit` owns the cascade.

-

- ### Step 6 — Emit the handoff summary

-

- ```markdown

- ---

- skill: clarify

- agent_id: <main | subagent-N | team-role>

- started: <ISO timestamp>

- ended: <ISO timestamp>

- checkpoint: null

- artifacts:

- - features/NNN-<slug>/<artifact> # the single artifact edited

- findings_summary: <one line — e.g. "6 ambiguities found, 6 resolved; spec.md may be stale">

- human_action_needed: <yes if downstream staleness flagged, else no>

- human_action_kind: <decision | none>

- recommended_next: <see below>

- tracker_update: none

- status: complete

- ---

-

- # clarify — handoff summary

-

- ## What I did

- Reviewed `<artifact>` for `<title>`. Found <N> ambiguities; resolved <M> with the user; edited the artifact in place to encode the resolutions.

-

- ## Artifacts produced

- - `features/NNN-<slug>/<artifact>` (edited — <M> resolutions applied)

-

- ## Findings

- <the ambiguities and how they resolved — one line each>

-

- ## Downstream staleness

- <list downstream artifacts that may now be inconsistent with the resolved artifact — or "None — no downstream artifacts depend on what changed">

-

- ## Human action needed?

- <If staleness flagged: "Yes — <downstream artifact(s)> may now be stale. Run /engineer.feature-edit to propagate the change.">

- <If none: "No — artifact clarified; no downstream impact.">

-

- ## Recommended next step

- <If staleness: "invoke /engineer.feature-edit to propagate to <downstream artifacts>">

- <If none: "resume the pipeline where you left off">

- ```

-

- ## When NOT to use this skill

-

- - Cross-artifact inconsistency (acs.md vs spec.md disagree) → that's `/engineer.consistency-check`

- - You want to change *what the feature does* (not resolve vagueness) → that's `/engineer.feature-edit`

- - The artifact needs a resolution that cascades into several files → clarify the source artifact here, then run `/engineer.feature-edit` for the cascade

-

- ## Cross-skill orchestration

- clarify is standalone and single-artifact. It reads one artifact (+ its parent contract for grounding), edits that one artifact, and flags — but does not perform — downstream propagation.

- - Upstream: any artifact-producing skill

- - This skill: resolves ambiguity within one artifact

- - Downstream: `feature-edit` (if cascade needed); `consistency-check` (for cross-artifact validation)

- Foundation contracts (Notion):

- - [DAE Foundation Design](https://www.notion.so/3585ecdee0e2811bbc67ff4913c03207) — artifact schemas, agentic summary contract

- - The DAE methodology page — the Speckit synthesis (clarify as embedded pattern + standalone skill)