unisono/specs/001-people-tend-to/spec.md

Feature Specification: Anonymous Desire Aggregator

Feature Branch: 001-people-tend-to
Created: 2025-10-09
Status: Draft
Input: User description: "People tend to not wanting to discuss their choices when agreeng on some common activity with others. For example, lovers might be ashamed to discuss some things straightforward before having sex. But they could privately state what they want and then blindly share their desires. The app will understand where they totally agree, where they partially agree, where they accept any suggestions, and where they totally disagree. The first person in a session states the topic and how many answers to anticipate, and shares the link to the session by copying it. One online session, totally anonymous and private, summons persons presenting their desires. Users write what they want, what they accept, and what they do not want at all - and submit the form. The system waits for all the answers and analyzes them with AI. While waiting for the results user sees some placeholder informing that the work is in progress: waiting for X more answers, analyzing results etc. Then the system presents the results: a cooperative decision based on everyone's opinions. The decision includes everything that participants want if everyone wants it too marking this part as GoTos. Things someone wants and everyone else just accept are in the category AlsoGoods. Things that are just wanted or accepted by some participants are in the category of their own - Considerables. The decision respects everything that at least one user does not want at all stating it as No-goes and excluding from every other category. The result is available by the link as long as the session is alive synching from local storage of participants via websockets."

Clarifications

Session 2025-10-09

• Q: How should the system handle variations in user-submitted desire items to ensure accurate aggregation? → A: Some LLM will understand the sense, analyze and combine resluts. Not just survey.
• Q: How should the system behave if more participants join and submit than the number originally specified by the session creator? → A: Lock the Session: Once the expected number of submissions is reached, no more submissions are allowed. Additional users see a "Session full" message.
• Q: How should the system handle a submission where one or more of the desire categories are empty? → A: Require At Least One Item: The user must enter at least one item in at least one of the categories. They cannot submit a completely blank form.
• Q: How should the "Considerable" category be refined to ensure it provides a useful signal to the group? → A: Just collapse this catogory in GUI giving it less attention.

User Scenarios & Testing (mandatory)

User Story 1 - Create and Share a Session (Priority: P1)

As a user, I want to create a new session by providing a topic and the number of expected participants, so I can receive a unique link to share with others for anonymously gathering their preferences.

Why this priority: This is the starting point for the entire workflow. Without the ability to create a session, no other functionality can be used.

Independent Test: Can be fully tested by creating a session and verifying that a unique, shareable link is generated and the session is ready for participants.

Acceptance Scenarios:

1. Given I am on the application's home page, When I enter a topic "Dinner Plans" and set the number of participants to 4, Then the system should generate a unique URL, display it, and provide a "copy to clipboard" button.
2. Given a session has been created, When I visit the generated URL, Then I should see the session's topic and the desire submission form.

---

User Story 2 - Participate in a Session (Priority: P2)

As a user with a session link, I want to submit my preferences by listing items I "Want", "Accept", or "Do Not Want", so that my input is included in the final decision.

Why this priority: This is the core data-gathering function. The value of the application depends on participants being able to submit their desires easily and anonymously.

Independent Test: Can be tested by navigating to a session link, filling out and submitting the desire form, and verifying the submission is recorded.

Acceptance Scenarios:

1. Given I have a valid session link and the session is waiting for participants, When I enter items into the "Want", "Accept", and "Do Not Want" fields and press "Submit", Then the system should confirm my submission and update the session status.
2. Given I have submitted my desires, When I revisit the session link, Then the system should show me a waiting screen indicating how many more participants are needed.

---

User Story 3 - View Aggregated Results (Priority: P3)

As a session participant, I want to see the final, categorized results after everyone has submitted their desires, so that our group can easily identify common ground and make a cooperative decision.

Why this priority: This is the "payoff" for the users. It delivers the promised value of a synthesized, cooperative decision, which is the main reason for using the app.

Independent Test: Can be tested by creating a session, having all participants submit their desires, and verifying that the final results are displayed correctly according to the aggregation logic.

Acceptance Scenarios:

1. Given all participants in a session have submitted their desires, When I visit the session link, Then I should see the results screen with the categories: "GoTos", "AlsoGoods", "Considerables", and "NoGoes".
2. Given the results are displayed, When an item was marked "Do Not Want" by at least one person, Then it must appear in the "NoGoes" list and nowhere else.
3. Given the results are displayed, When an item was marked "Want" by all participants, Then it must appear in the "GoTos" list.

---

Edge Cases

• What happens if a user provides the same item in multiple categories (e.g., in both "Want" and "Do Not Want")? (Addressed by FR-016)
• What happens if a user tries to submit their desires more than once for the same session? (Addressed by FR-017)
• What happens if the number of participants who join via the link exceeds the number set by the creator? (Addressed by FR-019)
• What happens if a session link is accessed after the session is considered "closed" or has expired? (Addressed by FR-018)

Requirements (mandatory)

Functional Requirements

• FR-001: System MUST allow a user to create a new session by specifying a topic and the number of expected participants.
• FR-002: System MUST generate a unique, shareable URL for each new session.
• FR-003: System MUST allow any user with the session URL to participate anonymously without requiring login or registration.
• FR-004: System MUST provide a form for participants to submit desires as free-form text into three distinct categories: "Want", "Accept", and "NoGoes".
• FR-005: System MUST display a real-time status indicating how many participants are still needed before results can be calculated.
• FR-006: System MUST begin the analysis process only after the specified number of participants have submitted their desires.
• FR-007: System MUST display a status to users indicating that analysis is in progress.
• FR-008: System MUST use semantic analysis (e.g., via an LLM) to interpret raw text inputs and group them into unique, semantically equivalent Semantic Desires.
• FR-009: The system MUST calculate the final decision based on the aggregation of these Semantic Desires.
• FR-010: A Semantic Desire MUST be categorized as "NoGoes" if at least one participant includes it in their "Do Not Want" list. This category takes precedence over all others.
• FR-011: A Semantic Desire MUST be categorized as "GoTos" if it is not a "NoGoes" and all participants include it in their "Want" list.
• FR-012: A Semantic Desire MUST be categorized as "AlsoGoods" if it is not a "NoGoes" or "GoTos", is in at least one participant's "Want" list, and all other participants have it in either their "Want" or "Accept" lists.
• FR-013: A Semantic Desire MUST be categorized as "Considerables" if it is not in any other category but is present in at least one participant's "Want" or "Accept" list.
• FR-014: System MUST display the final, categorized results to all participants in the session.
• FR-015: The results view MUST be updated in real-time for all participants.
• FR-016: System MUST validate a user's submission to prevent the same item from appearing in conflicting categories (e.g., in both "Want" and "Do Not Want"). If a conflict is detected, the system MUST display a clear, inline error message next to the conflicting input fields, highlighting the problematic items and preventing form submission until all conflicts are resolved by the user.
• FR-017: System MUST allow each participant to submit their desires only once. Participant identity MUST be established and persisted using a client-side generated UUID stored in the browser's Local Storage. If a user attempts to submit again from the same client (identified by the stored UUID), the system MUST inform them that their submission has already been recorded and prevent resubmission.
• FR-018: A session MUST remain active and its results accessible as long as at least one participant maintains an active WebSocket connection to the session. The session and its data MUST be terminated from the backend's active memory 5 minutes after the last participant disconnects. Frontend clients should handle this by displaying a "Session Expired" message and redirecting to the home page.
• FR-019: Once the number of submitted desire sets equals the expected number of participants, the session MUST be automatically locked. The submission form MUST be disabled, and any user attempting to access it MUST be shown a clear message indicating "Session Full" or "Analysis in Progress" (depending on the current state), preventing further submissions.
• FR-020: The system MUST require a user to enter at least one desire in at least one of the three categories ("Want", "Accept", "Do Not Want") before a submission can be accepted. Completely empty submissions MUST be rejected, and the system MUST display an inline error message prompting the user to fill in at least one category.
• FR-021: On the results screen, the "Considerables" category MUST be presented in a way that gives it less prominence than "GoTos" and "AlsoGoods", for instance, by being collapsed by default.

Key Entities (include if feature involves data)

• Session: Represents a single decision-making event.
  • Attributes: Topic (text), Expected Participant Count (number), Unique ID/URL (string), Status (e.g., "Waiting", "Analyzing", "Complete").
• Participant: Represents an anonymous user within a given session.
• Desire Set: Represents a single participant's raw text submission.
  • Attributes: Wants (list of strings), Accepts (list of strings), Do Not Wants (list of strings).
• Semantic Desire: Represents a unique conceptual desire identified by the system's semantic analysis of the raw text in Desire Sets. For example, the text inputs "go for a run", "running", and "a jog" would all map to a single Semantic Desire representing the concept of 'running'. The system should normalize variations in phrasing, synonyms, and minor grammatical differences to identify the underlying common intent.
• Decision: Represents the final aggregated output for a session.
  • Attributes: GoTos (list of Semantic Desires), AlsoGoods (list of Semantic Desires), Considerables (list of Semantic Desires), NoGoes (list of Semantic Desires).

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: A new session can be created and the shareable link generated in under 10 seconds.
• SC-002: At least 95% of participants can submit their desires on the first attempt without encountering an error message or being prevented from submitting due to validation issues.
• SC-003: For a session with up to 10 participants, the results are calculated and displayed within 5 seconds of the final participant's submission.
• SC-004: The final decision categories must correctly reflect the aggregation logic in 100% of automated test cases covering all rules and edge cases.
• SC-005: Post-feature user satisfaction surveys indicate that at least 80% of users rate the application's ease of use (e.g., intuitive session creation, clear submission process, understandable results) as 4 or 5 on a 5-point Likert scale (1=Very Difficult, 5=Very Easy) for making group decisions.