Lesson 01 | Overall Idea & Act 1: Getting Started — GSD Practical Tutorial: Building a Calculator from Scratch

A practical tutorial for beginners. No pure theory—just follow along and build it.

Overall Idea

This tutorial follows a real development process. Every episode solves a real problem and introduces a real concept.

14 Episodes, each with clear deliverables
Storyline: From an idea → 1529 lines of code → A working calculator
Code Volume: 3 files (HTML 57 lines / CSS 535 lines / JS 937 lines) + 1631 lines of tests
Rhythm: Build → Encounter issues → Learn concepts → Continue building

From "I want to build a calculator" to "starting to write code"

Scene: You open your computer with one thought—"Build a calculator that elderly people can use."

Specific idea: Elderly mode + Standard mode, pure frontend, works offline
Start with one command: /gsd-new-project
What GSD did: Asked a few key questions and turned a vague idea into a structured project
What we got: .planning/ directory, PROJECT.md, 34 requirements, 4-phase roadmap
Core concept: AI-assisted development isn't "write code for me", it's "help me think clearly"

Output Files:

.planning/PROJECT.md — Project definition (core value, constraints, target users)
.planning/REQUIREMENTS.md — 34 requirements (CALC/DISP/INPT/ELDR/STND/MODE/HIST/A11Y/RESP)
.planning/ROADMAP.md — 4-Phase roadmap
.planning/STATE.md — Project state
CLAUDE.md — Project constraints file (GSD workflow rules are written here)

Command: /gsd-new-project --auto

Scene: GSD automatically ran a round of research and found issues I hadn't thought of.

Floating-point precision: 0.1 + 0.2 = 0.30000000000000004, what's going on?
WCAG AAA: Elderly mode needs a 7:1 contrast ratio, how do we test that?
How big should buttons be: Where did 80px come from? (Elderly finger touch research)
How research becomes requirements: You only write down what you know; what you don't know gets missed
When can we use --skip-research?
Core concept: Researching before building is much more reliable than guessing

Output Files:

.planning/research/domain-research.md — Domain research (accessibility standards, elderly user habits)
.planning/research/stack-research.md — Tech stack research (floating-point precision solutions, CSS variables)
.planning/research/SUMMARY.md — Comprehensive research summary

Command: Built into /gsd-new-project (triggers automatically)

Scene: Before starting Phase 1, lock down key decisions. Once frozen, downstream tasks won't ask again.

Why not use eval()? (Security + control — CALC-08 security requirement)
What is the Shunting-yard algorithm? (In plain English: queuing up an expression to calculate by priority)
What about floating-point precision? (Multiply by 10^10 to calculate as integers, then divide back)
How do we store history? (Max 10 entries, FIFO, localStorage)
How do we record discussions: Traces in DISCUSSION-LOG.md
Core concept: Discuss first, then code; freeze decisions in CONTEXT.md

Output Files:

.planning/phases/01/CONTEXT.md — Frozen design decisions (engine architecture, precision scheme, history strategy)
.planning/phases/01/DISCUSSION-LOG.md — Discussion process

Command: /gsd-discuss-phase 1