rust-tutor/MANUAL.md

# How to Use Your Rust Learning System

## Quick Start (First Time)

1. **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!*