scaffolding

MANUAL.md

@@ -0,0 +1,224 @@
+# How to Use Your Rust Learning System
+
+## Quick Start (First Time)
+
+1. **Initialize Git (if not done)**
+   ```bash
+   cd /Users/real/Lab/now/rust/rust-tutor
+   git init
+   git add .
+   git commit -m "Initial learning scaffolding setup"
+   ```
+
+2. **Start Your First Exercise**
+   - Open `NEW_CHAT_TEMPLATE.md`
+   - Copy the template
+   - Start new Claude Code chat
+   - Paste template and request your first exercise
+
+## Daily Workflow
+
+### 🎯 Getting a New Exercise
+
+1. **Open new Claude Code chat**
+2. **Copy/paste from NEW_CHAT_TEMPLATE.md:**
+   ```
+   /model opusplan
+
+   I'm continuing my Rust learning journey. Please read CLAUDE.md for your instructions, then check CURRENT_STATE.md and help with:
+
+   [X] Exercise delivery - Give me the next exercise
+   ```
+3. **Claude will:**
+   - Read your current state
+   - Give you the next appropriate exercise
+   - Update CURRENT_STATE.md when done
+4. **Close the exercise chat** (it's served its purpose)
+
+### 💻 Working on Exercise
+
+1. **Create exercise branch:**
+   ```bash
+   git checkout -b exercise/07-01-notes-cli
+   ```
+
+2. **Create exercise directory:**
+   ```bash
+   mkdir -p exercises/07-01-notes-cli
+   cd exercises/07-01-notes-cli
+   cargo init
+   ```
+
+3. **Work and commit frequently:**
+   ```bash
+   # Every 15-30 minutes or when something works
+   git add .
+   git commit -m "[Exercise 1] Add basic note struct"
+   git commit -m "[Exercise 1] Implement add_note functionality"
+   git commit -m "[Exercise 1] Add CLI argument parsing"
+   ```
+
+4. **Create reflection when done:**
+   ```bash
+   # In exercises/07-01-notes-cli/
+   echo "# Reflection\n\n## What I learned\n- ...\n\n## What was hard\n- ...\n\n## Aha moments\n- ..." > REFLECTION.md
+   ```
+
+### 📝 Getting Code Review
+
+1. **Commit your final version:**
+   ```bash
+   git add .
+   git commit -m "[Exercise 1] Complete notes CLI - ready for review"
+   ```
+
+2. **Open new Claude Code chat for review**
+3. **Copy/paste from NEW_CHAT_TEMPLATE.md:**
+   ```
+   /model opusplan
+
+   I'm continuing my Rust learning journey. Please read CLAUDE.md for your instructions, then check CURRENT_STATE.md and help with:
+
+   [X] Code review - Review my completed exercise code
+   ```
+
+4. **Tell Claude:**
+   ```
+   Please review my exercise in exercises/07-01-notes-cli/
+   Focus on: correctness, Rust idioms, ownership/borrowing
+   ```
+
+5. **Iterate based on feedback:**
+   ```bash
+   # Make changes based on review
+   git add .
+   git commit -m "[Exercise 1] Fix: Use &str instead of String in function params"
+   ```
+
+6. **Close review chat when satisfied**
+
+### ✅ Completing Exercise
+
+1. **Merge to main:**
+   ```bash
+   git checkout main
+   git merge exercise/07-01-notes-cli
+   git branch -d exercise/07-01-notes-cli
+   ```
+
+2. **Update progress manually:**
+   - Edit PROGRESS.md to mark exercise complete
+   - Edit CURRENT_STATE.md if needed
+
+3. **Tag milestones (optional):**
+   ```bash
+   # After completing all 3 exercises in a milestone
+   git tag v07-modules-complete
+   ```
+
+## File Structure During Exercise
+
+```
+exercises/07-01-notes-cli/
+├── src/
+│   ├── main.rs
+│   └── lib.rs
+├── Cargo.toml
+├── README.md (exercise description)
+└── REFLECTION.md (your learnings)
+```
+
+## When to Create New Chats
+
+### ✅ Create New Chat For:
+- **Getting next exercise** (1 chat = 1 exercise delivery)
+- **Code review** (1 chat = review + iterations)
+- **Stuck/planning help** (when you need guidance)
+
+### ❌ Don't Create New Chat For:
+- Quick Rust syntax questions (use docs/book)
+- Continuing work on same exercise
+- Just checking current state (read CURRENT_STATE.md)
+
+## Git Commit Guidelines
+
+### ✅ Good Commit Messages:
+```bash
+"[Exercise 1] Add basic note struct with title and content"
+"[Exercise 1] Implement CLI parsing with clap"
+"[Exercise 1] Fix: Handle empty input gracefully"
+"[Exercise 1] Refactor: Extract validation to separate module"
+"[Exercise 1] Complete - ready for review"
+```
+
+### ❌ Avoid:
+```bash
+"work in progress"
+"fix stuff"
+"update"
+```
+
+### 🔄 Commit Frequency:
+- Every 15-30 minutes when coding
+- When you get something working
+- Before switching approaches
+- Before asking for help
+- When ready for review
+
+## File Maintenance
+
+### Files You Update:
+- **PROGRESS.md** - Mark exercises complete, add reflections
+- **CURRENT_STATE.md** - Update if your learning state changes significantly
+
+### Files Claude Updates:
+- **CURRENT_STATE.md** - After delivering exercises
+- **PROGRESS.md** - Sometimes adds context after milestones
+
+### Files You Never Touch:
+- **CLAUDE.md** - Master instructions (unless system needs changes)
+- **EXERCISES.md** - Exercise templates and tracking
+
+## Troubleshooting
+
+### "Claude can't read CLAUDE.md"
+- Use backup in NEW_CHAT_TEMPLATE.md
+- Copy/paste CLAUDE.md contents directly
+
+### "I'm lost on where I am"
+- Read CURRENT_STATE.md
+- Read your latest commits: `git log --oneline -5`
+- Check your current branch: `git branch`
+
+### "Exercise feels too hard"
+- Open planning chat
+- Ask for easier version or more hints
+- Remember: struggle 10-15min, then ask for help
+
+### "I forgot concepts from previous exercises"
+- Normal! Spaced repetition will help
+- Quickly review old exercise code
+- Future exercises will reinforce concepts
+
+## Success Patterns
+
+### 🎯 Aim For:
+- 1-2 exercises per week
+- Regular commits (not just at the end)
+- Reflecting on learnings in REFLECTION.md
+- Moving forward even when code isn't perfect
+
+### 🚀 You're On Track If:
+- Exercises take 1-3 hours each
+- You can explain your code choices
+- Compiler errors don't frustrate you as much
+- You're building things related to crypto/blockchain
+
+### 🔄 Course Correct If:
+- Exercises take more than 4 hours
+- You're copying code without understanding
+- You're stuck on same concept for weeks
+- You stop committing regularly
+
+---
+*This system is designed to get you shipping code. Trust the process!*