specs/005-tui-issue-creation/spec.md
Ref: Size: 6.7 KiB
# Feature Specification: TUI Issue Creation
**Feature Branch**: `005-tui-issue-creation`
**Created**: 2026-03-21
**Status**: Draft
**Input**: User description: "Allow creation of issue from dashboard. Add the ability to create a new issue directly from the TUI dashboard without leaving the interface. The user presses a key to open a minimal issue creation form where they can enter a title and optional body. On submit, the issue is created. On cancel (Escape), the form is dismissed. The new issue should appear in the list after creation."
## User Scenarios & Testing *(mandatory)*
### User Story 1 - Create Issue with Title (Priority: P1)
A user browsing the dashboard notices something that needs tracking. They press `n` to open an inline issue creation form. A text input appears where they type the issue title. They press Enter to submit, and the issue is created and immediately visible in the issue list.
**Why this priority**: Creating an issue with a title is the minimum viable interaction — without this, the feature has no value.
**Independent Test**: Can be fully tested by pressing `n`, typing a title, pressing Enter, and verifying the new issue appears in the list.
**Acceptance Scenarios**:
1. **Given** the dashboard is showing the Issues tab, **When** the user presses `n`, **Then** an input form appears at the bottom of the screen prompting for a title.
2. **Given** the title input is active, **When** the user types text and presses Enter, **Then** a new issue is created with that title and an empty body.
3. **Given** the issue was just created, **When** the dashboard refreshes, **Then** the new issue appears in the issue list.
4. **Given** the title input is active, **When** the user presses Escape, **Then** the form is dismissed without creating an issue.
5. **Given** the title input is active, **When** the user presses Enter with an empty title, **Then** the form is dismissed without creating an issue (empty titles are not allowed).
---
### User Story 2 - Create Issue with Title and Body (Priority: P2)
After entering a title, the user can optionally add a body/description to provide more context. After submitting the title, the form transitions to a body input. The user can type the body and press Enter to submit, or press Escape to skip the body and create the issue with title only.
**Why this priority**: A body provides valuable context but is optional — the feature works without it.
**Independent Test**: Can be tested by pressing `n`, entering a title, pressing Enter, then entering a body and pressing Enter again, and verifying the issue has both title and body.
**Acceptance Scenarios**:
1. **Given** the user has entered a title and pressed Enter, **When** the form transitions to body input, **Then** a prompt for the body text appears.
2. **Given** the body input is active, **When** the user types text and presses Enter, **Then** the issue is created with both the title and body.
3. **Given** the body input is active, **When** the user presses Escape, **Then** the issue is created with the title only and an empty body.
---
### User Story 3 - Status Feedback During Creation (Priority: P3)
The user sees clear feedback during the creation process: the current step (title/body), a confirmation message after successful creation, or an error message if something goes wrong.
**Why this priority**: Feedback completes the user experience but the feature works without it.
**Independent Test**: Can be tested by creating an issue and verifying a success message appears in the status bar.
**Acceptance Scenarios**:
1. **Given** the creation form is active, **When** the user looks at the footer, **Then** it shows which field is being edited (e.g., "New issue - Title:" or "New issue - Body:").
2. **Given** an issue was successfully created, **When** the form closes, **Then** a confirmation message appears in the status bar (e.g., "Issue created: {short-id}").
3. **Given** issue creation fails, **When** the error occurs, **Then** an error message appears in the status bar.
---
### Edge Cases
- What happens when the user presses `n` while on the Patches tab? The dashboard switches to the Issues tab before showing the form, since issues are created on the Issues tab.
- What happens when the user presses `n` while in search mode? The `n` keypress is treated as a search character, not an issue creation trigger (search mode intercepts all keys).
- What happens if the title contains only whitespace? It is treated as empty and the form is dismissed without creating an issue.
- What happens if the user presses Backspace during title/body input? The last character is removed from the current input field.
## Requirements *(mandatory)*
### Functional Requirements
- **FR-001**: System MUST provide an issue creation mode activated by the `n` key from the Issues tab.
- **FR-002**: System MUST display a title input field when creation mode is activated.
- **FR-003**: System MUST create a new issue when the user submits a non-empty title by pressing Enter.
- **FR-004**: System MUST dismiss the creation form without side effects when the user presses Escape.
- **FR-005**: System MUST refresh the issue list after successful issue creation so the new issue is immediately visible.
- **FR-006**: System MUST optionally prompt for a body after the title is submitted.
- **FR-007**: System MUST support Backspace to delete characters from the current input field.
- **FR-008**: System MUST reject empty or whitespace-only titles (no issue is created).
- **FR-009**: System MUST display a confirmation message in the status bar after successful creation.
- **FR-010**: System MUST display an error message in the status bar if issue creation fails.
### Key Entities
- **Issue Creation Form**: A temporary input state with two sequential fields (title, body) that captures user input and delegates to the existing issue creation logic.
## Success Criteria *(mandatory)*
### Measurable Outcomes
- **SC-001**: Users can create a new issue from the dashboard in under 10 seconds without leaving the TUI.
- **SC-002**: The newly created issue appears in the list immediately after creation with no manual refresh needed.
- **SC-003**: Cancelling at any point during creation leaves the dashboard in its original state with no side effects.
- **SC-004**: All existing keyboard shortcuts continue to function when the creation form is not active (no regressions).
## Assumptions
- The `n` key is not currently bound to any action in the TUI and is available for issue creation.
- Issue creation uses the existing programmatic interface (not shell-out to the CLI binary).
- The body input is a single line; multi-line body editing is out of scope.
- The creation form appears in the footer area, replacing the status bar temporarily.