Improve study path and foundations capstone guidance

Author: lucasbellesi

STUDY_PLAN.md

@@ -2,56 +2,112 @@
 
 This plan assumes 5 study days per week, 60-90 minutes per day.
 
-## Week 1 - Foundations I
+## How To Use This Plan
 
-- Complete `01-foundations/types-and-io`
-- Complete `01-foundations/operators-and-expressions`
-- Complete `01-foundations/control-flow`
-- Complete `01-foundations/functions`
+1. Follow modules in order.
+2. For each module: read `README.md`, run `example/main.cpp`, solve `exercises/01.cpp` and `exercises/02.cpp`.
+3. Mark progress in `languages/cpp/CHECKLIST.md`.
+4. Use level capstones to combine concepts.
 
-Deliverables:
+## Week 1 - Foundations Basics
 
-- All exercises solved for these modules.
-- Notes on at least 3 common input/control-flow mistakes.
+Modules:
 
-## Week 2 - Foundations II + First Capstone
+- `languages/cpp/01-foundations/types-and-io`
+- `languages/cpp/01-foundations/operators-and-expressions`
+- `languages/cpp/01-foundations/control-flow`
+- `languages/cpp/01-foundations/functions`
 
-- Complete `01-foundations/arrays-and-vectors`
-- Complete `01-foundations/strings`
-- Complete `01-foundations/scope-and-lifetime-basics`
-- Complete `01-foundations/formatted-output-and-iomanip`
-- Build `languages/cpp/projects/01-foundations`
+Suggested pacing:
 
-Deliverables:
+- Day 1: types-and-io
+- Day 2: operators-and-expressions
+- Day 3: control-flow
+- Day 4: functions
+- Day 5: exercise review + error fixes
 
-- All exercises solved.
-- Foundations capstone runs from VS Code task flow.
+Done when:
 
-## Week 3 - Core + Core Capstone
+- [ ] All 8 exercises from Week 1 are solved.
+- [ ] You can explain when to use `getline` versus `cin >>`.
+- [ ] You can write and call functions with clear parameters and return values.
 
-- Complete all modules in `02-core`
-- Build `languages/cpp/projects/02-core`
+## Week 2 - Foundations Collections + Capstone
 
-Deliverables:
+Modules:
 
-- Core exercises solved.
-- Core capstone parses file input and writes output report.
+- `languages/cpp/01-foundations/arrays-and-vectors`
+- `languages/cpp/01-foundations/strings`
+- `languages/cpp/01-foundations/scope-and-lifetime-basics`
+- `languages/cpp/01-foundations/formatted-output-and-iomanip`
+
+Capstone:
+
+- `languages/cpp/projects/01-foundations`
+
+Suggested pacing:
+
+- Day 1-4: one module per day
+- Day 5: complete the foundations capstone and extensions
+
+Done when:
+
+- [ ] All Week 2 exercises are solved.
+- [ ] Capstone builds and runs from terminal and VS Code.
+- [ ] You can process lists of values and print formatted reports.
+
+## Week 3 - Core Level + Capstone
+
+Modules:
+
+- `languages/cpp/02-core/input-validation`
+- `languages/cpp/02-core/algorithms-basics`
+- `languages/cpp/02-core/file-io-basics`
+- `languages/cpp/02-core/sorting-and-searching`
+- `languages/cpp/02-core/maps-and-frequency-counting`
+- `languages/cpp/02-core/error-handling-and-defensive-programming`
+
+Capstone:
+
+- `languages/cpp/projects/02-core`
+
+Suggested pacing:
+
+- Day 1-4: first four modules
+- Day 5: remaining modules + capstone start
+
+Done when:
+
+- [ ] You can validate user/file input safely.
+- [ ] You can sort/search data and build frequency summaries.
+- [ ] Core capstone generates the expected output report.
 
 ## Week 4 - Advanced + Expert Essentials
 
-- Complete all modules in `03-advanced`
-- Complete `04-expert/memory-management-and-raii`
-- Complete `04-expert/smart-pointers-in-depth`
-- Build `languages/cpp/projects/03-advanced` and `languages/cpp/projects/04-expert`
+Modules:
+
+- `languages/cpp/03-advanced/structs-and-classes`
+- `languages/cpp/03-advanced/constructors-and-invariants`
+- `languages/cpp/03-advanced/copy-and-move-semantics`
+- `languages/cpp/03-advanced/inheritance-and-polymorphism`
+- `languages/cpp/03-advanced/templates-basics`
+- `languages/cpp/04-expert/memory-management-and-raii`
+- `languages/cpp/04-expert/smart-pointers-in-depth`
+
+Capstones:
+
+- `languages/cpp/projects/03-advanced`
+- `languages/cpp/projects/04-expert`
 
-Deliverables:
+Done when:
 
-- Advanced/expert exercises solved.
-- Clear written explanation of ownership and thread safety basics.
+- [ ] You can design classes with clear invariants.
+- [ ] You can explain ownership (`unique_ptr`, `shared_ptr`, `weak_ptr`).
+- [ ] You can complete both advanced/expert capstones and explain tradeoffs.
 
 ## Weekly Review Checklist
 
-- [ ] I can run every module example from terminal and VS Code.
-- [ ] I can explain why each exercise solution works.
-- [ ] I documented at least 2 bugs/mistakes I fixed this week.
+- [ ] I can run module examples from terminal and VS Code.
+- [ ] I can explain why each exercise solution is correct.
+- [ ] I documented at least 2 mistakes and how I fixed them.
 - [ ] I updated `languages/cpp/CHECKLIST.md`.

languages/cpp/MODULE_README_STYLE.md

@@ -0,0 +1,33 @@
+# C++ Module README Style
+
+Use this structure for every concept module under:
+
+- `01-foundations`
+- `02-core`
+- `03-advanced`
+- `04-expert`
+
+## Required Sections
+
+1. `## Quick Run`
+2. `## Topics Covered`
+3. `## Common Pitfalls`
+4. `## Exercise Focus`
+5. `### Exercise Specs`
+6. `## Checkpoint`
+
+## Section Rules
+
+- `Quick Run`: include compile + run commands for `example/main.cpp`.
+- `Topics Covered`: short bullets of key concepts only.
+- `Common Pitfalls`: practical mistakes beginners actually make.
+- `Exercise Focus`: one bullet per exercise with task summary.
+- `Exercise Specs`: for each exercise define input, output, and at least 2 edge cases.
+- `Checkpoint`: 3-5 measurable learning outcomes as checkboxes.
+
+## Writing Guidelines
+
+- Keep explanations short and practical.
+- Prefer concrete examples over theory-heavy text.
+- Use the same naming style as folder names (kebab-case paths).
+- Keep all content in English.

languages/cpp/README.md

@@ -11,6 +11,8 @@ This track teaches C++ through small, runnable programs and focused exercises.
 5. [04-expert](./04-expert/README.md)
 
 Use progress tracking: [CHECKLIST.md](./CHECKLIST.md)
+  
+Module README format reference: [MODULE_README_STYLE.md](./MODULE_README_STYLE.md)
 
 ## Modules By Level
 

languages/cpp/projects/01-foundations/README.md

@@ -4,13 +4,28 @@
 
 Build a console program that reads student names and scores, then prints summary statistics.
 
+## Quick Run
+
+```bash
+g++ -std=c++17 -Wall -Wextra -pedantic main.cpp -o foundations_capstone
+./foundations_capstone
+```
+
 ## Requirements
 
 - Ask for number of students.
 - Read each student name with `getline` and score with numeric validation.
+- Keep score input in the range `0` to `100`.
 - Print all student records.
 - Print minimum score, maximum score, and average score.
 
+## Concepts Practiced
+
+- Input handling with `cin` and `getline`.
+- Loops and conditionals.
+- `vector` for dynamic storage.
+- Basic statistics: min, max, average.
+
 ## Sample Input
 
 ```text
@@ -35,7 +50,14 @@ Minimum: 77
 Maximum: 91
 ```
 
+## Common Pitfalls
+
+- Forgetting to clear the newline after reading numeric input.
+- Accepting invalid scores without retrying.
+- Dividing by zero when no students are provided.
+
 ## Extension Ideas
 
 - Add grade letters (A/B/C).
 - Sort output by score.
+- Print pass/fail counts using a threshold.

languages/cpp/projects/01-foundations/main.cpp

@@ -8,17 +8,50 @@ struct Student {
     int score;
 };
 
-int main() {
+int readPositiveCount() {
     int count = 0;
-    std::cout << "How many students? ";
-    std::cin >> count;
+    while (true) {
+        std::cout << "How many students? ";
+        if (!(std::cin >> count)) {
+            std::cout << "Invalid number. Try again.\n";
+            std::cin.clear();
+            std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+            continue;
+        }
+        if (count <= 0) {
+            std::cout << "Please enter a positive number.\n";
+            std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+            continue;
+        }
 
-    if (count <= 0) {
-        std::cout << "Please enter a positive number.\n";
-        return 0;
+        std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+        return count;
     }
+}
 
-    std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+int readScore(const std::string& studentName) {
+    int score = 0;
+    while (true) {
+        std::cout << "Score for " << studentName << " (0-100): ";
+        if (!(std::cin >> score)) {
+            std::cout << "Invalid score. Enter a number from 0 to 100.\n";
+            std::cin.clear();
+            std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+            continue;
+        }
+        if (score < 0 || score > 100) {
+            std::cout << "Score out of range. Enter a value from 0 to 100.\n";
+            std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+            continue;
+        }
+
+        std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+        return score;
+    }
+}
+
+int main() {
+    const int count = readPositiveCount();
 
     std::vector<Student> students;
     students.reserve(static_cast<std::size_t>(count));
@@ -27,10 +60,7 @@ int main() {
         Student student;
         std::cout << "Student name " << (i + 1) << ": ";
         std::getline(std::cin, student.name);
-
-        std::cout << "Score for " << student.name << " (0-100): ";
-        std::cin >> student.score;
-        std::cin.ignore(std::numeric_limits<std::streamsize>::max(), '\n');
+        student.score = readScore(student.name);
 
         students.push_back(student);
     }

templates/concept-template/README.md

@@ -1,6 +1,7 @@
 # Concept Template
 
 Use this template when creating a new concept module.
+For the C++ track, also follow `languages/cpp/MODULE_README_STYLE.md`.
 
 ## Quick Run