PRD Example 6: Flashcard Quiz CLI

Difficulty: Beginner | Project Type: CLI Tool | Time: 2-3 hours

---

Overview

What	A command-line flashcard app for studying with spaced repetition
Who	Students preparing for exams or learning new topics
Why	Enables quick study sessions directly in the terminal without distractions

---

Core Features (MVP)

1. Add Card: flash add "What is Python?" "A programming language" → Creates a flashcard
2. Study Mode: flash study → Shows cards one by one, user marks correct/incorrect
3. List Cards: flash list → Shows all cards with their success rates
4. Delete Card: flash delete 3 → Removes card by ID

---

Non-Goals

Will NOT build:

• Deck organization or categories
• Spaced repetition algorithm (simple random order only)
• Import/export from Anki or other formats
• Rich text or markdown in cards
• Images or media attachments
• Timed quizzes
• Multi-user or sharing features
• Statistics beyond simple success rate

Will NOT use:

• External APIs
• Database (use JSON file)
• Web interface
• Third-party flashcard libraries

---

Technical Constraints

Language	Python 3.11+
Framework	None (stdlib only)
Dependencies	None — stdlib only
Data Storage	JSON file at ~/.flashcards/cards.json
Testing	pytest, minimum 4 tests
Code Style	Black formatter, type hints

---

Success Criteria

• [ ] flash add creates cards with unique IDs
• [ ] flash study presents cards randomly, tracks correct/incorrect
• [ ] flash list shows all cards with success percentage
• [ ] flash delete removes cards by ID
• [ ] Data persists between sessions
• [ ] All tests pass

---

Implementation Phases

Phase 1: Data Model & Add Command

Goal: Set up card storage and creation

Tasks:

1. Create project structure with flash.py
2. Define card schema: \{id, question, answer, correct, attempts\}
3. Implement add command
4. Create JSON file in ~/.flashcards/ if not exists

Verification:

python flash.py add "Capital of France?" "Paris"
# Output: "Card #1 added!"

cat ~/.flashcards/cards.json
# Shows: {"cards": [{"id": 1, "question": "Capital of France?", ...}]}

Deliverables: flash.py with add functionality

---

Phase 2: Study Mode

Goal: Interactive study session

Tasks:

1. Implement study command that shows cards one at a time
2. User presses Enter to reveal answer
3. User types y (correct) or n (incorrect)
4. Update success/attempt counters in JSON

Verification:

python flash.py study
# Shows: "Question: Capital of France?"
# User presses Enter
# Shows: "Answer: Paris"
# Shows: "Correct? (y/n): "
# User types: y
# Shows: "Correct! Next card..."
# After all cards: "Session complete! 4/5 correct (80%)"

Deliverables: Working study mode

---

Phase 3: List, Delete & Testing

Goal: Complete CRUD and add tests

Tasks:

1. Implement list command showing all cards with stats
2. Implement delete command by card ID
3. Write pytest tests for all commands
4. Handle edge cases (empty deck, invalid ID)

Verification:

python flash.py list
# Shows:
# #1 "Capital of France?" → Paris (80% correct, 5 attempts)
# #2 "What is 2+2?" → 4 (100% correct, 3 attempts)

python flash.py delete 1
# Output: "Card #1 deleted"

pytest
# All tests pass

Deliverables: Complete CLI with tests

---

Agent Rules

Always	Ask First	Never
Validate card ID exists before delete	Before changing JSON schema	Use external packages
Handle empty deck gracefully	Before adding new commands	Store data outside ~/.flashcards/
Show helpful prompts during study	Before changing study flow	Add deck/category features
Preserve card stats on update		Delete all cards without confirmation