ag/unisono
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Deleted obsolete files

Browse Source
This commit is contained in:
aodulov
2025-10-13 11:00:02 +03:00
parent 272c4f6148
commit 7be22129f6
11 changed files with 49 additions and 1301 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
specs/004-afraid-to-ask/spec.md
View File

@@ -1,86 +1,89 @@
# Feature Specification: Afraid to Ask
# Feature Specification: `speckit.specify` command automation
**Feature Branch**: `004-afraid-to-ask`
**Created**: 2025-10-13
**Status**: Draft
**Input**: User description: "Afraid to Ask. You can find requirements here: .context/afraid-to-ask.md"
**Input**: User description: "Afraid to Ask. The requirements are in the .context/afraid-to-ask.md file."
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Submitting an "Afraid to Ask" Idea (Priority: P1)
### User Story 1 - Core Spec Generation (Priority: P1)
A user wants to express a sensitive idea or desire without it being widely visible to others unless there is a clear alignment with other users' expressed desires. This allows them to gauge interest or acceptance for potentially sensitive topics in a private manner initially.
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.
**Why this priority**: This is the core functionality of the feature, enabling users to input their "Afraid to Ask" ideas. Without this, the feature cannot exist.
**Why this priority**: This is the core functionality. Without it, the feature has no value.
**Independent Test**: A user can navigate to the response form, input an idea into the "Afraid to ask" field, and submit the form. The system should record this idea with the specified privacy settings, and it should not immediately appear in public results unless compliance conditions are met.
**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.
**Acceptance Scenarios**:
1. **Given** a user is on the response form, **When** they enter an idea into the "Afraid to ask" field and submit the form, **Then** the idea is successfully recorded by the system with maximum privacy.
2. **Given** a user has submitted an "Afraid to ask" idea, **When** they view the results before any other user's "Want" or "Accept" ideas comply with it, **Then** their "Afraid to ask" idea is not publicly displayed in the results.
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.
---
### User Story 2 - Viewing Results with "Afraid to Ask" Ideas (Priority: P1)
### User Story 2 - Validation and Checklists (Priority: P2)
Users want to see if their sensitive ideas align with others' desires, or if others' sensitive ideas align with their desires, without explicitly revealing the "Afraid to Ask" nature of the idea until a match is found. This promotes discovery of shared, sensitive interests.
After generating the spec, the system automatically creates a `requirements.md` checklist and validates the spec against it.
**Why this priority**: This story defines how the "Afraid to Ask" ideas become visible and useful, providing the value proposition for the feature.
**Why this priority**: This ensures the quality and completeness of the generated spec, which is a key part of the desired workflow.
**Independent Test**: Multiple users can submit ideas, including "Afraid to ask" ideas and "Want"/"Accept" ideas. The system can then be queried to display results, and the visibility of "Afraid to ask" ideas should correctly reflect the compliance logic.
**Independent Test**: Can be tested by checking for the existence and content of the `requirements.md` file after a spec is generated.
**Acceptance Scenarios**:
1. **Given** User A has submitted an "Afraid to ask" idea, and User B has submitted a "Want" or "Accept" idea that complies with User A's "Afraid to ask" idea, **When** any user views the results, **Then** User A's "Afraid to ask" idea is displayed as if it were a "Want" idea from User A.
2. **Given** User A has submitted an "Afraid to ask" idea, and no other user's "Want" or "Accept" idea complies with User A's "Afraid to ask" idea, **When** any user views the results, **Then** User A's "Afraid to ask" idea is NOT displayed in the public results.
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.
---
### User Story 3 - Interactive Clarification (Priority: P3)
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.
**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.
**Independent Test**: Can be tested by providing an ambiguous description and verifying that the system asks for clarification and correctly incorporates the answer.
**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 a user submits an empty "Afraid to ask" field? (It should be ignored or validated as empty).
- How does the system handle multiple "Afraid to ask" ideas from the same user? (Each should be evaluated independently).
- What if an "Afraid to ask" idea complies with multiple "Want" or "Accept" ideas from different users? (It should still be treated as a "Want" and displayed).
- 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?
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST add a new input field labeled "Afraid to ask" to the response form, positioned directly below the "What you want" field.
- **FR-002**: System MUST store "Afraid to ask" ideas with maximum privacy, meaning they are only visible to the submitting user until they "comply" with another user's "Want" or "Accept" idea.
- **FR-003**: System MUST compare "Afraid to ask" ideas from one user with "Want" and "Accept" ideas from other users using semantic similarity (e.g., via an LLM to compare meaning).
- **FR-004**: If an "Afraid to ask" idea complies with any other user's "Want" or "Accept" idea, the system MUST treat and display it in the results as if it were a "Want" idea from the submitting user.
- **FR-005**: If an "Afraid to ask" idea does NOT comply with any other user's "Want" or "Accept" idea, the system MUST NOT display it in the public results.
- **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.
### Key Entities *(include if feature involves data)*
- **Idea**: Represents a user's input, can be "Want", "Accept", or "Afraid to ask".
* Attributes: `content` (text), `type` (enum: Want, Accept, AfraidToAsk), `userId`, `privacyStatus` (e.g., private, public).
- **User**: Represents an individual interacting with the system.
* Attributes: `id`, `name`.
- **ResponseForm**: The interface where users submit their ideas.
## Dependencies and Assumptions *(optional)*
- **Assumption**: The system has an existing mechanism for users to submit "Want" and "Accept" ideas.
- **Assumption**: The system has an existing mechanism to display results based on user ideas.
- **Assumption**: "Maximum privacy" for "Afraid to ask" ideas is achieved through ephemeral server-side storage, meaning data is encrypted, stored temporarily on the server, and purged on session termination, making it inaccessible via client-side developer tools.
- **Dependency**: An LLM or similar semantic comparison service is available for evaluating idea compliance.
## Clarifications
### Session 2025-10-13
- Q: What constitutes "complying with" when comparing "Afraid to ask" ideas with "Want" and "Accept" ideas? → A: Semantic similarity (e.g., using an LLM to compare meaning)
- Q: How is "maximum privacy" achieved for storing "Afraid to ask" ideas? → A: Only visible to the submitting user until it "complies"
- **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.
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: The "Afraid to ask" field is present and correctly positioned on the response form, as verified by UI inspection.
- **SC-002**: "Afraid to ask" ideas that comply with other users' desires are correctly displayed in the results as "Want" ideas, with 100% accuracy in testing scenarios.
- **SC-003**: "Afraid to ask" ideas that do not comply with other users' desires are not displayed in the public results, with 100% accuracy in testing scenarios.
- **SC-004**: The privacy requirements for "Afraid to ask" ideas are met, as confirmed by a security review.
- **SC-005**: Users can submit "Afraid to ask" ideas through the response form without encountering any system errors.
- **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%.