attckdigital/smith/smith-clarify

Workflow requirement (Smith 20+): This skill must be invoked from inside an active top-level workflow (/smith-new, /smith-bugfix, /smith-debug, /smith-build). The workflow-gate hook will block standalone invocation. To use this skill standalone, start a top-level workflow first.

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-clarify <event>
 
**User Request:**
> <verbatim user message that triggered this action>
 
**Synthesized Input:** <brief summary>
**Outcome:** <what happened>
**Artifacts:** <files modified>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — which spec is being clarified (feature name and path)
2. After questions asked — number of questions, brief topic summary for each
3. After answers received — decision summary for each answered question (topic + chosen option)
4. After spec updates — which sections of the spec were updated based on answers

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking /smith-plan. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

1. Run .specify/scripts/bash/check-prerequisites.sh --json --paths-only from repo root once (combined --json --paths-only mode / -Json -PathsOnly). Parse minimal JSON payload fields:

• FEATURE_DIR
• FEATURE_SPEC
• (Optionally capture IMPL_PLAN, TASKS for future chained flows.)
• If JSON parsing fails, abort and instruct user to re-run /smith-specify or verify feature branch environment.
• For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

Questions file location: Store the questions file inside the feature spec folder at FEATURE_DIR/questions.md (NOT in a separate specs/questions/ directory). The questions are part of the feature's decision record and should travel with the feature spec. If FEATURE_DIR points to a .specify/systems/<system>/features/<feature>/ path, use that directly. If clarify is run multiple times, append new questions to the existing file with a ### Session YYYY-MM-DD timestamp header rather than overwriting.

1.5. Check for existing unanswered questions. After resolving FEATURE_DIR, check if FEATURE_DIR/questions.md exists. If it does, scan for unanswered questions — lines matching **Answer**: ___ or **Answer:** followed by only whitespace/underscore.

If unanswered questions exist: Skip the spec ambiguity scan (steps 2-3) and enter the Interactive Answer Collection flow below. This handles the case where /smith-new generated a questions.md during the planning phase and the user wants to answer them conversationally.

If no questions.md exists, or all questions are already answered: Proceed with the normal spec ambiguity scan (steps 2-4).

### Interactive Answer Collection (for existing questions.md)

When a questions.md file exists with unanswered questions, walk through each one interactively:

A. Parse questions.md — extract all question blocks. Each block has: question number, topic, context, question text, options table, recommended answer, and current answer status.

B. Invoke `smith-question` and present each unanswered question one at a time.

Invoke the smith-question skill — it is the canonical contract for the presentation format (Context → Options with pros/cons → Recommended + reasoning) and the one-at-a-time / wait-for-reply pacing. Follow that contract; do NOT restate the format here, and do NOT use the interactive AskUserQuestion popup.

C. Process the user's response per smith-question's response grammar (yes/recommended/rec → recommended answer; an option letter → that option's description; skip → **Answer:** SKIPPED — needs follow-up; anything else → custom answer verbatim).

D. After each answer, immediately:

1. Update questions.md — replace the **Answer**: ___ line for that question with **Answer:** [chosen answer]
2. Confirm to the user: Saved: Q[N] → [brief answer summary]. ([remaining] questions remaining)
3. Present the next unanswered question

E. If the session is interrupted before all questions are answered, the questions.md file reflects the current state — answered questions have their answers filled in, unanswered questions still show **Answer**: ___. The user can resume later by running /smith-clarify again (it will pick up where they left off).

F. After all questions are answered (or the user says "done"):

1. Update questions.md header — change **Status**: AWAITING ANSWERS to **Status**: ANSWERED (or PARTIALLY ANSWERED if any were skipped)
2. Display a summary of all answers:

``` ## Answers Summary

... ```

1. Ask: "Would you like to change any answers before proceeding? Reply with a question number to revise, or 'looks good' to continue."
2. If the user wants to change an answer, re-present that question and collect a new answer. Update questions.md.
3. Once confirmed, update spec.md with the decisions from the answered questions:

• For each non-skipped answer, identify the relevant section of spec.md and incorporate the decision
• Add or update a ## Implementation Decisions section in the spec if answers affect implementation approach
• Save spec.md

1. Suggest next step: "Questions answered and spec updated. Next: /smith-plan to generate the implementation plan."

Log all answers to the vault session log per the Vault Logging section above.

After completing the Interactive Answer Collection, skip to step 8 (Report completion).

1. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).

Functional Scope & Behavior:

• Core user goals & success criteria
• Explicit out-of-scope declarations
• User roles / personas differentiation

Domain & Data Model:

• Entities, attributes, relationships
• Identity & uniqueness rules
• Lifecycle/state transitions
• Data volume / scale assumptions

Interaction & UX Flow:

• Critical user journeys / sequences
• Error/empty/loading states
• Accessibility or localization notes

Non-Functional Quality Attributes:

• Performance (latency, throughput targets)
• Scalability (horizontal/vertical, limits)
• Reliability & availability (uptime, recovery expectations)
• Observability (logging, metrics, tracing signals)
• Security & privacy (authN/Z, data protection, threat assumptions)
• Compliance / regulatory constraints (if any)

Integration & External Dependencies:

• External services/APIs and failure modes
• Data import/export formats
• Protocol/versioning assumptions

Edge Cases & Failure Handling:

• Negative scenarios
• Rate limiting / throttling
• Conflict resolution (e.g., concurrent edits)

Constraints & Tradeoffs:

• Technical constraints (language, storage, hosting)
• Explicit tradeoffs or rejected alternatives

Terminology & Consistency:

• Canonical glossary terms
• Avoided synonyms / deprecated terms

Completion Signals:

• Acceptance criteria testability
• Measurable Definition of Done style indicators

Misc / Placeholders:

• TODO markers / unresolved decisions
• Ambiguous adjectives ("robust", "intuitive") lacking quantification

For each category with Partial or Missing status, add a candidate question opportunity unless:

• Clarification would not materially change implementation or validation strategy
• Information is better deferred to planning phase (note internally)

1. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:

• Maximum of 10 total questions across the whole session.
• Each question must be answerable with EITHER:
• A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
• A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
• Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
• Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
• Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
• Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
• If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

1. Sequential questioning loop (interactive):

• Invoke the smith-question skill for the canonical presentation contract

and response grammar; the multiple-choice format below follows it. Never use the interactive AskUserQuestion popup — questions are presented as markdown. (The short-answer style and the ≤5-word constraint below are clarify-specific additions on top of that contract; spec-ambiguity answers integrate into spec.md rather than a questions.md.)

• Present EXACTLY ONE question at a time.
• For multiple‑choice questions:
• Analyze all options and determine the most suitable option based on:
• Best practices for the project type
• Common patterns in similar implementations
• Risk reduction (security, performance, maintainability)
• Alignment with any explicit project goals or constraints visible in the spec
• Present your recommended option prominently at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
• Format as: **Recommended:** Option [X] - <reasoning>
• Then render all options as a Markdown table: