geek-calc/specs/001-build-a-single/spec.md

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)
• Focused on user value and business needs
• Written for non-technical stakeholders
• All mandatory sections completed

Requirement Completeness

• No [NEEDS CLARIFICATION] markers remain
• Requirements are testable and unambiguous
• Success criteria are measurable
• Scope is clearly bounded
• Dependencies and assumptions identified

---

Execution Status

Updated by main() during processing

• User description parsed
• Key concepts extracted
• Ambiguities marked
• User scenarios defined
• Requirements generated
• Entities identified
• Review checklist passed

---