specpro-cli 0.1.0__py3-none-any.whl

specpro_cli/assets/commands/specpro.clarify.md

@@ -0,0 +1,581 @@
+---
+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: specpro-plan
+    prompt: Create a plan for the spec. I am building with...
+writes:
+  # This command's write surface: only what it produces AS THE PRODUCER of that
+  # (artifact, unit) pair. A write this command makes on a non-producer path is a
+  # boundary violation by definition (FR-051) and MUST NOT be declared here.
+  # The full ownership map is the UNION of every command's writes: block.
+  - artifact: specs/clarifications.md
+    unit: "whole file in scan mode; per-item Status / Answer / Resolution fields in interactive mode"
+  - artifact: specs/spec.md
+    unit: "## Requirements -> the FR entries it updates or adds from answers; plus the User Story / acceptance-scenario / data-model text rewritten from those answers"
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+**Rerun safety — detect the artifact, default to incremental** ⚠️ [settled 2026-09-13]:
+
+**Before writing `specs/clarifications.md`, detect whether it already exists.** Use the SAME check in every command:
+
+```bash
+[ -s specs/clarifications.md ] && echo EXISTS || echo NEW    # -s: exists AND non-empty (an empty placeholder counts as NEW)
+```
+
+| Detection | Mode |
+|-----------|------|
+| **NEW** (absent or empty) | **Initial** — generate from scratch |
+| **EXISTS** | **Incremental** — evolve it; **never silently regenerate from scratch** |
+
+**Overwriting an existing artifact requires explicit, confirmed intent:**
+1. Only when the user *explicitly* asks (in their own words) does the initial path run on an existing artifact.
+2. **Even then, confirm once more before writing** — name the artifact that will be replaced and what will be lost; wait for the answer.
+3. **Silence is not consent.** An unspecified run on an existing artifact is ALWAYS incremental.
+
+> **Why a shared rule rather than per-command courtesy**: nine of the twelve non-implementation commands already had some protection, but each wrote it its own way (`EXISTING_SPEC` check · "creates a NEW file" · `NEVER overwrite` · "incremental regeneration" · `AUTO_MODE=false`), and **three had none at all** — not by decision, but because the discipline had no shared carrier. Overwriting an artifact the user has been evolving is not recoverable within the session; the cost of asking is one prompt.
+
+
+### Scope Resolution 🆕 (FR-063 / T050 · v0.23)
+
+1. **作用域判定**: 当前工作目录位于 `specs/fNNN-简称/` 内 ⇒ **feature 作用域**(读写范围 = 本 feature 目录,由 `check-prerequisites.sh` 的作用域感知解析);位于仓库根或 `specs/` 根 ⇒ **母作用域**(读写母规格链)。feature 作用域内 MUST NOT 写母产物——唯一例外:**发现登记**(台账路由,`[specify]`/`[plan]` 分区)。
+2. **新会话首次执行**: 若 `specs/features.md` 存在且含 `active` 行、而用户未指明作用域 ⇒ **询问用户**在母作用域还是某个 feature 内工作,MUST NOT 自行挑选。
+3. 本命令的产物路径随之解析:feature 作用域下落 `<feature 目录>/`,母作用域下落 `specs/`。
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification. This command has two modes:
+
+1. **--scan mode**: Scan spec.md for ambiguities, categorize questions, generate/update clarifications.md (no user interaction)
+2. **Interactive mode** (default): Load clarifications.md, ask questions one by one, integrate answers into spec.md
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/specpro-plan`. The Plan stage will auto-invoke this command if [Must Clarify] items remain unresolved.
+
+## Mode Detection ✨ ENHANCED with Smart Recommendations
+
+**Step 1: Check for user-provided flags**:
+
+**Check $ARGUMENTS for --scan flag**:
+- If `$ARGUMENTS` contains "--scan": Execute **SCAN MODE** (steps 2-4)
+- If `$ARGUMENTS` is empty: **Interactive mode selection** (see below)
+- Otherwise: Execute **INTERACTIVE MODE** (steps 5-10)
+
+**Step 2: Interactive mode selection (if no flags provided)** ✨ NEW:
+
+If `$ARGUMENTS` is empty, detect context and provide intelligent mode selection:
+
+```markdown
+## 🔍 Clarification Mode Selection
+
+No clarification mode specified. Please choose the appropriate mode:
+
+**Context Detection**:
+- Clarifications file exists: [YES/NO]
+- Previous clarifications: [N total, M Must, N Suggested, K Can Infer]
+- Unresolved Must Clarify: [N remaining]
+
+---
+
+### Mode Options:
+
+**1. Interactive Mode** (Recommended for most cases)
+- Ask questions one by one interactively
+- You control the pace
+- Integrate answers into spec.md immediately
+- Best for: Thorough clarification with user oversight
+
+**2. Scan Mode Only** (Recommended to generate questions without answering)
+- Scan spec.md for ambiguities
+- Categorize questions (Must/Suggested/Can Infer)
+- Generate/update clarifications.md
+- No user interaction required
+- Best for: Quick question generation, review questions later
+
+**3. Scan + Auto-Infer** (Recommended if you want AI to resolve automatically)
+- Scan spec.md for ambiguities
+- Auto-infer [Can Infer] questions automatically
+- Mark as [inferred] in clarifications.md
+- Leave [Must] and [Suggested] for manual resolution
+- Best for: Reduce question count, focus on critical issues
+
+---
+
+**AI Recommendation**: [Mode Name]
+
+**Reason**: [Why this mode is recommended based on current context]
+
+Examples:
+- "No clarifications file exists → Interactive Mode (1) - Start from scratch"
+- "You have 5 Must Clarify unresolved → Interactive Mode (1) - Complete critical questions"
+- "You have 20 Can Infer items → Scan + Auto-Infer (3) - Auto-resolve obvious questions"
+- "This is your first clarification → Interactive Mode (1) - Understand your requirements"
+
+---
+
+Your choice (1-3):
+```
+
+**Step 3: Execute selected mode**:
+
+After user selection:
+- **Choice 1**: Execute INTERACTIVE MODE (steps 5-10)
+- **Choice 2**: Execute SCAN MODE only (steps 2-4), then stop
+- **Choice 3**: Execute SCAN MODE (steps 2-4) + Auto-infer all [Can Infer] items
+
+**Context Detection Rules**:
+- **No clarifications.md** exists: Recommend Interactive Mode (1) - "Start from scratch"
+- **Must Clarify > 0**: Recommend Interactive Mode (1) - "Complete critical questions first"
+- **Can Infer > 10**: Recommend Scan + Auto-Infer (3) - "Many questions AI can answer"
+- **First-time clarification** (no file): Recommend Interactive Mode (1)
+- **Review phase** (clarifications.md exists, reviewing): Recommend Scan Mode (2)
+
+**Smart Recommendation Logic**:
+```markdown
+IF clarifications.md does NOT exist THEN:
+  Recommend: Interactive Mode (1)
+  Reason: "This is your first clarification. Best to go through questions interactively to understand your requirements."
+
+ELSE IF [Must Clarify] items > 0 THEN:
+  Recommend: Interactive Mode (1)
+  Reason: "You have N critical [Must Clarify] questions remaining. These should be resolved before planning."
+
+ELSE IF [Can Infer] items > 10 THEN:
+  Recommend: Scan + Auto-Infer (3)
+  Reason: "You have N [Can Infer] questions that AI can answer automatically. This will reduce manual effort."
+
+ELSE:
+  Recommend: Interactive Mode (1)
+  Reason: "Continue clarifying any remaining questions interactively."
+END IF
+```
+
+---
+
+## SCAN MODE (Generate clarifications.md)
+
+Execution steps for scan mode:
+
+1. Run `.specpro/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once**. Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - If JSON parsing fails, abort and instruct user to re-run `/specpro-specify` or verify the setup.
+
+2. Load the current spec file (FEATURE_SPEC). 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.
+
+   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
+     ⚠️ **This category carries a MANDATORY trigger, and the carve-out below does
+     not reach it** — see "The `Integration & External Dependencies` trigger" that
+     follows the list.
+
+   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)
+
+   ⚠️ **The `Integration & External Dependencies` trigger** — TR002's enforcement
+   point, and the one category the carve-out just above does NOT reach:
+
+   - **Trigger**: the spec names an outside system the product MUST interoperate with. Read
+     this at the **FUNCTIONAL layer** — a system the *requirements* talk to — never at
+     the implementation stack (libraries, frameworks, language versions are not it).
+     ⚠️ **Triggering does not require the spec to LABEL it**: what the criterion is
+     about is "an outside object exists and its failure modes have not been considered", and
+     how the spec happens to name that object — a labelled form, or a bare functional one
+     such as "the payment gateway the checkout flow calls" — is immaterial to that.
+     ⚠️ **And that is why this enforcement point lands HERE rather than on a second
+     scanner.** The same-named check in `/specpro-qc` recognises an outside system only when
+     the spec **labels** it (`外部` / `第三方` / `external …` /
+     `third-party`); on an unlabelled functional-layer name it returns
+     `⊘ not decidable by this scan`, by design and on the record (`ISS-150`). That is a
+     declared limit of a *pattern scan* — not of this step, which is executed by a reader,
+     and reading for meaning is exactly what the recognition needs.
+   - **When the trigger fires, this category MUST NOT be marked Clear**, and it MUST yield a
+     question covering all three of its own bullets above: **failure modes** ·
+     **protocol / versioning assumptions** · **data import/export formats**.
+   - **That question MUST be categorised `[Must Clarify]`, not `[Suggested Clarify]`.**
+     ⚠️ **This categorisation IS the enforcement point** — it is what turns the
+     rule from advice into a stop: an unresolved `[Must Clarify]` item makes `/specpro-plan`
+     halt at `⛔ PLAN BLOCKED` (`commands/specpro.plan.md` → `### Step 3: Quality
+     Gates` → `#### 3.0 Clarifications Quality Gate`; the consumer is named there and is
+     not restated here).
+     ⚠️ **It diverges from step 3b's default, deliberately**: step 3b files
+     "Integration patterns (RESTful, GraphQL, etc.)" under `[Suggested Clarify]`. That default
+     covers an integration's **style**, where a reasonable default exists and the user may let
+     it stand. This trigger covers **an outside object whose failure modes nobody has looked
+     at** — no reasonable default is inferable, which is `[Must Clarify]`'s own fourth
+     scope ("No reasonable default exists").
+   - **Negative cases — the trigger MUST NOT fire**: the spec names no outside system it must
+     interoperate with ⇒ judge this category as usual (Clear is allowed; no question is
+     produced). ⚠️ **A sentence that DENIES external dependencies does not fire it**
+     (`本项目自包含，无外部依赖。`): the
+     trigger reads whether an outside object is *required to take part*, not which nouns appear.
+
+3. **Categorize clarification questions** into three types:
+
+   a. **[Must Clarify]**: Critical questions that MUST be answered by the user before implementation. Plan stage is BLOCKED until these are resolved.
+      - Scope: Affects feature boundaries or what's included/excluded
+      - Security/Privacy: Legal, financial, or compliance implications
+      - User Roles: Multiple conflicting interpretations possible
+      - Performance Targets: No reasonable default exists
+
+   b. **[Suggested Clarify]**: Important questions with reasonable defaults. User can choose to answer manually OR request AI auto-inference.
+      - Error handling strategies (user-friendly messages, fallbacks)
+      - Data retention policies (industry-standard defaults)
+      - Integration patterns (RESTful, GraphQL, etc.)
+      - Performance optimization priorities
+
+   c. **[Can Infer]**: Questions that AI can answer using context, industry standards, or logical inference. AI will auto-resolve these.
+      - Logging formats (JSON with timestamp, level, message, context)
+      - Testing coverage targets (>70% business logic, >90% protocols)
+      - Code style (language conventions, indentation width, max line length)
+      - Standard authentication patterns (session-based or OAuth2 for web)
+
+4. **Load clarifications template**: Read `.specpro/templates/clarifications-template.md` to understand the required format.
+
+5. **Generate or update clarifications.md**:
+   - Load existing `specs/clarifications.md` if it exists (for UPDATE_MODE)
+   - Assign sequential IDs to new questions (Q001, Q002, etc.)
+   - For each clarification question, create an entry following the template format:
+     ```markdown
+     ### [Tag] - [ID] - [Question Summary]
+
+     **Status**: [ ] Unanswered | [x] Answered | [inferred] Auto-inferred
+
+     **Related Section**: [spec.md section reference, e.g., "FR-xxx", "US2"]
+
+     **Question**:
+     [Clear, specific question about requirements]
+
+     **Options** (if applicable):
+     | Option | Description | Implications |
+     |--------|-------------|--------------|
+     | A | [First option] | [What this means] |
+     | B | [Second option] | [What this means] |
+     | Auto | Let AI infer from context | [What AI will do] |
+
+     **Answer** (when answered or inferred):
+     [Concise answer that resolves the question]
+
+     **Resolution** (when answered or inferred):
+     - Updated spec.md section: [section name]
+     - New/updated FR: [FR-XXX] (if applicable)
+     - Details: [how the answer was integrated]
+     ```
+   - For [Can Infer] items, pre-fill the "Auto-Inference" field with how AI will resolve it
+   - Write to `specs/clarifications.md`
+   - If updating existing file, preserve already-resolved items ([x] or [inferred])
+
+6. **Report scan completion**:
+   ```markdown
+   ✓ Clarification scan complete
+
+   **Clarifications File**: specs/clarifications.md
+   - [Must Clarify]: M items (must be resolved before Plan)
+   - [Suggested Clarify]: N items (can answer manually or auto-infer)
+   - [Can Infer]: K items (AI can auto-resolve)
+
+   **Next Steps**:
+   - Run /specpro-clarify to start interactive clarification
+   - Or review clarifications.md first, then run /specpro-clarify
+   - Note: /specpro-plan will auto-invoke clarification if [Must Clarify] items remain
+   ```
+
+---
+
+## INTERACTIVE MODE (Ask questions and integrate answers) ✨ ENHANCED (Incremental Processing)
+
+Execution steps for interactive mode:
+
+1. Run `.specpro/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once**. Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - If JSON parsing fails, abort and instruct user to re-run `/specpro-specify` or verify the setup.
+
+2. **Load clarifications.md** ✨ ENHANCED:
+   - Read `specs/clarifications.md`
+   - If file doesn't exist, warn user: "No clarifications.md found. Please run `/specpro-clarify --scan` first to generate clarification questions."
+   - Extract all clarification items with status `[ ]` (unanswered)
+
+2.5. **Filter for Modified/New items** ✨ NEW (Incremental Clarification):
+
+   **Purpose**: Only ask questions related to modified or new spec items, skip already-processed questions
+
+   a. **Parse spec.md for Lifecycle fields**:
+      ```markdown
+      Load spec.md and extract Lifecycle status for items referenced in clarifications.md:
+      - User Stories: SpecStatus, PlanStatus, TasksStatus
+      - Functional Requirements: SpecStatus, PlanStatus, TasksStatus
+
+      Create map:
+      clarification_id → spec_item_status
+      ```
+
+   b. **Filter clarification questions**:
+      ```markdown
+      For each clarification in clarifications.md:
+      - Find related spec item (from "Related Section" field)
+      - Check spec item's SpecStatus:
+        * `[specify:…]` ∈ {`create`, `update`} → **KEEP** (needs clarification) —— ⚠️ 本节此前认的是 `"Add"`／`"Modified"`（`T174`），而 **Lifecycle 的取值表里没有这两个词** ⇒ 该过滤器在本仓库的任何产物上都保留不了东西，**且不报错**。
+        * `[specify:delete]`，或 `[plan:deprecated]`／`[tasks:deprecated]` → **SKIP** (item deprecated, ignore)
+        * SpecStatus = "" (no Lifecycle) → **KEEP** (legacy, pre-Lifecycle item)
+      ⚠️ **Those three branches are the WHOLE filter — everything not deprecated and not Lifecycle-less is KEEP.** A fourth branch reading `[specify:processed]` → SKIP used to sit here; it is **removed, not fixed** (`T247` / `ISS-220`): no writer anywhere in the toolchain ever produces that value, so the branch was **unreachable from the day it was written** — it could never skip anything, and its presence made the filter *look* like it excluded already-processed items. ⚠️ **Do not restore it**, and do not "give it a writer": `FR-046` fixes the segment's meaning as *how an item entered* (not where it now is), and `/specpro-specify`'s own merge rule forbids touching the Lifecycle of an unchanged item ⇒ **that segment has no terminal moment to write.**
+
+      Filtered clarifications:
+      - Total clarifications: N
+      - From modified/new items: X (ASK THESE)
+      - From deprecated items: Y (SKIP - no longer relevant)
+      - From legacy items (no Lifecycle): Z (ASK THESE — nothing says they were resolved)
+      ```
+
+   c. **Report filtering statistics**:
+      ```markdown
+      ## Clarification Filtering Summary
+
+      **Total Questions**: 15
+      - **From Modified/New Items**: 3 (ASK) ⭐
+      - **From Processed Items**: 10 (SKIP - already clarified)
+      - **From Deprecated Items**: 2 (SKIP - no longer relevant)
+
+      Processing 3 questions from modified/new items...
+      ```
+
+   d. **Create filtered question list**:
+      - Replace original clarification list with filtered list
+      - Only include questions from modified/new items
+      - Preserve question IDs, options, and metadata
+
+   **Benefits**:
+   - ✅ Clarify time reduced by 50-70% (skip already processed)
+   - ✅ Focus on truly unclear content (modified/new items)
+   - ✅ Avoid re-clarifying already resolved issues
+   - ✅ Smoother incremental iteration experience
+
+3. **Prioritize questions** by category:
+   - Process ALL [Must Clarify] items first (in order Q001, Q002, etc.)
+   - Then [Suggested Clarify] items
+   - Then [Can Infer] items
+
+4. **Sequential questioning loop**:
+   - Present EXACTLY ONE question at a time.
+   - For each question, display:
+     ```markdown
+     ### Question [ID]: [Question Summary]
+
+     **Category**: [Must Clarify | Suggested Clarify | Can Infer]
+     **Related Section**: [spec.md reference]
+
+     **Question**:
+     [Full question text]
+
+     **Options** (if applicable):
+     | Option | Description | Implications |
+     |--------|-------------|--------------|
+     | A | [Option A] | [Implications] |
+     | B | [Option B] | [Implications] |
+     | Auto | Let AI infer from context | [What AI will do] |
+
+     Your answer (option letter, "Auto", or custom answer):
+     ```
+   - 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)
+     - Format as: `**Recommended:** Option [X] - <reasoning>`
+   - After the user answers:
+     - If the user replies with "yes", "recommended", "suggested", or "auto", use the recommended/auto-inferred answer
+     - Otherwise, validate the answer maps to one option or is appropriate
+     - Once satisfactory, proceed to integration
+
+5. **Integration after EACH accepted answer** (incremental update approach):
+   - **Core Principle**: Convert clarifications into Functional Requirements, not separate records
+   - Maintain in-memory representation of the spec (loaded once at start) plus clarifications.md
+   - For each accepted answer, immediately convert it to Functional Requirements:
+     - **Functional ambiguity** → Update or add a Functional Requirement (FR) with "System MUST" format
+     - **User interaction / actor distinction** → Update User Story description or add new acceptance scenario
+     - **Data shape / entities** → Update Data Model entities (add fields, types, relationships)
+     - **Non-functional constraint** → Add/modify FR with measurable criteria (convert vague adjective to metric)
+     - **Edge case / negative flow** → Add new FR with "System MUST" format (not separate Edge Cases section)
+     - **Technical decision** → Convert decision into FR (e.g., "Use hybrid protocol" → "System MUST use hybrid protocol...")
+   - If the clarification invalidates an earlier ambiguous statement, replace that FR instead of duplicating
+   - Use the next available FR number — e.g., if the highest existing FR is `FR-xxx`, the new one takes the next integer in sequence (never reuse or renumber)
+   - **Update clarifications.md**:
+     - Mark item status as `[x]` (Answered)
+     - Fill in "Answer" field with the user's response
+     - Fill in "Resolution" field with what was updated in spec.md
+   - Save BOTH spec.md and clarifications.md AFTER each integration (atomic overwrite)
+   - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact
+
+6. **Validation** (performed after EACH write plus final pass):
+   - Each accepted answer was converted to a Functional Requirement or User Story update
+   - Updated spec.md sections contain no lingering vague placeholders
+   - No contradictory earlier statement remains
+   - Markdown structure valid
+   - Terminology consistency: same canonical term used across all updated sections
+   - clarifications.md was updated with [x] status and resolution details
+
+7. **Stop conditions** for questioning loop:
+   - ALL [Must Clarify] items have been answered (status [x])
+   - Then prompt user:
+     ```markdown
+     ✓ All [Must Clarify] items resolved
+
+     **Remaining Items**:
+     - [Suggested Clarify]: N items unresolved
+     - [Can Infer]: M items unresolved
+
+     **Next Steps**:
+     1. Continue answering [Suggested Clarify] questions (recommended) - improves spec quality
+     2. Auto-infer all remaining items - AI will resolve [Suggested Clarify] and [Can Infer] automatically
+     3. Skip for now - leave remaining items unresolved, you can run /specpro-clarify again later
+
+     Your choice (1/2/3):
+     ```
+
+8. **Process user choice**:
+
+   a. **If user chooses 1 (Continue - recommended)**:
+      - Continue questioning loop with [Suggested Clarify] items
+      - Ask each [Suggested Clarify] question one by one
+      - After each answer, integrate into spec.md and clarifications.md (same as Step 5)
+      - After all [Suggested Clarify] resolved, prompt again:
+        ```markdown
+        ✓ All [Suggested Clarify] items resolved
+
+        **Remaining Items**:
+        - [Can Infer]: N items unresolved
+
+        **Next Steps**:
+        1. Auto-infer [Can Infer] items (recommended) - AI will resolve automatically
+        2. Continue answering [Can Infer] questions - answer each question manually
+        3. Skip for now - leave [Can Infer] items unresolved
+
+        Your choice (1/2/3):
+        ```
+      - If user chooses 1: Run auto-inference on [Can Infer] items (see step 8b)
+      - If user chooses 2: Continue questioning loop with [Can Infer] items (same as Step 4)
+        - After all [Can Infer] resolved, proceed to completion report (step 9)
+      - If user chooses 3: Proceed to completion report (step 9)
+
+   b. **If user chooses 2 (Auto-infer)**:
+      - Process ALL remaining [Suggested Clarify] and [Can Infer] items automatically
+      - For each item:
+        - Use context, industry standards, and logical inference to determine answer
+        - Convert answer to FR or update spec.md as needed
+        - Mark item as `[inferred]` in clarifications.md
+        - Fill in "Answer" and "Resolution" fields
+      - Save spec.md and clarifications.md after each item
+      - Report: "✓ Auto-inferred N items (M [Suggested Clarify], K [Can Infer])"
+      - Proceed to completion report (step 9)
+
+   c. **If user chooses 3 (Skip)**:
+      - Proceed directly to completion report (step 9)
+      - Leave remaining items as unresolved ([ ] status)
+
+9. **Report completion** (after questioning loop ends or auto-inference completes):
+   ```markdown
+   ✓ Clarification complete
+
+   **Questions Resolved**: N answered, M auto-inferred
+   **Spec File**: [path to spec.md]
+   **Clarifications File**: [path to clarifications.md]
+
+   **Resolution Summary**:
+   - [Must Clarify]: N/M resolved (all required items resolved ✓)
+   - [Suggested Clarify]: X/Y resolved or inferred
+   - [Can Infer]: P/Q resolved or inferred
+
+   **Sections Updated**: [list of spec.md sections modified]
+
+   **Important**: Your spec.md has been significantly updated with clarification answers.
+   Please review the changes before proceeding to planning.
+
+   **Next Steps**:
+   1. Review specs/spec.md to verify the updates
+   2. Run /specpro-plan to create technical plan (ready - all [Must Clarify] resolved ✓)
+   3. Or run /specpro-clarify again if more clarifications needed
+   ```
+
+10. **Quality gates**:
+    - If any [Must Clarify] items remain unresolved ([ ] status), warn user:
+      "⚠️ WARNING: [Must Clarify] items remain unresolved. /specpro-plan will be blocked until these are resolved."
+
+Behavior rules:
+
+**For SCAN MODE**:
+- If spec.md is missing, abort and instruct user to run `/specpro-specify` first
+- If no meaningful ambiguities found, respond: "No critical ambiguities detected worth formal clarification. Clarifications file not created." and suggest proceeding to `/specpro-plan`
+- Always generate clarifications.md even if only [Can Infer] items exist
+- Preserve existing [x] or [inferred] items when updating
+
+**For INTERACTIVE MODE**:
+- If clarifications.md doesn't exist, instruct user to run `/specpro-clarify --scan` first
+- If all items already resolved ([x] or [inferred]), report: "All clarifications resolved. Ready for `/specpro-plan`."
+- Respect user early termination signals ("stop", "done", "proceed")
+- After completing [Must Clarify], ALWAYS prompt about [Suggested Clarify] and [Can Infer] items (don't auto-advance)
+- Auto-inference MUST process both [Suggested Clarify] and [Can Infer] items when requested
+- Never skip unresolved [Must Clarify] items - these are hard blockers for Plan
+
+**Common rules**:
+- Clarifications are converted to Functional Requirements (not separate records)
+- Each answer is immediately integrated into spec.md and clarifications.md
+- Maintain traceability: every clarification should have a Resolution field linking to spec.md changes
+
+Context for prioritization: $ARGUMENTS