smith-clarify git:20260413.7c3d3fcA

Immutable. This exact content is served forever at /api/v1/blob/fbdae6d36be29038.

---
name: smith-clarify
description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
handoffs:
  - label: Build Technical Plan
    agent: smith-plan
    prompt: Create a plan for the spec. I am building with...
---

## 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.

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

```text
$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. For each unanswered question, present it one at a time:**

   Display in this format:
   ```
   ## Question [N] of [Total]: [Topic]

   **Context:** [Quote from plan/spec that raises this question]

   **Question:** [The specific implementation decision]

   **Options:**
   | Option | Description | Implications |
   |--------|-------------|--------------|
   | A | [description] | [pros: ..., cons: ...] |
   | B | [description] | [pros: ..., cons: ...] |
   | C | [description] | [pros: ..., cons: ...] |

   **Recommended:** [Option letter] — [Clear reasoning for why this is the best choice]

   Reply with an option letter (e.g., "A"), say "yes" to accept the recommendation,
   type "skip" to defer this question, or provide your own custom answer.
   ```

   **C. Process the user's response:**
   - `"yes"`, `"recommended"`, or `"rec"` → use the recommended answer
   - An option letter (`"A"`, `"B"`, `"C"`) → use that option's description as the answer
   - `"skip"` → mark as `**Answer:** SKIPPED — needs follow-up`
   - Anything else → accept as a 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

      | # | Topic | Answer |
      |---|-------|--------|
      | Q1 | [topic] | [answer] |
      | Q2 | [topic] | [answer] |
      | Q3 | [topic] | SKIPPED |
      ...
      ```
   3. Ask: "Would you like to change any answers before proceeding? Reply with a question number to revise, or 'looks good' to continue."
   4. If the user wants to change an answer, re-present that question and collect a new answer. Update questions.md.
   5. 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
   6. 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).**

   ---

2. 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)

3. 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.

4. Sequential questioning loop (interactive):
    - 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:

       | Option | Description |
       |--------|-------------|
       | A | <Option A description> |
       | B | <Option B description> |
       | C | <Option C description> (add D/E as needed up to 5) |
       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |

       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
    - For short‑answer style (no meaningful discrete options):
       - Provide your **suggested answer** based on best practices and context.
       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
    - After the user answers:
       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
    - Stop asking further questions when:
       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
       - User signals completion ("done", "good", "no more"), OR
       - You reach 5 asked questions.
    - Never reveal future queued questions in advance.
    - If no valid questions exist at start, immediately report no critical ambiguities.

5. Integration after EACH accepted answer (incremental update approach):
    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
    - For the first integrated answer in this session:
       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
    - Then immediately apply the clarification to the most appropriate section(s):
       - Functional ambiguity → Update or add a bullet in Functional Requirements.
       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
    - Keep each inserted clarification minimal and testable (avoid narrative drift).

6. Validation (performed after EACH write plus final pass):
   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
   - Total asked (accepted) questions ≤ 5.
   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
   - Terminology consistency: same canonical term used across all updated sections.

7. Write the updated spec back to `FEATURE_SPEC`.

8. Report completion (after questioning loop ends or early termination):
   - Number of questions asked & answered.
   - Path to updated spec.
   - Sections touched (list names).
   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
   - If any Outstanding or Deferred remain, recommend whether to proceed to `/smith-plan` or run `/smith-clarify` again later post-plan.
   - Suggested next command.

Behavior rules:

- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
- If spec file missing, instruct user to run `/smith-specify` first (do not create a new spec here).
- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
- Avoid speculative tech stack questions unless the absence blocks functional clarity.
- Respect user early termination signals ("stop", "done", "proceed").
- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.

Context for prioritization: $ARGUMENTS