unisono/specs/002-result-preparation-refactoring/spec.md

Feature Specification: Result Preparation Refactoring

Feature Branch: 002-result-preparation-refactoring
Created: 2025-10-11
Status: Draft
Input: User description: "Users fill the response form with what they WANT, ACCEPT, and DO NOT WANT. Each field contains a text expressing user's desires. At least one of the fields is required. System checks each field for inner contradictions using an LLM. In case of contradictions, the system must ask the user to eliminate them. When all responses are received, the system initiates analysis and returns a result. The result is a cooperative decision prepared by an LLM based on everyone's opinions. The decision includes categories: Go-to, Also good, Considerable, No-goes, and Needs discussion."

Clarifications

Session 2025-10-11

• Q: How should the system handle the unavailability of the LLM service during a contradiction check? → A: A
• Q: How does the system know when all responses for a session have been received? → A: Existing function: session creator states the number of expected responses when creating a session.
• Q: What is the maximum number of participants a session should support? → A: Make it 20.

User Scenarios & Testing (mandatory)

User Story 1 - Submit Desires (Priority: P1)

A user fills out a form with their desires (what they want, accept, and don't want) and submits it.

Why this priority: This is the core functionality for a user to input their desires.

Independent Test: A user can open the form, fill in at least one of the fields, and successfully submit it.

Acceptance Scenarios:

1. Given a user is on the desire submission page, When they fill in the "WANT" field and click submit, Then their submission is accepted.
2. Given a user is on the desire submission page, When they do not fill in any fields and click submit, Then they receive an error message.

---

User Story 2 - Inner Contradiction Check (Priority: P1)

The system checks the user's submitted desires for internal contradictions within each category. If contradictions are found, the user is prompted to resolve them.

Why this priority: Ensures the quality and consistency of user input before the final analysis.

Independent Test: A user submits a desire set with a contradiction (e.g., "I want a dog" and "I don't want any pets" in the WANT field), and the system identifies the contradiction and prompts the user for correction.

Acceptance Scenarios:

1. Given a user has submitted a desire set with an internal contradiction, When the system processes the submission, Then the user is presented with a message indicating the contradiction and is asked to revise their submission.
2. Given a user has submitted a desire set with no internal contradictions, When the system processes the submission, Then the submission is accepted without any warnings.

---

User Story 3 - Generate Cooperative Decision (Priority: P2)

After all users have submitted their non-contradictory desires, the system analyzes them and generates a cooperative decision with the categories: Go-to, Also good, Considerable, No-goes, and Needs discussion.

Why this priority: This is the final output of the feature and delivers the core value to the users.

Independent Test: Given a set of desire submissions from multiple users, the system can generate a categorized result.

Acceptance Scenarios:

1. Given all users have submitted their desires, When the analysis is triggered, Then a result is generated with the five specified categories.
2. Given a set of desires where all users want "A", When the analysis is run, Then "A" appears in the Go-to category.
3. Given user 1 wants "B" and user 2 accepts "B", When the analysis is run, Then "B" appears in the Also good category.
4. Given user 1 wants "C" and user 2 has no opinion on "C", When the analysis is run, Then "C" appears in the Considerable category.
5. Given user 1 does not want "D", When the analysis is run, Then "D" appears in the No-goes category and not in any other category.
6. Given user 1 wants "E" and user 2 does not want "E", When the analysis is run, Then "E" appears in the Needs discussion category.

Edge Cases

• What happens if the LLM service is unavailable for contradiction checking? The system will display an error message and prevent the user from submitting their desires.
• How does the system handle a large number of participants in a session? A session will support a maximum of 20 participants.
• What happens if a user's input is very long? The system will enforce a character limit of 500 characters per desire field. The UI will display a character counter under each field. If the input exceeds this limit, the system will return an error message and prevent submission.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST provide a form with three text fields: "What you WANT", "What you ACCEPT", and "What you DO NOT WANT".
• FR-001a: The UI MUST display a character counter under each of the three desire input fields.
• FR-002: The system MUST require at least one of the three fields to be filled.
• FR-003: The system MUST use an LLM to check for inner contradictions within each of the three fields of a user's submission.
• FR-004: If inner contradictions are found, the system MUST inform the user and ask them to revise their submission.
• FR-005: The system MUST be able to receive and store desire submissions from multiple users for a session.
• FR-006: The system MUST trigger the analysis process after all responses for a session are received.
• FR-007: The system MUST generate a result categorized into Go-to, Also good, Considerable, No-goes, and Needs discussion.
• FR-008: The Go-to category MUST contain items that all participants want and have no contradictions.
• FR-009: The Also good category MUST contain items that at least one participant wants and all other participants accept.
• FR-010: The Considerable category MUST contain items that are wanted or accepted by some, but not all, participants.
• FR-011: The No-goes category MUST contain items that at least one participant does not want. These items MUST be excluded from all other categories.
• FR-012: The Needs discussion category MUST contain items where contradictions are found between participants' desires.
• FR-013: The system MUST present the final categorized result to the users.

Key Entities (include if feature involves data)

• Desire Set: A user's submission, containing three text fields: want, accept, dont_want.
• Session: A collection of Desire Sets from multiple users.
• Result: The categorized output of the analysis of a Session.

Assumptions

• The LLM service for contradiction checking and result preparation is available and responsive.
• The number of participants in a session and the length of their inputs are within reasonable limits for the LLM to process effectively.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 100% of user submissions are checked for inner contradictions.
• SC-002: The system correctly identifies and categorizes desires according to the rules in 100% of cases with no contradictions.
• SC-003: The system correctly identifies and categorizes desires into the "Needs discussion" category when contradictions exist between users.
• SC-004: Users can successfully submit their desires in under 1 minute.