Refactor module examples and add education quality audit

Author: lucasbellesi

CONTRIBUTING.md

@@ -60,11 +60,18 @@ Run language lint checks with:
 - `./scripts/lint.ps1` (PowerShell)
 - `bash ./scripts/lint.sh` (Bash)
 
+Run the non-blocking education quality audit with:
+
+- `./scripts/audit-education-quality.ps1` (PowerShell)
+- `bash ./scripts/audit-education-quality.sh` (Bash)
+
 These smoke checks also compile standalone C# exercises by generating temporary validation projects during the check.
 TypeScript checks restore Node dependencies from `package-lock.json`, compile with `tsc`, and execute the emitted JavaScript with `node`.
 
 The public PowerShell and Bash scripts are thin wrappers over the shared Python automation core in `scripts/automation.py`. Curriculum validation and smoke target metadata live in `scripts/automation_manifest.json`.
 
+Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) when reviewing `example/main.*` files for teaching clarity and parity.
+
 4. Update related README files when behavior or structure changes.
 5. Open a pull request with a clear description of what changed and why.
 

EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md

@@ -0,0 +1,47 @@
+# Educational Example Review Rubric
+
+Use this rubric when reviewing module entry examples under `languages/*/*/*/example/main.*`.
+
+## Purpose
+
+Keep examples easy to learn from while preserving technical correctness and cross-language parity.
+
+## Review Checklist
+
+- The file starts with a module-specific header comment that states the concept and why it matters.
+- Comments are intent-first and appear before non-trivial logic blocks (validation, transformation, branching, output checks).
+- The example follows one deterministic scenario so learners can rerun and compare outcomes.
+- Output is explained in comments so learners can connect printed values to the code path.
+- Language-specific adaptation notes are present only when concept mapping differs from C++ semantics.
+- Naming and flow emphasize readability over cleverness.
+- The example still matches the module topic and does not drift into unrelated concepts.
+
+## Suggested Scoring
+
+Score each category from 0 to 2.
+
+- `Concept Framing`: clear concept + why it matters.
+- `Narration Quality`: comments guide reasoning, not syntax.
+- `Scenario Determinism`: same inputs lead to predictable learning output.
+- `Output Explainability`: printed values are explained and verifiable.
+- `Parity Discipline`: cross-language concept intent is preserved.
+
+Interpretation:
+
+- `9-10`: ready
+- `7-8`: acceptable with minor polish
+- `5-6`: needs focused revision
+- `<5`: rewrite required before merge
+
+## Tooling Support
+
+Run the non-blocking audit report:
+
+```bash
+python scripts/automation.py audit-education-quality
+```
+
+Generated reports:
+
+- `build/reports/education-quality-report.md`
+- `build/reports/education-quality-report.json`

README.md

@@ -155,6 +155,7 @@ Run checks locally:
 ./scripts/check-readme-structure.ps1
 ./scripts/check-module-completeness.ps1
 ./scripts/check-checkpoint-completeness.ps1
+./scripts/audit-education-quality.ps1
 ./scripts/lint.ps1
 ./scripts/smoke-languages.ps1
 ./scripts/build-all.ps1
@@ -166,6 +167,7 @@ bash ./scripts/check-links.sh
 bash ./scripts/check-readme-structure.sh
 bash ./scripts/check-module-completeness.sh
 bash ./scripts/check-checkpoint-completeness.sh
+bash ./scripts/audit-education-quality.sh
 bash ./scripts/lint.sh
 bash ./scripts/smoke-languages.sh
 bash ./scripts/build-all.sh
@@ -178,6 +180,8 @@ The public PowerShell and Bash scripts remain the supported entrypoints, but the
 
 The multi-language smoke scripts also compile standalone C# exercises by generating temporary validation projects during the check and compile TypeScript programs before executing their smoke targets.
 
+Use [EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md](EDUCATIONAL_EXAMPLE_REVIEW_RUBRIC.md) to keep entry examples pedagogically consistent during reviews. The education audit command is advisory and writes markdown/json findings without failing CI.
+
 Documentation sync also validates that [CONCEPT_INDEX.md](CONCEPT_INDEX.md) covers every implemented module and checkpoint path listed in the automation manifest.
 
 ## Contributing

languages/cpp/01-foundations/arrays-and-vectors/example/main.cpp

@@ -1,17 +1,17 @@
-// This example shows storing related values in ordered collections and iterating safely.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: Storing related values in ordered collections and iterating safely.
+// Why it matters: practicing arrays and vectors patterns makes exercises and checkpoints easier to
+// reason about.
 
 #include <iostream>
 #include <vector>
 using namespace std;
 
-// Run one deterministic scenario so the console output makes storing related values in ordered
-// collections and iterating safely easy to verify.
+// Walk through one fixed scenario so arrays and vectors behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Prepare sample inputs that exercise the key arrays and vectors path.
     const int fixedScores[3] = {72, 88, 95};
 
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Report values so learners can verify the arrays and vectors outcome.
     cout << "Fixed array values: ";
     for (int i = 0; i < 3; ++i) {
         cout << fixedScores[i];

languages/cpp/01-foundations/control-flow/example/main.cpp

@@ -1,15 +1,15 @@
-// This example shows choosing between branches and repeating work with predictable control flow.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: Choosing between branches and repeating work with predictable control flow.
+// Why it matters: practicing control flow patterns makes exercises and checkpoints easier to reason
+// about.
 
 #include <iostream>
 using namespace std;
 
-// Run one deterministic scenario so the console output makes choosing between branches and
-// repeating work with predictable control flow easy to verify.
+// Walk through one fixed scenario so control flow behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Prepare sample inputs that exercise the key control flow path.
     int value = 0;
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Report values so learners can verify the control flow outcome.
     cout << "Enter an integer: ";
     cin >> value;
 

languages/cpp/01-foundations/formatted-output-and-iomanip/example/main.cpp

@@ -1,14 +1,14 @@
-// This example shows formatting values so output is easier to read and compare.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: Formatting values so output is easier to read and compare.
+// Why it matters: practicing formatted output and iomanip patterns makes exercises and checkpoints
+// easier to reason about.
 
 #include <iomanip>
 #include <iostream>
 using namespace std;
 
-// Run one deterministic scenario so the console output makes formatting values so output is easier
-// to read and compare easy to verify.
+// Walk through one fixed scenario so formatted output and iomanip behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Prepare sample inputs that exercise the key formatted output and iomanip path.
     const char* item1 = "Notebook";
     const char* item2 = "Pen";
     const char* item3 = "Backpack";
@@ -17,7 +17,7 @@ int main() {
     const double p2 = 1.2;
     const double p3 = 30.0;
 
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Report values so learners can verify the formatted output and iomanip outcome.
     cout << left << setw(12) << "Item" << right << setw(10) << "Price" << '\n';
     cout << "----------------------\n";
 

languages/cpp/01-foundations/functions/example/main.cpp

@@ -1,11 +1,12 @@
-// This example shows breaking behavior into reusable functions with clear inputs and outputs.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: Breaking behavior into reusable functions with clear inputs and outputs.
+// Why it matters: practicing functions patterns makes exercises and checkpoints easier to reason
+// about.
 
 #include <iostream>
 #include <vector>
 using namespace std;
 
-// Define the reusable pieces first so the main flow can focus on one observable scenario.
+// Helper setup for functions; this keeps the walkthrough readable.
 int sum(int a, int b) { return a + b; }
 
 void swapByReference(int& left, int& right) {
@@ -35,11 +36,10 @@ void incrementByReference(int& number) {
     cout << "Inside incrementByReference: " << number << '\n';
 }
 
-// Run one deterministic scenario so the console output makes breaking behavior into reusable
-// functions with clear inputs and outputs easy to verify.
+// Walk through one fixed scenario so functions behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Prepare sample inputs that exercise the key functions path.
+    // Report values so learners can verify the functions outcome.
     cout << "sum(4, 6) = " << sum(4, 6) << '\n';
 
     int first = 10;

languages/cpp/01-foundations/operators-and-expressions/example/main.cpp

@@ -1,17 +1,17 @@
-// This example shows combining values through expressions and readable calculations.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: Combining values through expressions and readable calculations.
+// Why it matters: practicing operators and expressions patterns makes exercises and checkpoints
+// easier to reason about.
 
 #include <iostream>
 using namespace std;
 
-// Run one deterministic scenario so the console output makes combining values through expressions
-// and readable calculations easy to verify.
+// Walk through one fixed scenario so operators and expressions behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Prepare sample inputs that exercise the key operators and expressions path.
     const int a = 17;
     const int b = 5;
 
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Report values so learners can verify the operators and expressions outcome.
     cout << "a = " << a << ", b = " << b << "\n\n";
     cout << "a + b = " << (a + b) << '\n';
     cout << "a - b = " << (a - b) << '\n';

languages/cpp/01-foundations/scope-and-lifetime-basics/example/main.cpp

@@ -1,10 +1,11 @@
-// This example shows how names stay visible only inside the blocks that own them.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: How names stay visible only inside the blocks that own them.
+// Why it matters: practicing scope and lifetime basics patterns makes exercises and checkpoints
+// easier to reason about.
 
 #include <iostream>
 using namespace std;
 
-// Define the reusable pieces first so the main flow can focus on one observable scenario.
+// Helper setup for scope and lifetime basics; this keeps the walkthrough readable.
 void printRangeSum(int from, int to) {
     int sum = 0;
     for (int value = from; value <= to; ++value) {
@@ -13,12 +14,11 @@ void printRangeSum(int from, int to) {
     cout << "Sum from " << from << " to " << to << " = " << sum << '\n';
 }
 
-// Run one deterministic scenario so the console output makes how names stay visible only inside the
-// blocks that own them easy to verify.
+// Walk through one fixed scenario so scope and lifetime basics behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Prepare sample inputs that exercise the key scope and lifetime basics path.
     int value = 10;
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Report values so learners can verify the scope and lifetime basics outcome.
     cout << "Outer value: " << value << '\n';
 
     {

languages/cpp/01-foundations/strings/example/main.cpp

@@ -1,21 +1,21 @@
-// This example shows cleaning and combining text while preserving readable string logic.
-// In C++, the example keeps value flow, references, and explicit control visible.
+// Module focus: Cleaning and combining text while preserving readable string logic.
+// Why it matters: practicing strings patterns makes exercises and checkpoints easier to reason
+// about.
 
 #include <cctype>
 #include <iostream>
 #include <limits>
 #include <string>
 using namespace std;
 
-// Run one deterministic scenario so the console output makes cleaning and combining text while
-// preserving readable string logic easy to verify.
+// Walk through one fixed scenario so strings behavior stays repeatable.
 int main() {
-    // Build the sample state first, then let the later output confirm the behavior step by step.
+    // Prepare sample inputs that exercise the key strings path.
     int year = 0;
     string fullName;
     string sentence;
 
-    // Print the observed state here so learners can connect the code path to a concrete result.
+    // Report values so learners can verify the strings outcome.
     cout << "Enter your birth year: ";
     cin >> year;