gf-learn

name	gf-learn
description	SystemVerilog learning mode — generates exercises, reviews solutions, and teaches RTL design patterns. Use when the user wants to learn SystemVerilog, practice hardware design, get exercises, or understand verification methodology.
user-invocable	true
triggers	["teach me SystemVerilog","give me an exercise","learning mode","practice RTL design","review my solution","SystemVerilog tutorial","help me learn hardware design","generate a learning exercise"]

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)