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

Feature Specification: Afraid to Ask Feature

Feature Branch: 004-afraid-to-ask
Created: October 13, 2025
Status: Draft
Input: User description: "Afraid to Ask. Requirements are in the file .context/afraid-to-ask.md"

User Scenarios & Testing (mandatory)

User Story 1 - Submitting an "Afraid to Ask" Idea (Priority: P1)

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: Core functionality, enables users to express sensitive desires while maintaining privacy.

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 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 - "Afraid to Ask" Idea Matching (Priority: P1)

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: Defines the core logic for how "Afraid to Ask" ideas interact with other users' desires and ensures conditional visibility.

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 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 - Data Privacy and Ephemerality (Priority: P1)

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: Addresses critical privacy and data retention requirements, building user trust.

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 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: 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)

• 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: 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.