codejunkie99/gf-learn

allowed-tools:

• Read
• Write
• Bash
• Task
• AskUserQuestion

GateFlow Learning Mode

Interactive SystemVerilog learning with exercises and solution review.

Usage

/gf-learn                    # Start learning session, pick topic
/gf-learn <topic>            # Get exercises on specific topic
/gf-learn check <file>       # Submit solution for review
/gf-learn hint               # Get hint for current exercise
/gf-learn solution           # Show solution (gives up)

Topics

| Topic | Exercises | |-------|-----------| | basics | Signals, always blocks, assignments | | fsm | State machines, encodings, transitions | | fifo | Synchronous FIFOs, pointers, full/empty | | pipeline | Valid/ready, backpressure, stages | | cdc | Clock domain crossing, synchronizers | | arbiter | Round-robin, priority, grant logic | | memory | RAMs, ROMs, register files | | protocol | AXI-lite, Wishbone, handshakes | | verification | Assertions, SVA properties, coverage | | optimization | Timing closure, resource sharing, pipelining tradeoffs |

Workflow

Step 1: Generate Exercise

When user runs /gf-learn <topic>:

1. Present 3-5 exercises of increasing difficulty
2. Format each exercise as:

## Exercise X: <Title>

**Difficulty:** Beginner/Intermediate/Advanced

**Requirements:**
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

**Interface:**
```systemverilog
module exercise_name (
    input  logic clk,
    input  logic rst_n,
    // ... define ports
);

Test Cases:

1. When X happens, Y should occur
2. Edge case: ...

Starter File: exercises/exercise_X.sv

3. Create starter file in `exercises/` directory
4. **STOP and wait for user to attempt solution**

### Step 2: Wait for User

After presenting exercises, say:

Your turn! Edit the file and run /gf-learn check exercises/exercise_X.sv when ready.

Need help? Run /gf-learn hint for a hint.

**DO NOT proceed until user submits with `/gf-learn check`**

### Step 3: Review Solution

When user runs `/gf-learn check <file>`:

1. Spawn the `gateflow:sv-tutor` agent to review
2. Present feedback without giving away answers
3. If solution passes, offer next exercise

### Step 4: Hints (on request)

When user runs `/gf-learn hint`:

1. Give progressive hints (hint 1 is vague, hint 3 is specific)
2. Track hint count per exercise
3. Never give full solution in hints

## Exercise Templates

### Beginner: 4-bit Counter

Create a 4-bit counter with:

• Synchronous reset
• Enable signal
• Wrap-around at max value

### Intermediate: Sync FIFO

Create a synchronous FIFO with:

• Parameterized WIDTH and DEPTH
• Full and empty flags
• No overflow/underflow

### Advanced: AXI-Lite Slave

Create an AXI-Lite slave with:

• 4 read/write registers
• Proper handshaking
• Address decoding

## Key Rules

1. **ALWAYS wait for user** after presenting exercises
2. **NEVER show solution** unless explicitly asked with `/gf-learn solution`
3. **Track progress** in `.gateflow/learn/progress.json`
4. **Encourage** - learning is hard, be supportive

## Difficulty Scaling

| Level | Score Range | Criteria |
|---|---|---|
| Beginner | 0-99 | Single always block, basic signals |
| Intermediate | 100-299 | Multi-block, FSMs, parameterization |
| Advanced | 300-499 | Multi-clock, protocols, optimization |
| Expert | 500+ | Full subsystems, cross-cutting concerns |

Advancement: +30 no hints, +20 one hint, +10 two+ hints, +10 lint-clean bonus, -10 solution revealed.

## Grading Rubric

| Grade | Criteria |
|---|---|
| A (Excellent) | Lint-clean, correct reset, parameterized, assertions included |
| B (Good) | Correct, minor lint warnings, reasonable naming |
| C (Acceptable) | Correct for basic cases, multiple warnings, hardcoded values |
| D (Needs Work) | Functional errors, missing reset, width mismatches |

Automated checks: lint (20%), functional correctness (40%), style (15%), parameterization (10%), edge cases (10%), assertions (5%).

## Progress Persistence

Store in `.gateflow/learn/progress.json`:
```json
{"user_level": "intermediate", "total_score": 185, "topics": {"basics": {"level": "intermediate", "score": 90, "exercises_completed": 3}}}

Challenge Mode

/gf-learn challenge <topic> -- timed exercises with scoring.

| Difficulty | Time Limit | Bonus Threshold | |---|---|---| | Beginner | 15 min | 8 min (2x points) | | Intermediate | 25 min | 15 min (2x points) | | Advanced | 40 min | 25 min (2x points) |