"Agraid to Ask" feature redesigned with SpecKit 62

specs/004-afraid-to-ask/spec.md

@@ -1,89 +1,98 @@
-# Feature Specification: `speckit.specify` command automation
+# Feature Specification: Afraid to Ask Feature
 
 **Feature Branch**: `004-afraid-to-ask`  
-**Created**: 2025-10-13  
+**Created**: October 13, 2025  
 **Status**: Draft  
-**Input**: User description: "Afraid to Ask. The requirements are in the .context/afraid-to-ask.md file."
+**Input**: User description: "Afraid to Ask. Requirements are in the file .context/afraid-to-ask.md"
 
 ## User Scenarios & Testing *(mandatory)*
 
-### User Story 1 - Core Spec Generation (Priority: P1)
+### User Story 1 - Submitting an "Afraid to Ask" Idea (Priority: P1)
 
-A developer provides a feature description to the `/speckit.specify` command. The system automatically generates a new feature branch and a complete, structured `spec.md` file based on a template, filling in details derived from the description.
+A user wants to express a sensitive desire without immediately revealing it to others. They use the new "Afraid to Ask" field to submit their idea.
 
-**Why this priority**: This is the core functionality. Without it, the feature has no value.
+**Why this priority**: Core functionality, enables users to express sensitive desires while maintaining privacy.
 
-**Independent Test**: Can be tested by running the command with a simple description and verifying that the correct branch and a well-formed spec file are created.
+**Independent Test**: A user can successfully submit an "Afraid to Ask" idea and see it reflected in their own session view (if applicable, without revealing it to others yet).
 
 **Acceptance Scenarios**:
 
-1. **Given** a developer is on the `main` branch, **When** they run `/speckit.specify "New feature"`, **Then** a new branch `[num]-new-feature` is created and checked out, and a `specs/[num]-new-feature/spec.md` file is created.
-2. **Given** a feature description, **When** the spec is generated, **Then** the spec file contains all the mandatory sections from the template.
+1.  **Given** a user is on the response form, **When** they enter text into the "Afraid to Ask" field and submit, **Then** the idea is recorded privately for that user.
+2.  **Given** a user has submitted an "Afraid to Ask" idea, **When** they view their own session details, **Then** their "Afraid to Ask" idea is visible to them.
 
 ---
 
-### User Story 2 - Validation and Checklists (Priority: P2)
+### User Story 2 - "Afraid to Ask" Idea Matching (Priority: P1)
 
-After generating the spec, the system automatically creates a `requirements.md` checklist and validates the spec against it.
+A user's "Afraid to Ask" idea is compared against other participants' "Want" or "Accept" desires. If a match is found, it's treated as a "Want" for the submitting user in the results; otherwise, it remains private and is not shown.
 
-**Why this priority**: This ensures the quality and completeness of the generated spec, which is a key part of the desired workflow.
+**Why this priority**: Defines the core logic for how "Afraid to Ask" ideas interact with other users' desires and ensures conditional visibility.
 
-**Independent Test**: Can be tested by checking for the existence and content of the `requirements.md` file after a spec is generated.
+**Independent Test**: A user's "Afraid to Ask" idea that matches another user's "Want" or "Accept" is treated as a "Want" for the submitting user in the results. Conversely, an "Afraid to Ask" idea with no match is not displayed in the results.
 
 **Acceptance Scenarios**:
 
-1. **Given** a spec has been generated, **When** the validation step runs, **Then** a `checklists/requirements.md` file is created in the feature directory.
-2. **Given** a generated spec has obvious omissions (e.g., empty sections), **When** the validation runs, **Then** the corresponding items in the checklist are marked as failed.
+1.  **Given** User A submits an "Afraid to Ask" idea, and User B has a "Want" or "Accept" idea that semantically matches User A's "Afraid to Ask" idea, **When** the session results are generated, **Then** User A's "Afraid to Ask" idea is treated as a "Want" for User A in the results.
+2.  **Given** User A submits an "Afraid to Ask" idea, and no other user has a "Want" or "Accept" idea that semantically matches User A's "Afraid to Ask" idea, **When** the session results are generated, **Then** User A's "Afraid to Ask" idea does not appear in the results.
 
 ---
 
-### User Story 3 - Interactive Clarification (Priority: P3)
+### User Story 3 - Data Privacy and Ephemerality (Priority: P1)
 
-When the system encounters ambiguities in the feature description, it adds `[NEEDS CLARIFICATION]` markers to the spec. It then presents these as questions to the user and updates the spec with their answers.
+Users expect their "Afraid to Ask" ideas to be handled with maximum privacy and to be completely removed from the server once the session concludes.
 
-**Why this priority**: This handles cases where the AI cannot make a reasonable assumption, making the process more robust. It's P3 because the core generation can function without it for well-defined features.
+**Why this priority**: Addresses critical privacy and data retention requirements, building user trust.
 
-**Independent Test**: Can be tested by providing an ambiguous description and verifying that the system asks for clarification and correctly incorporates the answer.
+**Independent Test**: After a session terminates, no "Afraid to Ask" data is retrievable from the server, confirming complete data purging.
 
 **Acceptance Scenarios**:
 
-1. **Given** a feature description with an ambiguous requirement, **When** the spec is generated, **Then** it contains a `[NEEDS CLARIFICATION]` marker.
-2. **Given** a spec with a clarification marker, **When** the clarification flow is triggered, **Then** the user is presented with a formatted question and options.
-3. **Given** a user provides an answer, **When** the system processes it, **Then** the `[NEEDS CLARIFICATION]` marker in the spec is replaced with the user's answer.
-
----
-
-### Edge Cases
-
-- What happens when the feature description is empty?
-- How does the system handle a non-git repository?
-- How does the system handle a situation where the generated branch name already exists?
+1.  **Given** a session has terminated, **When** an attempt is made to retrieve "Afraid to Ask" data from the server, **Then** no such data is found.
 
 ## Requirements *(mandatory)*
 
 ### Functional Requirements
 
-- **FR-001**: System MUST accept a natural language string as a feature description.
-- **FR-002**: System MUST generate a unique, kebab-cased feature branch name from the description, prefixed with a 3-digit incrementing number.
-- **FR-003**: System MUST create and check out a new git branch with the generated name.
-- **FR-004**: System MUST create a new directory for the feature under the `specs/` directory.
-- **FR-005**: System MUST create a `spec.md` file in the new feature directory, populated from a template.
-- **FR-006**: System MUST parse the feature description to populate the sections of the `spec.md` file.
-- **FR-007**: System MUST create a `checklists/requirements.md` file to validate the spec.
-- **FR-008**: System MUST identify and flag ambiguous requirements with `[NEEDS CLARIFICATION]` markers (max 3).
-- **FR-009**: System MUST present clarification questions to the user and update the spec with their answers.
-- **FR-010**: System MUST handle cases where a generated branch name already exists by checking out the existing branch instead of failing.
+-   **FR-001**: The system MUST provide an "Afraid to Ask" input field on the response form, located directly under the "What you want" field.
+-   **FR-002**: The system MUST ensure that "Afraid to Ask" ideas are initially private to the submitting user and not visible to other participants.
+-   **FR-003**: The system MUST semantically compare "Afraid to Ask" ideas with other users' "Want" or "Accept" desires.
+-   **FR-004**: If an "Afraid to Ask" idea semantically matches another user's "Want" or "Accept" desire, the system MUST treat it as a "Want" for the submitting user in the session results.
+-   **FR-005**: If an "Afraid to Ask" idea does not semantically match any other user's "Want" or "Accept" desire, the system MUST exclude it from the session results.
+-   **FR-006**: The system MUST ensure maximum privacy for "Afraid to Ask" ideas, preventing their exposure to other users unless a semantic match occurs as per FR-004.
+-   **FR-007**: The system MUST purge all "Afraid to Ask" data from the server upon session termination, leaving no traces.
+-   **FR-008**: "Afraid to Ask" ideas will NOT influence session results beyond matching other users' "Want" or "Accept" desires.
+-   **FR-009**: The system will NOT perform long-term storage or analytics of "Afraid to Ask" ideas.
+-   **FR-010**: The UI MUST display a specific error message and prevent form submission if the semantic matching service is unavailable or returns an error.
+-   **FR-011**: The UI MUST display a "Harmonizing desires" placeholder during the semantic matching analysis of "Afraid to Ask" ideas.
+-   **FR-012**: The system MUST adhere to general data privacy best practices for handling "Afraid to Ask" data.
 
 ### Key Entities *(include if feature involves data)*
 
-- **Feature Specification**: A markdown document that describes a new feature. It includes user scenarios, requirements, and success criteria.
-- **Requirement Checklist**: A markdown document used to validate the quality and completeness of a feature specification.
+-   **User Idea**: Represents a user's desire, including "Want", "Accept", and "Afraid to Ask" types. Attributes include content and type. A single "Afraid to Ask" input field may contain one or multiple distinct ideas.
+-   **Session**: A collection of user ideas and their matching results, along with associated metadata.
 
 ## Success Criteria *(mandatory)*
 
 ### Measurable Outcomes
 
-- **SC-001**: A developer can generate a complete and validated draft specification from a one-sentence feature description in under 1 minute.
-- **SC-002**: 90% of generated specifications require no manual structural changes to the file itself (i.e., the template is correctly applied).
-- **SC-003**: The clarification process correctly resolves ambiguities in over 95% of cases where it is triggered.
-- **SC-004**: The time spent by developers writing initial feature specs is reduced by 75%.
+-   **SC-001**: Users can successfully submit "Afraid to Ask" ideas without them being immediately visible to other participants.
+-   **SC-002**: "Afraid to Ask" ideas that semantically match other users' "Want" or "Accept" desires are correctly reflected as "Want" in the results for the submitting user in 100% of test cases.
+-   **SC-003**: "Afraid to Ask" ideas that do not semantically match any other user's "Want" or "Accept" desires are completely absent from the session results in 100% of test cases.
+-   **SC-004**: No "Afraid to Ask" data is retained on the server after a session has concluded, ensuring complete privacy and data purging within 5 seconds of session termination.
+
+## Clarifications
+
+### Session October 13, 2025
+
+- Q: What explicit items are out-of-scope for the "Afraid to Ask" feature? → A: Handling of offensive/illegal "Afraid to Ask" ideas; "Afraid to Ask" ideas influencing session results beyond matching "Want" or "Accept"; Long-term storage or analytics of "Afraid to Ask" ideas.
+- Q: What is the expected maximum number of "Afraid to Ask" ideas per session or per user? → A: No particular number. The field contains some text that can contain one or multiple ideas.
+- Q: How should the UI behave if the semantic matching service is unavailable or returns an error? → A: Show the error message and prevent form submission.
+- Q: What is the target latency for semantic matching of an "Afraid to Ask" idea? → A: No target. Let the LLM work on it and display `Harmonizing desires` placeholder during analysis.
+- Q: Are there any specific compliance or regulatory requirements for handling sensitive "Afraid to Ask" data (e.g., GDPR, HIPAA)? → A: No specific regulatory requirements beyond general data privacy best practices.
+
+### Edge Cases
+
+- What happens when the "Afraid to Ask" field is left empty? (It should be ignored)
+- How does system handle partial matches between "Afraid to Ask" ideas and other desires? (Assume exact or semantic match based on existing LLM service)
+- What if a user submits multiple "Afraid to Ask" ideas? (Each is processed independently)
+- The system does NOT provide moderation or filtering for offensive or illegal content submitted via "Afraid to Ask" ideas.