snowprint
54f427ea21
Some checks failed
Deploy to GitHub Pages / build-and-deploy (push) Has been cancelled
135 lines
8.3 KiB
Markdown
135 lines
8.3 KiB
Markdown
# Feature Specification: Geek Calculator
|
||
|
||
**Feature Branch**: `001-build-a-single`
|
||
**Created**: 2025-10-03
|
||
**Status**: Draft
|
||
**Input**: User description: "Build a single-file, offline-capable "Geek Calculator" that opens as index.html with no build step and no external CDN. User goals: - Perform basic arithmetic (+ − × ÷), parentheses, percentages, +/- toggle. - Power-user features: RPN mode toggle, keyboard-first operation, command palette (\"@\"), and history with re-run. - "Geek vibe" UI: dark terminal theme, monospace font, ASCII banner, blinking cursor in input, small Easter eggs. Constraints: - Pure HTML/CSS/JS, no frameworks, total payload < 50KB. - Works fully offline; no network requests. - A11y: full keyboard navigation, ARIA roles, high-contrast. Non-goals: - Scientific/trig functions, i18n for v1. Success metrics: - Lighthouse Perf/Best Practices/SEO/Accessibility ≥ 95 locally. - 100% keyboard coverage for primary flows. - Unit tests for core math + RPN stack."
|
||
|
||
## Execution Flow (main)
|
||
```
|
||
1. Parse user description from Input
|
||
→ If empty: ERROR "No feature description provided"
|
||
2. Extract key concepts from description
|
||
→ Identify: actors, actions, data, constraints
|
||
3. For each unclear aspect:
|
||
→ Mark with [NEEDS CLARIFICATION: specific question]
|
||
4. Fill User Scenarios & Testing section
|
||
→ If no clear user flow: ERROR "Cannot determine user scenarios"
|
||
5. Generate Functional Requirements
|
||
→ Each requirement must be testable
|
||
→ Mark ambiguous requirements
|
||
6. Identify Key Entities (if data involved)
|
||
7. Run Review Checklist
|
||
→ If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
|
||
→ If implementation details found: ERROR "Remove tech details"
|
||
8. Return: SUCCESS (spec ready for planning)
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ Quick Guidelines
|
||
- ✅ Focus on WHAT users need and WHY
|
||
- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
|
||
- 👥 Written for business stakeholders, not developers
|
||
|
||
### Section Requirements
|
||
- **Mandatory sections**: Must be completed for every feature
|
||
- **Optional sections**: Include only when relevant to the feature
|
||
- When a section doesn't apply, remove it entirely (don't leave as "N/A")
|
||
|
||
### For AI Generation
|
||
When creating this spec from a user prompt:
|
||
1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
|
||
2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
|
||
3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
|
||
4. **Common underspecified areas**:
|
||
- User types and permissions
|
||
- Data retention/deletion policies
|
||
- Performance targets and scale
|
||
- Error handling behaviors
|
||
- Integration requirements
|
||
- Security/compliance needs
|
||
|
||
---
|
||
|
||
## User Scenarios & Testing *(mandatory)*
|
||
|
||
### Primary User Story
|
||
As a user, I want to open the Geek Calculator and perform basic arithmetic operations (addition, subtraction, multiplication, division) with immediate results, so that I can quickly calculate mathematical expressions without needing an internet connection or installing additional software.
|
||
|
||
### Acceptance Scenarios
|
||
1. **Given** I am on the Geek Calculator page with a dark terminal-themed UI and monospace font, **When** I input a basic arithmetic expression like "5 + 3 * 2" using the keyboard, **Then** I see the correct result (11) displayed and formatted with the "geek vibe" aesthetic.
|
||
2. **Given** I want to perform calculations without a mouse, **When** I use keyboard shortcuts to enter numbers and operations, **Then** the calculator responds to my input and shows results instantly with keyboard-first navigation.
|
||
3. **Given** I have performed several calculations, **When** I access the history feature, **Then** I can see my previous calculations and re-run them to reproduce the same results.
|
||
4. **Given** I am a power user familiar with RPN calculators, **When** I toggle the RPN mode and use postfix notation for calculations, **Then** the calculator correctly processes expressions in RPN format rather than standard infix notation.
|
||
|
||
### Edge Cases
|
||
- What happens when I input an invalid expression like "5 // 0" or "5 + * 3"? [NEEDS CLARIFICATION: What error handling behavior is expected for invalid expressions?]
|
||
- How does the system handle very large numbers or calculations that result in overflow? [NEEDS CLARIFICATION: What is the expected behavior for calculations that exceed numerical limits?]
|
||
- What happens when the calculation history becomes very long - is there a limit or does it scroll? [NEEDS CLARIFICATION: Are there limits to calculation history storage?]
|
||
- How does the calculator handle the percentage operation in different contexts (e.g., "50% of 100" vs "100 + 50%")? [NEEDS CLARIFICATION: What are the specific percentage operation behaviors expected?]
|
||
- What happens if someone tries to use scientific functions (non-goal) - does it show an error or ignore? [NEEDS CLARIFICATION: How should the system respond to inputs that exceed the v1 scope?]
|
||
|
||
## Requirements *(mandatory)*
|
||
|
||
### Functional Requirements
|
||
- **FR-001**: System MUST perform basic arithmetic operations (+, -, ×, ÷) with correct order of operations precedence
|
||
- **FR-002**: System MUST support parentheses for expression grouping and control of evaluation order
|
||
- **FR-003**: Users MUST be able to use percentage operations in calculations
|
||
- **FR-004**: Users MUST be able to toggle the sign of numbers using a +/- feature
|
||
- **FR-005**: System MUST provide an RPN mode toggle that switches between standard and Reverse Polish Notation calculation methods
|
||
- **FR-006**: System MUST support keyboard-first operation with all functions accessible via keyboard shortcuts
|
||
- **FR-007**: System MUST provide a command palette feature accessible via the "@" key
|
||
- **FR-008**: System MUST maintain a calculation history that users can review and re-run
|
||
- **FR-009**: System MUST provide a "geek vibe" UI with dark terminal theme, monospace font, and ASCII banner
|
||
- **FR-010**: System MUST display a blinking cursor in the input field for terminal-like experience
|
||
- **FR-011**: System MUST include small Easter eggs for enhanced user experience
|
||
- **FR-012**: System MUST work fully offline with no network requests required
|
||
- **FR-013**: System MUST store calculation history locally for offline access
|
||
- **FR-014**: System MUST provide full keyboard navigation for accessibility compliance
|
||
- **FR-015**: System MUST implement ARIA roles for accessibility compliance
|
||
- **FR-016**: System MUST support high-contrast mode for accessibility
|
||
- **FR-017**: System MUST maintain total payload under 50KB
|
||
- **FR-018**: System MUST provide unit tests for core math operations
|
||
- **FR-019**: System MUST provide unit tests for RPN stack operations
|
||
|
||
### Key Entities
|
||
- **Calculation Expression**: Represents the mathematical expression being entered or evaluated, including operands, operators, and parentheses grouping
|
||
- **Calculation Result**: The numerical result of a completed calculation, with formatting that matches the "geek vibe" aesthetic
|
||
- **RPN Stack**: A data structure used in Reverse Polish Notation mode to manage operands during calculations
|
||
- **Calculation History Entry**: A record of previous calculations, including the expression, result, and timestamp, that can be recalled and re-executed
|
||
- **Application Settings**: Configuration options for the calculator including theme preferences, RPN vs standard mode, keyboard shortcuts, and accessibility settings
|
||
- **User Input**: The current expression being entered by the user, which may be in progress or ready for evaluation
|
||
|
||
---
|
||
|
||
## Review & Acceptance Checklist
|
||
*GATE: Automated checks run during main() execution*
|
||
|
||
### Content Quality
|
||
- [ ] No implementation details (languages, frameworks, APIs)
|
||
- [x] Focused on user value and business needs
|
||
- [x] Written for non-technical stakeholders
|
||
- [x] All mandatory sections completed
|
||
|
||
### Requirement Completeness
|
||
- [ ] No [NEEDS CLARIFICATION] markers remain
|
||
- [x] Requirements are testable and unambiguous
|
||
- [x] Success criteria are measurable
|
||
- [x] Scope is clearly bounded
|
||
- [x] Dependencies and assumptions identified
|
||
|
||
---
|
||
|
||
## Execution Status
|
||
*Updated by main() during processing*
|
||
|
||
- [x] User description parsed
|
||
- [x] Key concepts extracted
|
||
- [x] Ambiguities marked
|
||
- [x] User scenarios defined
|
||
- [x] Requirements generated
|
||
- [x] Entities identified
|
||
- [ ] Review checklist passed
|
||
|
||
--- |