opencompletion.com/research/activity37-programming-languages.yaml

default_max_attempts_per_step: 3
classifier_model: MODEL_0
feedback_model: MODEL_1
tokens_for_ai_rubric: 'Evaluate the student''s understanding of programming concepts in their chosen language.

  Consider:

  - Grasp of fundamental concepts (variables, types, control flow, functions)

  - Ability to write code that uses stdout to display output

  - Understanding of syntax in their chosen language

  - Problem-solving approach

  - Progression from simple to complex concepts


  Provide encouraging feedback adapted to their specific programming language.

  '
sections:
- section_id: introduction
  title: Welcome to Programming
  steps:
  - step_id: welcome
    title: Choose Your Language
    content_blocks:
    - '# Learn Programming: Your Language, Your Journey 💻'
    - Welcome to programming! You'll learn fundamental concepts that apply to all programming languages.
    - ''
    - '**First, choose your programming language:**'
    - ''
    - '**Popular choices:**'
    - '- Python (beginner-friendly, powerful, widely used)'
    - '- JavaScript (web development, interactive websites)'
    - '- Java (enterprise applications, Android)'
    - '- C++ (systems programming, games, performance-critical)'
    - '- C# (game development with Unity, Windows apps)'
    - '- Ruby (web development, elegant syntax)'
    - '- Go (modern, fast, concurrent systems)'
    - '- Rust (memory-safe systems programming)'
    - '- Swift (iOS/Mac development)'
    - '- Kotlin (Android development, modern JVM)'
    - ''
    - '**Or any other language you''re interested in:**'
    - '- PHP, Perl, R, Julia, Scala, Haskell, Elixir, Lua, TypeScript, Dart, Objective-C, Visual Basic, COBOL, Fortran, Assembly, etc.'
    - ''
    - '**All programming languages share core concepts** - what you learn in one language helps you learn others!'
    question: Which programming language would you like to learn? (Type the name of any programming language)
    tokens_for_ai: 'The student is choosing a programming language. Store their choice in metadata.


      Accept ANY programming language they name (Python, JavaScript, C++, COBOL, Brainfuck, whatever).

      Be enthusiastic about their choice regardless of language.


      For the REST of this activity:

      - ALL code examples must be in their chosen language

      - ALL explanations must be adapted to their language''s syntax and conventions

      - ALL feedback must reference their specific language


      Categorize as:

      - language_chosen: Student named a programming language (any language)

      - set_language: Student setting human language preference (not programming language)

      - off_topic: Didn''t choose a programming language

      '
    buckets:
    - language_chosen
    - set_language
    - off_topic
    transitions:
      language_chosen:
        ai_feedback:
          tokens_for_ai: 'Identify the programming language they chose. Be enthusiastic!

            Say something like: "Excellent choice! [Language] is great for [typical use cases]."

            Store the EXACT language name they provided in metadata.


            Remember: From now on, ALL code examples and explanations must be in their chosen language.

            '
        metadata_add:
          programming_language: the-users-response
        counts_as_attempt: false
        next_section_and_step: hello_world:step_1
      set_language:
        content_blocks:
        - I'll communicate in your preferred human language. But please also choose a PROGRAMMING language to learn (like Python, JavaScript, C++, etc.)
        counts_as_attempt: false
        next_section_and_step: introduction:welcome
      off_topic:
        content_blocks:
        - Please choose a programming language you'd like to learn. You can pick any language - Python, JavaScript, C++, or any other language you're interested in!
        counts_as_attempt: false
        next_section_and_step: introduction:welcome
- section_id: hello_world
  title: Hello World - Your First Program
  steps:
  - step_id: step_1
    title: Displaying Output
    content_blocks:
    - '## Your First Program: Hello World! 👋'
    - ''
    - '### What is "Hello World"?'
    - The traditional first program in any language is 'Hello World' - a program that displays text to the screen. This tradition dates back to the 1970s and serves as a simple test that your programming environment is working correctly.
    - ''
    - '### Understanding Standard Output (stdout)'
    - ''
    - '**What is stdout?**'
    - 'The term **stdout** (pronounced "standard out") stands for **standard output**. It''s the default destination where programs send their text output. When you run a program in a terminal or console, stdout is what displays on the screen.'
    - ''
    - '**Breaking down the terminology:**'
    - '- **Standard** = The default, conventional way programs handle output'
    - '- **Output** = Information flowing OUT of the program to the user'
    - '- **stdout** = Lowercase shorthand used in programming (also written as STDOUT in some contexts)'
    - ''
    - '**The Three Standard Streams**'
    - 'In Unix/Linux systems (and adopted by Windows), every program has three standard "streams" of data:'
    - ''
    - '1. **stdin (standard input)** - Where programs receive input (usually keyboard)'
    - '2. **stdout (standard output)** - Where programs send normal output (usually screen)'
    - '3. **stderr (standard error)** - Where programs send error messages (usually screen)'
    - ''
    - 'Right now we''re focusing on **stdout** because displaying output is the first thing beginners learn!'
    - ''
    - '**Why is stdout important?**'
    - 'Almost every program needs to communicate with its users. Whether it''s:'
    - '- Displaying calculation results'
    - '- Showing progress updates'
    - '- Presenting information to the user'
    - '- Debugging your code (printing variable values)'
    - ''
    - '...stdout is the fundamental way programs "talk" to people.'
    - ''
    - '**How stdout works:**'
    - ''
    - '```'
    - 'Your Program → stdout → Terminal/Console → Your Screen'
    - '```'
    - ''
    - 'When you write `print("Hello")` in Python or `console.log("Hello")` in JavaScript, you''re sending text to stdout, which the operating system then displays in your terminal window.'
    - ''
    - '**Historical Context**'
    - 'The concept of standard streams comes from Unix in the 1970s. Before graphical interfaces, all computing was done in text terminals. Programs needed a consistent way to:'
    - '- Read input (stdin)'
    - '- Display output (stdout)'
    - '- Report errors (stderr)'
    - ''
    - 'This simple, powerful design is still used today in every programming language!'
    - ''
    - '**Why "standard"?**'
    - 'It''s called "standard" because:'
    - '- Every program automatically has these streams connected when it starts'
    - '- It''s the standard/default way programs communicate'
    - '- It works consistently across different operating systems'
    - '- Other programs can read from or write to these streams (piping, redirection)'
    - ''
    - '**Advanced: Redirection (You don''t need this yet, but it''s cool!)**'
    - 'Because stdout is a "stream," you can redirect it:'
    - '- `program > output.txt` - Send stdout to a file instead of the screen'
    - '- `program1 | program2` - Send program1''s stdout to program2''s stdin'
    - ''
    - 'This is why understanding stdout matters - it''s not just "printing to the screen," it''s sending data to a stream that can go anywhere!'
    - ''
    - '### How Languages Display Output'
    - ''
    - 'Every programming language has its own syntax for displaying output to stdout:'
    - '- Some use a `print()` function'
    - '- Some use `console.log()`'
    - '- Some use methods like `System.out.println()`'
    - '- Some use stream operators like `<<`'
    - ''
    - 'Despite different syntax, they all accomplish the same goal: sending text to stdout.'
    - ''
    - '**Important Concept:**'
    - 'Text in quotes (like `"Hello, World!"`) is called a **string** - it represents text data that you want to display.'
    - ''
    - 'Now you''ll figure out how YOUR chosen language does it!'
    - ''
    - '### Now It''s Your Turn!'
    question: How do you display 'Hello, World!' to stdout in your chosen language? Write the complete code.
    tokens_for_ai: 'IMPORTANT: Get the student''s chosen language from metadata (programming_language).


      Evaluate their Hello World code in THAT specific language.


      Examples of correct Hello World in various languages:

      - Python: print("Hello, World!")

      - JavaScript: console.log("Hello, World!");

      - Java: System.out.println("Hello, World!");

      - C++: std::cout << "Hello, World!" << std::endl;

      - C: printf("Hello, World!\n");

      - Ruby: puts "Hello, World!"

      - Go: fmt.Println("Hello, World!")

      - Rust: println!("Hello, World!");

      - PHP: echo "Hello, World!";

      - Swift: print("Hello, World!")


      If they write correct code for their language, praise them!

      If incorrect, show them the correct syntax for their specific language.


      Categorize as:

      - correct: Valid Hello World code in their chosen language

      - close: Has the right idea but syntax errors

      - wrong_language: Used a different language than they chose

      - incomplete: Missing parts

      - limited_effort: Too brief or unclear

      - asking_clarifying_questions: Asking for help

      - off_topic: Not attempting the task

      '
    feedback_tokens_for_ai: 'Provide feedback specific to their language.

      If correct, show enthusiasm!

      If incorrect, show the correct syntax and explain it.


      Always show the correct code for their specific language.

      '
    buckets:
    - correct
    - close
    - wrong_language
    - incomplete
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Perfect! That's exactly how you write Hello World in [their language]. Explain what each part does (the output function/statement, the string, any semicolons/syntax).
        metadata_add:
          score: n+2
          concepts_mastered: n+1
        next_section_and_step: hello_world:step_2
      close:
        ai_feedback:
          tokens_for_ai: You have the right idea! Show them the correct syntax for their language and explain what was slightly off.
        metadata_add:
          score: n+1
        next_section_and_step: hello_world:step_1
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That looks like code for a different language! You chose [their language]. Here''s how you do it in [their language]: [show correct code]'
        next_section_and_step: hello_world:step_1
      incomplete:
        ai_feedback:
          tokens_for_ai: You're on the right track but missing some parts. Show the complete Hello World code for their language.
        next_section_and_step: hello_world:step_1
      limited_effort:
        content_blocks:
        - Try writing the actual code! How does your chosen language display text to the screen?
        next_section_and_step: hello_world:step_1
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Help them with their question, then show the Hello World code for their specific language.
        counts_as_attempt: false
        next_section_and_step: hello_world:step_1
      off_topic:
        content_blocks:
        - Let's write your first program! How do you display 'Hello, World!' in your chosen language?
        next_section_and_step: hello_world:step_1
  - step_id: step_2
    title: Multiple Outputs
    content_blocks:
    - '## Displaying Multiple Lines'
    - ''
    - '### Building on What You''ve Learned'
    - Great! Now that you can display one message, let's display multiple messages. This is a fundamental skill because real programs often need to show multiple pieces of information.
    - ''
    - '### Two Ways to Display Multiple Lines'
    - ''
    - '**Method 1: Multiple Output Statements**'
    - You can call your output function multiple times in sequence. Each call displays one line.
    - ''
    - '**Example in Python:**'
    - '```python'
    - 'print("First line")'
    - 'print("Second line")'
    - 'print("Third line")'
    - '```'
    - ''
    - '**Method 2: Newline Characters**'
    - Many languages support special characters like `\n` (newline) that create line breaks within a single string.
    - ''
    - '**Example in Python:**'
    - '```python'
    - 'print("First line\nSecond line\nThird line")'
    - '```'
    - ''
    - '### Understanding Newlines'
    - The `\n` is called an "escape sequence" - a special character that represents a line break. When the computer sees `\n`, it moves to the next line.'
    - ''
    - '**Why use multiple statements vs newlines?**'
    - '- Multiple statements are clearer and easier to read'
    - '- Newlines are more compact and useful when you have a long block of text'
    - '- Both are valid approaches!'
    - ''
    - '### Now It''s Your Turn!'
    question: 'Write a program that displays three lines to stdout: ''My first program'', ''Learning to code'', and ''This is fun!'' (each on its own line)'
    tokens_for_ai: 'The student should write code in THEIR chosen language (from metadata) that outputs three lines.


      Check that:

      - Code is in their chosen language

      - Outputs all three strings

      - Each on a separate line (using newlines or multiple output statements)


      Categorize as:

      - correct: Valid code outputting all three lines in their language

      - close: Right idea, minor syntax issues

      - missing_newlines: All on one line instead of three

      - incomplete: Missing one or more lines

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Asking for help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'Provide feedback specific to their language.

      Show the correct code if needed.

      Explain how newlines work in their language (\\n in strings, or separate output statements, etc.).

      '
    buckets:
    - correct
    - close
    - missing_newlines
    - incomplete
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Excellent! You've written multiple output statements in [their language]. Explain how they can use this to build more complex programs.
        metadata_add:
          score: n+2
          concepts_mastered: n+1
        next_section_and_step: variables:step_1
      close:
        ai_feedback:
          tokens_for_ai: Almost there! Show the correct code and explain the minor issue.
        metadata_add:
          score: n+1
        next_section_and_step: hello_world:step_2
      missing_newlines:
        ai_feedback:
          tokens_for_ai: Good try! But they should be on separate lines. Show how to create newlines in their language (either \n in strings or multiple statements).
        next_section_and_step: hello_world:step_2
      incomplete:
        ai_feedback:
          tokens_for_ai: You're missing one or more of the required lines. Show the complete code for their language.
        next_section_and_step: hello_world:step_2
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'Remember, you''re learning [their language]! Here''s how to do it in [their language]: [show code]'
        next_section_and_step: hello_world:step_2
      limited_effort:
        content_blocks:
        - Write the actual code to display all three messages!
        next_section_and_step: hello_world:step_2
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question, then guide them on how to output multiple lines in their language.
        counts_as_attempt: false
        next_section_and_step: hello_world:step_2
      off_topic:
        content_blocks:
        - Write code to display three lines of text using your chosen language.
        next_section_and_step: hello_world:step_2
- section_id: variables
  title: Variables and Data Types
  steps:
  - step_id: step_1
    title: Creating Variables
    content_blocks:
    - '## Variables: Storing Information 📦'
    - ''
    - '### What Are Variables?'
    - Variables are one of the most fundamental concepts in programming. A variable is a named storage location in your computer''s memory that holds a value. Think of it as a labeled container where you can store information and retrieve it later.
    - ''
    - '### Why Do We Need Variables?'
    - Imagine if you could only work with literal values. You''d have to write "Alice" everywhere you need that name. But with a variable, you write the name once, and then use the variable name to refer to it. This makes your code:'
    - '- **Reusable:** Use the same value in multiple places'
    - '- **Maintainable:** Change the value in one place, and it updates everywhere'
    - '- **Dynamic:** The value can change while the program runs'
    - '- **Readable:** `username` is clearer than "alice123"'
    - ''
    - '### The Box Analogy'
    - '**Think of a variable as a labeled box:**'
    - '- **The label** = the variable name (like `name`, `age`, `score`)'
    - '- **The contents** = the value stored inside (like `"Alice"`, `25`, `100`)'
    - '- **Reading** = looking inside the box to see what''s there'
    - '- **Writing/Updating** = putting new contents in the box'
    - ''
    - '### Variable Naming Rules'
    - 'Most languages follow similar rules for naming variables:'
    - '- Start with a letter or underscore (not a number)'
    - '- Can contain letters, numbers, and underscores'
    - '- Cannot use reserved words (like `if`, `for`, `while`)'
    - '- **Case-sensitive:** `name` and `Name` are different variables'
    - ''
    - '**Good names:** `user_name`, `total_score`, `isActive`, `playerHealth`'
    - '**Bad names:** `x`, `temp`, `asdf`, `thing1`'
    - ''
    - '### How Languages Handle Variables'
    - ''
    - 'Every programming language has its own syntax for creating variables, but they all follow the same basic pattern:'
    - '1. Give the variable a name'
    - '2. Use an assignment operator (usually `=`)'
    - '3. Provide a value'
    - ''
    - '**Important Language Difference:**'
    - ''
    - '**Dynamically typed languages** (like Python, JavaScript, Ruby):'
    - '- You just name the variable and assign a value'
    - '- The language automatically figures out the type'
    - '- Simpler syntax, more flexible'
    - ''
    - '**Statically typed languages** (like Java, C++, C#, Go):'
    - '- You must specify the data type when creating a variable'
    - '- Example: declare that `name` will store a String'
    - '- More verbose, but catches type errors early'
    - ''
    - 'You''ll use YOUR language''s specific syntax to create variables!'
    - ''
    - '### The Assignment Operator'
    - 'The `=` sign is the **assignment operator**. It means "assign the value on the right to the variable on the left."'
    - ''
    - '```'
    - 'name = "Alice"'
    - '│      │'
    - '│      └── The value (what goes in the box)'
    - '└── The variable name (the label on the box)'
    - '```'
    - ''
    - '**Important:** In programming, `=` means assignment, NOT mathematical equality! To test equality, most languages use `==`.'
    - ''
    - '### Now It''s Your Turn!'
    question: Write a program that creates a variable called 'name' with your name as the value, then displays it to stdout.
    tokens_for_ai: 'Check that student writes code in THEIR language that:

      - Creates a variable (using their language''s syntax)

      - Assigns a string value to it

      - Outputs the variable to stdout


      Examples:

      - Python: name = "Alice" \\n print(name)

      - JavaScript: let name = "Alice"; \\n console.log(name);

      - Java: String name = "Alice"; \\n System.out.println(name);

      - C++: std::string name = "Alice"; \\n std::cout << name << std::endl;


      Categorize as:

      - correct: Valid variable creation and output in their language

      - close: Right idea, minor syntax issues

      - missing_declaration: In typed languages, forgot type

      - wrong_output: Created variable but didn''t output it

      - hardcoded_output: Outputted string directly instead of using variable

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Needs help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'Provide feedback for their specific language.

      Show correct syntax for variable declaration (including type if their language requires it).

      Explain how to output a variable in their language.

      '
    buckets:
    - correct
    - close
    - missing_declaration
    - wrong_output
    - hardcoded_output
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Perfect! You've created a variable and displayed it in [their language]. Explain how variables make code reusable and dynamic.
        metadata_add:
          score: n+2
          concepts_mastered: n+1
        next_section_and_step: variables:step_2
      close:
        ai_feedback:
          tokens_for_ai: Almost! Show the correct syntax and explain the issue.
        metadata_add:
          score: n+1
        next_section_and_step: variables:step_1
      missing_declaration:
        ai_feedback:
          tokens_for_ai: In [their language], you need to declare the variable type. Show the correct syntax with type declaration.
        next_section_and_step: variables:step_1
      wrong_output:
        ai_feedback:
          tokens_for_ai: You created the variable but didn't display it! Show how to output the variable in their language.
        next_section_and_step: variables:step_1
      hardcoded_output:
        ai_feedback:
          tokens_for_ai: You need to store the value in a variable first, then display the VARIABLE, not the string directly. Show the correct approach.
        next_section_and_step: variables:step_1
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That''s not [their language] syntax! Here''s how to create and display a variable in [their language]: [show code]'
        next_section_and_step: variables:step_1
      limited_effort:
        content_blocks:
        - Write the actual code! Create a variable and then display it.
        next_section_and_step: variables:step_1
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question about variables in their specific language.
        counts_as_attempt: false
        next_section_and_step: variables:step_1
      off_topic:
        content_blocks:
        - Create a variable with your name and display it using your chosen language.
        next_section_and_step: variables:step_1
  - step_id: step_2
    title: Data Types
    content_blocks:
    - '## Understanding Data Types'
    - ''
    - '### What Are Data Types?'
    - 'Just as in real life we have different kinds of information (names, ages, prices, yes/no answers), programming has different **data types** to represent different kinds of values. The type of data determines what operations you can perform on it.'
    - ''
    - '### Why Data Types Matter'
    - 'Data types tell the computer:'
    - '- How much memory to allocate'
    - '- What operations are valid (you can add numbers, but adding text doesn''t make mathematical sense)'
    - '- How to interpret the bits in memory'
    - ''
    - 'For example: `"25" + "10"` (strings) might give `"2510"` (concatenation), but `25 + 10` (numbers) gives `35` (addition).'
    - ''
    - '### The Four Fundamental Data Types'
    - ''
    - '**1. Strings (Text)**'
    - '- Represent text and characters'
    - '- Enclosed in quotes: `"hello"`, `''world''`, `"Alice"`'
    - '- Can contain letters, numbers, spaces, symbols'
    - '- Examples: names, addresses, messages, file paths'
    - ''
    - '**2. Integers (Whole Numbers)**'
    - '- Whole numbers without decimal points'
    - '- Can be positive, negative, or zero'
    - '- Examples: `42`, `-17`, `0`, `1000`'
    - '- Used for: counting, indexing, discrete quantities'
    - ''
    - '**3. Floats/Doubles (Decimal Numbers)**'
    - '- Numbers with decimal points'
    - '- More precision for measurements'
    - '- Examples: `3.14`, `-0.5`, `2.71828`, `1.75`'
    - '- Used for: measurements, prices, scientific calculations'
    - '- Note: "Float" = single precision, "Double" = double precision'
    - ''
    - '**4. Booleans (True/False)**'
    - '- Only two possible values: `true` or `false`'
    - '- Used for: decisions, conditions, flags'
    - '- Examples: `isActive`, `hasPermission`, `gameOver`'
    - '- We''ll use these heavily with if statements later!'
    - ''
    - '### Static vs Dynamic Typing'
    - ''
    - '**Statically Typed Languages** (Java, C++, C#, Go, Rust):'
    - '- You MUST declare the type when creating a variable'
    - '- Type cannot change after declaration'
    - '- Catches type errors before the program runs'
    - ''
    - '**Example in Java:**'
    - '```java'
    - 'int age = 25;              // Integer type'
    - 'double height = 1.75;      // Decimal type'
    - 'String city = "Tokyo";     // String type'
    - 'boolean isStudent = true;  // Boolean type'
    - '```'
    - ''
    - '**Dynamically Typed Languages** (Python, JavaScript, Ruby, PHP):'
    - '- Type is inferred automatically from the value'
    - '- Variables can hold different types at different times'
    - '- More flexible but less type safety'
    - ''
    - '**Example in Python:**'
    - '```python'
    - 'age = 25              # Python knows it''s an integer'
    - 'height = 1.75         # Python knows it''s a float'
    - 'city = "Tokyo"        # Python knows it''s a string'
    - 'is_student = True     # Python knows it''s a boolean'
    - '```'
    - ''
    - '### Combining Strings and Variables in Output'
    - 'When displaying variables with labels, you need to combine strings and values. Different languages have different approaches:'
    - ''
    - '**Python - f-strings (modern):**'
    - '```python'
    - 'age = 25'
    - 'print(f"Age: {age}")  # Output: Age: 25'
    - '```'
    - ''
    - '**JavaScript - template literals:**'
    - '```javascript'
    - 'let age = 25;'
    - 'console.log(`Age: ${age}`);  // Output: Age: 25'
    - '```'
    - ''
    - '**Java - concatenation:**'
    - '```java'
    - 'int age = 25;'
    - 'System.out.println("Age: " + age);  // Output: Age: 25'
    - '```'
    - ''
    - '**C++ - stream insertion:**'
    - '```cpp'
    - 'int age = 25;'
    - 'std::cout << "Age: " << age << std::endl;  // Output: Age: 25'
    - '```'
    - ''
    - '### Type Conversion'
    - 'Sometimes you need to convert between types:'
    - '- String to number: `int("25")` (Python), `parseInt("25")` (JavaScript)'
    - '- Number to string: `str(25)` (Python), `String.valueOf(25)` (Java)'
    - '- Integer to float: Usually automatic in most languages'
    - ''
    - '### Now It''s Your Turn!'
    - 'Practice working with multiple data types by creating variables of different types and displaying them with descriptive labels.'
    question: 'Write a program with three variables: an integer (age), a decimal/float (height in meters), and a string (city). Display all three with labels, like ''Age: 25'', ''Height: 1.75'', ''City: Tokyo'''
    tokens_for_ai: 'Check that student creates three variables of different types and outputs them with labels.


      For their specific language:

      - Integer variable

      - Float/decimal variable

      - String variable

      - Outputs each with descriptive label


      Categorize as:

      - correct: All three types declared and outputted correctly

      - close: Right idea, minor issues

      - missing_types: In typed language, didn''t specify types

      - wrong_types: Used wrong type for data (string for number, etc.)

      - missing_labels: Outputted values but without labels

      - incomplete: Missing one or more variables

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Needs help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'For their language, show:

      - How to declare each type

      - How to output strings and variables together (concatenation or formatting)

      - Any type-specific syntax


      If statically typed language (Java, C++, etc.): ensure they declared types

      If dynamically typed (Python, JavaScript, Ruby): explain that types are inferred

      '
    buckets:
    - correct
    - close
    - missing_types
    - wrong_types
    - missing_labels
    - incomplete
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Excellent! You've worked with multiple data types in [their language]. Explain how different types are used for different purposes.
        metadata_add:
          score: n+3
          concepts_mastered: n+1
        next_section_and_step: control_flow:step_1
      close:
        ai_feedback:
          tokens_for_ai: Good work! Show the corrected version and explain string concatenation or formatting in their language.
        metadata_add:
          score: n+2
        next_section_and_step: variables:step_2
      missing_types:
        ai_feedback:
          tokens_for_ai: In [their language], you need to specify variable types. Show the correct syntax with type declarations.
        next_section_and_step: variables:step_2
      wrong_types:
        ai_feedback:
          tokens_for_ai: Check your data types! Numbers shouldn't be in quotes (they'd be strings). Show the correct way to declare each type.
        next_section_and_step: variables:step_2
      missing_labels:
        ai_feedback:
          tokens_for_ai: 'Add labels like ''Age: 25'' so it''s clear what each value represents. Show how to combine strings and variables in their language.'
        next_section_and_step: variables:step_2
      incomplete:
        ai_feedback:
          tokens_for_ai: You need all three variables (integer, float, string). Show the complete code.
        next_section_and_step: variables:step_2
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That''s not [their language]! Here''s how to declare different types in [their language]: [show code]'
        next_section_and_step: variables:step_2
      limited_effort:
        content_blocks:
        - Write complete code with all three variable types and display them with labels!
        next_section_and_step: variables:step_2
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question about data types or string formatting in their language.
        counts_as_attempt: false
        next_section_and_step: variables:step_2
      off_topic:
        content_blocks:
        - Create three variables of different types (integer, float, string) and display them.
        next_section_and_step: variables:step_2
- section_id: control_flow
  title: 'Control Flow: Making Decisions'
  steps:
  - step_id: step_1
    title: If Statements
    content_blocks:
    - '## Conditional Logic: Making Decisions 🔀'
    - ''
    - '### What Is Conditional Logic?'
    - 'Up until now, your programs have been linear - they execute every line in order from top to bottom. But real programs need to make **decisions** based on different situations. This is called **conditional logic** or **branching**.'
    - ''
    - '### Why Do We Need Conditionals?'
    - 'Think about everyday decisions:'
    - '- "IF it''s raining, take an umbrella. ELSE, leave it at home."'
    - '- "IF you have enough money, buy the item. ELSE, save up more."'
    - '- "IF the user is logged in, show their dashboard. ELSE, show the login page."'
    - ''
    - 'Programs need to make similar decisions based on the current state or user input.'
    - ''
    - '### The If Statement'
    - 'An **if statement** tests a **condition** (something that evaluates to true or false) and executes code only if that condition is true.'
    - ''
    - '**Basic structure:**'
    - '```'
    - 'IF condition is true:'
    - '    execute this code'
    - '```'
    - ''
    - '**With else:**'
    - '```'
    - 'IF condition is true:'
    - '    execute this code'
    - 'ELSE:'
    - '    execute this other code'
    - '```'
    - ''
    - '### Comparison Operators'
    - 'To test conditions, we use **comparison operators** that compare two values and return true or false:'
    - ''
    - '- `==` Equal to (Note: double equals for comparison, single = for assignment!)'
    - '- `!=` Not equal to'
    - '- `>` Greater than'
    - '- `<` Less than'
    - '- `>=` Greater than or equal to'
    - '- `<=` Less than or equal to'
    - ''
    - '**Examples:**'
    - '- `age >= 18` → true if age is 18 or more, false otherwise'
    - '- `score == 100` → true if score is exactly 100'
    - '- `temperature > 30` → true if temperature exceeds 30'
    - ''
    - '### If/Else in Different Languages'
    - ''
    - '**Python:**'
    - '```python'
    - 'age = 20'
    - 'if age >= 18:'
    - '    print("Adult")'
    - 'else:'
    - '    print("Minor")'
    - '```'
    - 'Note: Python uses **indentation** to show which code belongs to the if/else blocks. Colons (`:`) start each block.'
    - ''
    - '**JavaScript:**'
    - '```javascript'
    - 'let age = 20;'
    - 'if (age >= 18) {'
    - '    console.log("Adult");'
    - '} else {'
    - '    console.log("Minor");'
    - '}'
    - '```'
    - 'Note: Curly braces `{}` group the code blocks. Condition must be in parentheses `()`.'
    - ''
    - '**Java:**'
    - '```java'
    - 'int age = 20;'
    - 'if (age >= 18) {'
    - '    System.out.println("Adult");'
    - '} else {'
    - '    System.out.println("Minor");'
    - '}'
    - '```'
    - 'Similar to JavaScript - uses braces and parentheses.'
    - ''
    - '**C++:**'
    - '```cpp'
    - 'int age = 20;'
    - 'if (age >= 18) {'
    - '    std::cout << "Adult" << std::endl;'
    - '} else {'
    - '    std::cout << "Minor" << std::endl;'
    - '}'
    - '```'
    - ''
    - '### Multiple Conditions (Else If)'
    - 'You can chain multiple conditions using else-if:'
    - ''
    - '```python'
    - 'if age < 13:'
    - '    print("Child")'
    - 'elif age < 18:      # else if in Python'
    - '    print("Teen")'
    - 'else:'
    - '    print("Adult")'
    - '```'
    - ''
    - '### How the Computer Evaluates Conditionals'
    - '1. Evaluate the condition (does it produce true or false?)'
    - '2. If true, execute the if block and skip the else'
    - '3. If false, skip the if block and execute the else'
    - '4. Continue with the rest of the program'
    - ''
    - '### Boolean Logic'
    - 'Remember boolean data types? Conditions always evaluate to a boolean:'
    - '- `age >= 18` → evaluates to `true` or `false`'
    - '- You can also use boolean variables directly: `if isLoggedIn:`'
    - ''
    - '### Now It''s Your Turn!'
    - 'Practice conditional logic by writing an if/else statement that checks age and displays different messages.'
    question: 'Write a program that: creates a variable for age, then uses an if/else statement to display ''Adult'' if age is 18 or older, or ''Minor'' if younger. Test with age = 20.'
    tokens_for_ai: 'Check their if/else code in their chosen language.


      Should have:

      - Age variable (set to 20 or any value)

      - If statement checking if age >= 18

      - Displays "Adult" if true

      - Else displays "Minor"

      - Uses stdout for output


      Categorize as:

      - correct: Valid if/else in their language

      - close: Right logic, minor syntax issues

      - wrong_comparison: Used wrong operator (==, <, etc.)

      - missing_else: Has if but no else

      - logic_error: Backwards logic (minor when >= 18)

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Needs help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'Show if/else syntax for their specific language.

      Explain:

      - Comparison operators in their language

      - How to structure if/else blocks

      - Any language-specific syntax (colons, braces, etc.)

      '
    buckets:
    - correct
    - close
    - wrong_comparison
    - missing_else
    - logic_error
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Perfect if/else statement in [their language]! Explain how conditional logic lets programs make decisions.
        metadata_add:
          score: n+3
          concepts_mastered: n+1
        next_section_and_step: control_flow:step_2
      close:
        ai_feedback:
          tokens_for_ai: Good logic! Fix the minor syntax issue and show the correct version.
        metadata_add:
          score: n+2
        next_section_and_step: control_flow:step_1
      wrong_comparison:
        ai_feedback:
          tokens_for_ai: Check your comparison operator! You need 'greater than or equal to 18'. Show the correct operator for their language (>=).
        next_section_and_step: control_flow:step_1
      missing_else:
        ai_feedback:
          tokens_for_ai: You need an else clause for when age < 18. Show the complete if/else structure in their language.
        next_section_and_step: control_flow:step_1
      logic_error:
        ai_feedback:
          tokens_for_ai: Your logic is backwards! Age >= 18 should be 'Adult', not 'Minor'. Show the corrected version.
        next_section_and_step: control_flow:step_1
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That''s not [their language] syntax! Here''s how if/else works in [their language]: [show code]'
        next_section_and_step: control_flow:step_1
      limited_effort:
        content_blocks:
        - Write the complete if/else code to check age and display the appropriate message!
        next_section_and_step: control_flow:step_1
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question about if/else statements in their language.
        counts_as_attempt: false
        next_section_and_step: control_flow:step_1
      off_topic:
        content_blocks:
        - Write an if/else statement to check if age is 18 or older.
        next_section_and_step: control_flow:step_1
  - step_id: step_2
    title: Loops
    content_blocks:
    - '## Loops: Repeating Actions 🔁'
    - ''
    - '### What Are Loops?'
    - 'Imagine you want to display numbers 1 through 1000. Would you write 1000 print statements? Of course not! **Loops** let you repeat code multiple times without writing it over and over.'
    - ''
    - '### Why Do We Need Loops?'
    - 'Loops are essential for:'
    - '- **Repetitive tasks:** Displaying numbers, processing items, running calculations'
    - '- **Collections:** Going through every element in a list or array'
    - '- **Automation:** Doing the same thing many times efficiently'
    - '- **Iteration:** Repeating until a goal is reached'
    - ''
    - 'Without loops, programs would be extremely limited and repetitive!'
    - ''
    - '### The Two Main Types of Loops'
    - ''
    - '**1. For Loop (Counting Loop)**'
    - '- Use when you know HOW MANY times to repeat'
    - '- Has a counter variable that changes each iteration'
    - '- Best for: counting, iterating a specific number of times'
    - ''
    - '**2. While Loop (Conditional Loop)**'
    - '- Use when you want to repeat UNTIL a condition becomes false'
    - '- Keeps going as long as the condition is true'
    - '- Best for: unknown number of repetitions, waiting for something to happen'
    - ''
    - '### For Loops in Detail'
    - 'A for loop typically has three parts:'
    - '1. **Initialization:** Set up a counter variable'
    - '2. **Condition:** When to stop looping'
    - '3. **Update:** How to change the counter after each iteration'
    - ''
    - '### For Loops in Different Languages'
    - ''
    - '**Python (using range):**'
    - '```python'
    - 'for i in range(1, 6):  # Start at 1, stop before 6 (so 1,2,3,4,5)'
    - '    print(i)'
    - '```'
    - 'Python''s `range(start, stop)` generates numbers from start up to (but not including) stop.'
    - ''
    - '**JavaScript (C-style):**'
    - '```javascript'
    - 'for (let i = 1; i <= 5; i++) {  // Start; Condition; Increment'
    - '    console.log(i);'
    - '}'
    - '```'
    - 'Breaking it down:'
    - '- `let i = 1` - Initialize counter to 1'
    - '- `i <= 5` - Keep going while i is 5 or less'
    - '- `i++` - Add 1 to i after each iteration (`++` means increment by 1)'
    - ''
    - '**Java (same as JavaScript):**'
    - '```java'
    - 'for (int i = 1; i <= 5; i++) {'
    - '    System.out.println(i);'
    - '}'
    - '```'
    - ''
    - '**C++ (same pattern):**'
    - '```cpp'
    - 'for (int i = 1; i <= 5; i++) {'
    - '    std::cout << i << std::endl;'
    - '}'
    - '```'
    - ''
    - '**Ruby:**'
    - '```ruby'
    - '(1..5).each do |i|  # Range from 1 to 5'
    - '    puts i'
    - 'end'
    - '```'
    - ''
    - '**Go:**'
    - '```go'
    - 'for i := 1; i <= 5; i++ {'
    - '    fmt.Println(i)'
    - '}'
    - '```'
    - ''
    - '### How a For Loop Executes'
    - 'Let''s trace through `for (let i = 1; i <= 5; i++)`:'
    - ''
    - '1. **Iteration 1:** i=1, check 1<=5 (true), print 1, increment to i=2'
    - '2. **Iteration 2:** i=2, check 2<=5 (true), print 2, increment to i=3'
    - '3. **Iteration 3:** i=3, check 3<=5 (true), print 3, increment to i=4'
    - '4. **Iteration 4:** i=4, check 4<=5 (true), print 4, increment to i=5'
    - '5. **Iteration 5:** i=5, check 5<=5 (true), print 5, increment to i=6'
    - '6. **Check:** i=6, check 6<=5 (false), exit loop'
    - ''
    - '### The Loop Variable'
    - 'The variable `i` is called the **loop variable** or **counter**:'
    - '- Common names: `i`, `j`, `k` (for nested loops), or descriptive names like `count`, `index`'
    - '- It automatically updates each iteration'
    - '- You can use it inside the loop for calculations or display'
    - ''
    - '### Common Loop Patterns'
    - ''
    - '**Count from 0 to N-1:**'
    - '```python'
    - 'for i in range(5):  # 0, 1, 2, 3, 4'
    - '    print(i)'
    - '```'
    - ''
    - '**Count by 2s:**'
    - '```python'
    - 'for i in range(0, 11, 2):  # 0, 2, 4, 6, 8, 10'
    - '    print(i)'
    - '```'
    - ''
    - '**Count backwards:**'
    - '```python'
    - 'for i in range(5, 0, -1):  # 5, 4, 3, 2, 1'
    - '    print(i)'
    - '```'
    - ''
    - '### Avoiding Infinite Loops'
    - 'Make sure your loop will eventually end! Common mistakes:'
    - '- Forgetting to increment the counter'
    - '- Wrong condition (using `<` when you need `>`)'
    - '- Modifying the counter incorrectly inside the loop'
    - ''
    - '### Now It''s Your Turn!'
    - 'Practice loops by writing a simple counting loop that displays numbers 1 through 5.'
    question: Write a program using a for loop that displays the numbers 1 through 5 to stdout, each on its own line.
    tokens_for_ai: 'Check their for loop code in their chosen language.


      Should:

      - Use a for loop (or equivalent iteration construct)

      - Display numbers 1, 2, 3, 4, 5

      - Each number on separate line

      - Use stdout


      Note: Loop syntax varies WIDELY between languages!

      - Python: for i in range(1, 6): print(i)

      - JavaScript: for (let i = 1; i <= 5; i++) console.log(i);

      - Java: for (int i = 1; i <= 5; i++) System.out.println(i);

      - C++: for (int i = 1; i <= 5; i++) std::cout << i << std::endl;


      Categorize as:

      - correct: Valid for loop in their language

      - close: Right idea, minor syntax issues

      - off_by_one: Shows 0-4 or 1-6 instead of 1-5

      - wrong_loop_type: Used while instead of for (acceptable if works)

      - missing_output: Loop exists but doesn''t display

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Needs help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'Show for loop syntax for their specific language.

      Explain:

      - How to initialize loop variable

      - How to set the condition

      - How to increment

      - Language-specific syntax (parentheses, colons, braces, etc.)


      If they used a while loop that works, that''s acceptable - mention that for loops

      are more common for counting.

      '
    buckets:
    - correct
    - close
    - off_by_one
    - wrong_loop_type
    - missing_output
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Excellent for loop in [their language]! Explain how loops save you from writing repetitive code.
        metadata_add:
          score: n+3
          concepts_mastered: n+1
        next_section_and_step: functions:step_1
      close:
        ai_feedback:
          tokens_for_ai: Good approach! Fix the syntax issue and show the correct version.
        metadata_add:
          score: n+2
        next_section_and_step: control_flow:step_2
      off_by_one:
        ai_feedback:
          tokens_for_ai: Close! But you're displaying the wrong numbers. Should be 1-5. Show the corrected loop for their language.
        next_section_and_step: control_flow:step_2
      wrong_loop_type:
        ai_feedback:
          tokens_for_ai: Your while loop works! But try using a for loop - it's more common for counting. Show the for loop version.
        metadata_add:
          score: n+2
        next_section_and_step: functions:step_1
      missing_output:
        ai_feedback:
          tokens_for_ai: You have a loop but it's not displaying anything! Add output inside the loop body.
        next_section_and_step: control_flow:step_2
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That''s not [their language]! Here''s the for loop syntax in [their language]: [show code]'
        next_section_and_step: control_flow:step_2
      limited_effort:
        content_blocks:
        - Write a complete for loop that displays 1, 2, 3, 4, 5!
        next_section_and_step: control_flow:step_2
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question about for loops in their specific language.
        counts_as_attempt: false
        next_section_and_step: control_flow:step_2
      off_topic:
        content_blocks:
        - Write a for loop that displays numbers 1 through 5.
        next_section_and_step: control_flow:step_2
- section_id: functions
  title: 'Functions: Reusable Code'
  steps:
  - step_id: step_1
    title: Creating Functions
    content_blocks:
    - '## Functions: Organize and Reuse Your Code 📦'
    - ''
    - '### What Are Functions?'
    - 'A **function** is a named block of reusable code that performs a specific task. Think of it as a mini-program within your program. Functions are one of the most important concepts in programming because they let you organize code and avoid repetition.'
    - ''
    - '### Why Do We Need Functions?'
    - ''
    - '**Without functions, code becomes:**'
    - '- Repetitive (copy-paste the same code everywhere)'
    - '- Hard to maintain (fix a bug in 50 places instead of 1)'
    - '- Difficult to understand (one giant block of code)'
    - '- Impossible to test in isolation'
    - ''
    - '**With functions, code becomes:**'
    - '- **Reusable:** Write once, use many times'
    - '- **Organized:** Break complex programs into manageable pieces'
    - '- **Readable:** `calculateTax()` is clearer than 50 lines of math'
    - '- **Testable:** Test each function independently'
    - '- **Abstract:** Hide implementation details behind a simple name'
    - ''
    - '### Real-World Analogy'
    - 'Think of functions like recipes in a cookbook:'
    - '- Each recipe has a **name** ("Chocolate Cake")'
    - '- Each recipe takes **ingredients** (inputs/parameters)'
    - '- Each recipe has **instructions** (the function body - what it does)'
    - '- Each recipe produces **a result** (output/return value)'
    - ''
    - 'You don''t rewrite the recipe every time you want cake - you just refer to it by name: "Make Chocolate Cake"'
    - ''
    - '### Anatomy of a Function'
    - ''
    - 'Every function has these parts:'
    - ''
    - '1. **Name:** What you call the function (`greet`, `calculateTotal`, `isValid`)'
    - '2. **Parameters:** Inputs the function needs (optional)'
    - '3. **Body:** The code that runs when you call the function'
    - '4. **Return value:** What the function sends back (optional)'
    - ''
    - '**Defining vs Calling:**'
    - '- **Definition** = Creating the function (writing the recipe)'
    - '- **Call** = Using the function (following the recipe)'
    - ''
    - '### Functions in Different Languages'
    - ''
    - '**Python:**'
    - '```python'
    - '# Define the function'
    - 'def greet(name):                    # def = define, name = parameter'
    - '    print(f"Hello, {name}!")        # Function body (indented)'
    - ''
    - '# Call the function'
    - 'greet("Alice")                      # Output: Hello, Alice!'
    - 'greet("Bob")                        # Output: Hello, Bob!'
    - '```'
    - ''
    - '**JavaScript:**'
    - '```javascript'
    - '// Define the function'
    - 'function greet(name) {              // function keyword'
    - '    console.log(`Hello, ${name}!`); // Function body in braces'
    - '}'
    - ''
    - '// Call the function'
    - 'greet("Alice");                     // Output: Hello, Alice!'
    - 'greet("Bob");                       // Output: Hello, Bob!'
    - '```'
    - ''
    - '**Java:**'
    - '```java'
    - '// Define the function (method)'
    - 'void greet(String name) {                      // void = no return value'
    - '    System.out.println("Hello, " + name + "!");'
    - '}'
    - ''
    - '// Call the function'
    - 'greet("Alice");'
    - 'greet("Bob");'
    - '```'
    - ''
    - '**C++:**'
    - '```cpp'
    - '// Define the function'
    - 'void greet(std::string name) {                 // void = no return'
    - '    std::cout << "Hello, " << name << "!" << std::endl;'
    - '}'
    - ''
    - '// Call the function'
    - 'greet("Alice");'
    - 'greet("Bob");'
    - '```'
    - ''
    - '### Understanding Parameters'
    - ''
    - '**Parameters** (also called arguments) are values you pass into a function:'
    - ''
    - '```python'
    - 'def greet(name):       # "name" is a parameter'
    - '    print(f"Hello, {name}!")'
    - ''
    - 'greet("Alice")         # "Alice" is the argument passed to name'
    - '```'
    - ''
    - 'When you call `greet("Alice")`:'
    - '1. The value `"Alice"` is passed to the function'
    - '2. Inside the function, `name = "Alice"`'
    - '3. The function can use `name` like any other variable'
    - ''
    - '**Multiple parameters:**'
    - '```python'
    - 'def greet(first_name, last_name):'
    - '    print(f"Hello, {first_name} {last_name}!")'
    - ''
    - 'greet("Alice", "Smith")  # Output: Hello, Alice Smith!'
    - '```'
    - ''
    - '### The DRY Principle'
    - '**DRY = Don''t Repeat Yourself**'
    - ''
    - '**Without functions (repetitive):**'
    - '```python'
    - 'print("Hello, Alice!")'
    - 'print("Hello, Bob!")'
    - 'print("Hello, Carol!")'
    - '```'
    - ''
    - '**With functions (DRY):**'
    - '```python'
    - 'def greet(name):'
    - '    print(f"Hello, {name}!")'
    - ''
    - 'greet("Alice")'
    - 'greet("Bob")'
    - 'greet("Carol")'
    - '```'
    - ''
    - 'If you need to change the greeting format, you only change it in ONE place (the function), not everywhere it''s used!'
    - ''
    - '### Function Naming Conventions'
    - 'Choose clear, descriptive names that describe what the function does:'
    - ''
    - '**Good names:** `calculateTotal`, `isValid`, `getUserInput`, `sendEmail`'
    - '**Bad names:** `doStuff`, `func1`, `xyz`, `temp`'
    - ''
    - 'Use verb names since functions perform actions: `get`, `set`, `calculate`, `validate`, `send`, `display`'
    - ''
    - '### Now It''s Your Turn!'
    - 'Practice creating and calling a function with a parameter.'
    question: Write a function called 'greet' that takes a name as a parameter and displays 'Hello, [name]!' to stdout. Then call the function with your own name.
    tokens_for_ai: 'Check their function code in their chosen language.


      Should have:

      - Function definition/declaration named ''greet''

      - Takes one parameter (name)

      - Outputs "Hello, [name]!" to stdout

      - Function is called with a name


      Function syntax varies greatly:

      - Python: def greet(name): \\n    print(f"Hello, {name}!")

      - JavaScript: function greet(name) { console.log(\`Hello, ${name}!\`); }

      - Java: void greet(String name) { System.out.println("Hello, " + name + "!"); }


      Categorize as:

      - correct: Valid function definition and call

      - close: Right idea, minor syntax issues

      - missing_call: Defined function but didn''t call it

      - missing_parameter: Function doesn''t take parameter

      - hardcoded_name: Doesn''t use parameter, outputs fixed name

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Needs help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'For their language, explain:

      - How to define a function

      - How to specify parameters

      - How to use parameters inside function

      - How to call the function

      - Any language-specific syntax (def, function keyword, return types, etc.)

      '
    buckets:
    - correct
    - close
    - missing_call
    - missing_parameter
    - hardcoded_name
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Perfect function in [their language]! You've defined it, used a parameter, and called it. Explain how functions make code reusable.
        metadata_add:
          score: n+3
          concepts_mastered: n+1
        next_section_and_step: functions:step_2
      close:
        ai_feedback:
          tokens_for_ai: Good function structure! Fix the syntax issue and show the corrected version.
        metadata_add:
          score: n+2
        next_section_and_step: functions:step_1
      missing_call:
        ai_feedback:
          tokens_for_ai: You defined the function but didn't call it! Show how to call the function with a name.
        next_section_and_step: functions:step_1
      missing_parameter:
        ai_feedback:
          tokens_for_ai: Your function needs to accept a name parameter! Show how to add parameters in their language.
        next_section_and_step: functions:step_1
      hardcoded_name:
        ai_feedback:
          tokens_for_ai: You need to USE the parameter inside the function, not hardcode a name. Show how to use the parameter.
        next_section_and_step: functions:step_1
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That''s not [their language]! Here''s how to define and call functions in [their language]: [show code]'
        next_section_and_step: functions:step_1
      limited_effort:
        content_blocks:
        - Write a complete function that takes a name parameter and displays a greeting!
        next_section_and_step: functions:step_1
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question about functions in their specific language.
        counts_as_attempt: false
        next_section_and_step: functions:step_1
      off_topic:
        content_blocks:
        - Create a function that takes a name and displays a greeting.
        next_section_and_step: functions:step_1
  - step_id: step_2
    title: Return Values
    content_blocks:
    - '## Functions That Return Values'
    - ''
    - '### Display vs Return: A Critical Difference'
    - 'So far, our `greet` function **displayed** output directly to stdout. But functions can also **return** values that can be used elsewhere. This is a crucial concept that many beginners find confusing at first.'
    - ''
    - '**Displaying (printing):**'
    - '- Shows output to the user immediately'
    - '- Cannot save or reuse the value'
    - '- The function''s only effect is to show text'
    - ''
    - '**Returning:**'
    - '- Sends a value back to the caller'
    - '- The caller can store it, use it in calculations, or display it'
    - '- More flexible and reusable'
    - ''
    - '### Why Return Values?'
    - ''
    - 'Imagine a calculator. It doesn''t just print results on paper - it gives you the answer so you can use it in the next calculation. That''s what return values do!'
    - ''
    - '**Return values let you:**'
    - '- **Calculate and send back results:** `calculateTax(100)` returns `15`'
    - '- **Use results in other operations:** `total = price + calculateTax(price)`'
    - '- **Store results in variables:** `tax = calculateTax(price)`'
    - '- **Chain functions together:** `display(formatCurrency(calculateTotal(items)))`'
    - ''
    - '### Visualizing the Difference'
    - ''
    - '**Function that displays:**'
    - '```python'
    - 'def add(a, b):'
    - '    print(a + b)        # Shows result but can''t reuse it'
    - ''
    - 'add(5, 3)               # Displays: 8'
    - 'result = add(5, 3)      # result = None (nothing returned!)'
    - '```'
    - ''
    - '**Function that returns:**'
    - '```python'
    - 'def add(a, b):'
    - '    return a + b        # Sends result back to caller'
    - ''
    - 'result = add(5, 3)      # result = 8 (can use it!)'
    - 'print(result)           # Displays: 8'
    - 'double = result * 2     # Can do more calculations!'
    - '```'
    - ''
    - '### The Return Statement'
    - ''
    - 'The **return statement** does two things:'
    - '1. Sends a value back to whoever called the function'
    - '2. Immediately exits the function (no code after return runs)'
    - ''
    - '**Syntax in different languages:**'
    - '```python'
    - 'return value            # Python'
    - '```'
    - '```javascript'
    - 'return value;           // JavaScript, Java, C++, etc.'
    - '```'
    - ''
    - '### Return Values in Different Languages'
    - ''
    - '**Python:**'
    - '```python'
    - 'def add(a, b):'
    - '    return a + b'
    - ''
    - 'result = add(5, 3)      # result = 8'
    - 'print(result)           # Display the result'
    - '```'
    - ''
    - '**JavaScript:**'
    - '```javascript'
    - 'function add(a, b) {'
    - '    return a + b;'
    - '}'
    - ''
    - 'let result = add(5, 3);'
    - 'console.log(result);    // Output: 8'
    - '```'
    - ''
    - '**Java:**'
    - '```java'
    - 'int add(int a, int b) {        // int before name = return type'
    - '    return a + b;'
    - '}'
    - ''
    - 'int result = add(5, 3);'
    - 'System.out.println(result);    // Output: 8'
    - '```'
    - 'Note: In statically typed languages like Java/C++, you must declare the return type!'
    - ''
    - '**C++:**'
    - '```cpp'
    - 'int add(int a, int b) {        // int = return type'
    - '    return a + b;'
    - '}'
    - ''
    - 'int result = add(5, 3);'
    - 'std::cout << result << std::endl;  // Output: 8'
    - '```'
    - ''
    - '### Understanding Return Types'
    - ''
    - '**Dynamically typed languages** (Python, JavaScript):'
    - '- Don''t declare return type'
    - '- Can return any type'
    - ''
    - '**Statically typed languages** (Java, C++, C#, Go):'
    - '- Must declare return type before function name'
    - '- `int add(...)` means function returns an integer'
    - '- `String getName(...)` means function returns a string'
    - '- `void doSomething(...)` means function returns nothing'
    - ''
    - '### Using Returned Values'
    - ''
    - 'Once a function returns a value, you can:'
    - ''
    - '**Store it in a variable:**'
    - '```python'
    - 'sum = add(5, 3)        # sum = 8'
    - '```'
    - ''
    - '**Use it in calculations:**'
    - '```python'
    - 'total = add(5, 3) * 2  # total = 16'
    - '```'
    - ''
    - '**Pass it to another function:**'
    - '```python'
    - 'print(add(5, 3))       # Displays 8'
    - '```'
    - ''
    - '**Use it in conditionals:**'
    - '```python'
    - 'if add(5, 3) > 10:'
    - '    print("Big number!")'
    - '```'
    - ''
    - '### Common Mistakes'
    - ''
    - '**Mistake 1: Forgetting to return**'
    - '```python'
    - 'def add(a, b):'
    - '    a + b              # Calculates but doesn''t return!'
    - ''
    - 'result = add(5, 3)     # result = None ❌'
    - '```'
    - ''
    - '**Mistake 2: Printing instead of returning**'
    - '```python'
    - 'def add(a, b):'
    - '    print(a + b)       # Displays but doesn''t return!'
    - ''
    - 'result = add(5, 3)     # Shows 8, but result = None ❌'
    - '```'
    - ''
    - '**Correct:**'
    - '```python'
    - 'def add(a, b):'
    - '    return a + b       # Returns the value ✓'
    - ''
    - 'result = add(5, 3)     # result = 8 ✓'
    - '```'
    - ''
    - '### When to Display vs Return'
    - ''
    - '**Use display (print) when:**'
    - '- The function''s purpose is to show information to the user'
    - '- You won''t need the value later'
    - '- Example: `showWelcomeMessage()`, `displayReport()`'
    - ''
    - '**Use return when:**'
    - '- The function calculates a result you''ll use later'
    - '- You want flexibility (caller decides whether to display)'
    - '- You''re building reusable utility functions'
    - '- Example: `calculateTotal()`, `isValid()`, `formatName()`'
    - ''
    - '**Best practice:** Most functions should return values. Let the caller decide whether to display them.'
    - ''
    - '### Now It''s Your Turn!'
    - 'Practice creating a function that returns a value, then using that returned value.'
    question: Write a function called 'add' that takes two numbers as parameters, returns their sum, and then call it with 5 and 3 and display the result to stdout.
    tokens_for_ai: 'Check their function with return value.


      Should have:

      - Function named ''add''

      - Takes two parameters (numbers)

      - Returns the sum

      - Function is called with 5 and 3

      - Result is displayed to stdout


      Categorize as:

      - correct: Valid function with return, called correctly, result displayed

      - close: Right idea, minor issues

      - displays_instead_of_return: Function outputs instead of returning

      - missing_display: Returns but doesn''t display result

      - missing_call: Defined but didn''t call

      - wrong_language: Used different language

      - limited_effort: Too brief

      - asking_clarifying_questions: Needs help

      - off_topic: Not attempting

      '
    feedback_tokens_for_ai: 'For their language, explain:

      - How to return a value (return keyword or equivalent)

      - Difference between returning and displaying

      - How to capture and use returned value

      - How to display the result


      Some languages (like early BASIC) don''t have explicit return statements - be flexible!

      '
    buckets:
    - correct
    - close
    - displays_instead_of_return
    - missing_display
    - missing_call
    - wrong_language
    - limited_effort
    - asking_clarifying_questions
    - off_topic
    transitions:
      correct:
        ai_feedback:
          tokens_for_ai: Excellent! You've mastered functions with return values in [their language]. Explain the difference between returning and displaying.
        metadata_add:
          score: n+3
          concepts_mastered: n+1
        next_section_and_step: conclusion:step_1
      close:
        ai_feedback:
          tokens_for_ai: Good work! Fix the minor issue and show the correct version.
        metadata_add:
          score: n+2
        next_section_and_step: functions:step_2
      displays_instead_of_return:
        ai_feedback:
          tokens_for_ai: Your function displays the sum instead of returning it. Show how to use return to send the value back.
        next_section_and_step: functions:step_2
      missing_display:
        ai_feedback:
          tokens_for_ai: You're returning the value but not displaying it! Show how to capture the returned value and display it.
        next_section_and_step: functions:step_2
      missing_call:
        ai_feedback:
          tokens_for_ai: You defined the function but didn't call it with 5 and 3! Show how to call it and display the result.
        next_section_and_step: functions:step_2
      wrong_language:
        ai_feedback:
          tokens_for_ai: 'That''s not [their language]! Here''s how return values work in [their language]: [show code]'
        next_section_and_step: functions:step_2
      limited_effort:
        content_blocks:
        - Write a complete function that returns a sum, call it, and display the result!
        next_section_and_step: functions:step_2
      asking_clarifying_questions:
        ai_feedback:
          tokens_for_ai: Answer their question about return values in their language.
        counts_as_attempt: false
        next_section_and_step: functions:step_2
      off_topic:
        content_blocks:
        - Create a function that returns the sum of two numbers.
        next_section_and_step: functions:step_2
- section_id: conclusion
  title: Congratulations, Programmer!
  steps:
  - step_id: step_1
    title: Your Programming Journey
    content_blocks:
    - '## Congratulations! You''ve Learned to Program! 🎉'
    - You've mastered fundamental programming concepts that work in ANY language.
    - ''
    - '**Core concepts you''ve learned:**'
    - ✓ **Output (stdout)** - Displaying information to users
    - ✓ **Variables** - Storing and managing data
    - ✓ **Data Types** - Different kinds of information (strings, numbers, booleans)
    - ✓ **Conditional Logic** - Making decisions with if/else
    - ✓ **Loops** - Repeating actions efficiently
    - ✓ **Functions** - Organizing code into reusable blocks
    - ✓ **Return Values** - Functions that calculate and return results
    - ''
    - '**These concepts are universal!**'
    - Whether you continue with your chosen language or learn another one, these fundamentals remain the same.
    - ''
    - '**Next steps in your programming journey:**'
    - '- Practice by building small projects'
    - '- Learn about arrays/lists and dictionaries/maps'
    - '- Explore object-oriented programming (classes and objects)'
    - '- Study algorithms and data structures'
    - '- Build something that interests you!'
    - ''
    - '**Remember:** The best way to learn programming is by writing code and solving problems.'
    question: What would you like to build with your new programming skills? What kind of program interests you?
    tokens_for_ai: 'This is a reflection question.


      Based on their answer, provide encouragement and suggestions for their specific language.

      Suggest projects appropriate for beginners in their chosen language.


      Categorize as:

      - specific_project: Has a specific project idea

      - general_interest: General area of interest (games, websites, data, etc.)

      - exploring: Still exploring what to build

      - limited_effort: Very brief

      - off_topic: Unrelated

      '
    feedback_tokens_for_ai: 'Provide enthusiastic, personalized feedback!


      Reference their specific programming language.

      Suggest beginner-friendly projects for their language and interests.

      Encourage them to start small and build up.

      Remind them that the programming community is welcoming and helpful.


      Celebrate their completion of the fundamentals!

      '
    buckets:
    - specific_project
    - general_interest
    - exploring
    - limited_effort
    - off_topic
    transitions:
      specific_project:
        ai_feedback:
          tokens_for_ai: Great project idea! For [their language], suggest how they might approach that project. Recommend beginner-friendly libraries or frameworks if applicable. Encourage them to start with a simple version.
        metadata_add:
          activity_completed: 'true'
      general_interest:
        ai_feedback:
          tokens_for_ai: Great area of interest! For [interest area] in [their language], suggest 2-3 beginner projects they could start with. Provide encouragement and resources.
        metadata_add:
          activity_completed: 'true'
      exploring:
        ai_feedback:
          tokens_for_ai: Exploration is great! For [their language], suggest 3-4 different types of beginner projects they could try (web, automation, data analysis, games, etc.) to discover what they enjoy.
        metadata_add:
          activity_completed: 'true'
      limited_effort:
        ai_feedback:
          tokens_for_ai: Congratulate them on completing programming fundamentals in [their language]! Encourage them to build something, even if it's small.
        metadata_add:
          activity_completed: 'true'
      off_topic:
        content_blocks:
        - Think about what interests you! What kind of program would you like to create with your new skills?
        next_section_and_step: conclusion:step_1