codejunkie99/gf-learn-ctx

GF-Learn-Ctx — Contextual Learning

Philosophy

Teaching happens WITHIN the workflow, not in a separate mode. The first time a user encounters a concept, explain it briefly. Never explain the same concept twice.

First-Encounter Explanations

When GateFlow generates code using a concept for the first time, include a 2-3 sentence explanation marked with [Learn]:

Generated sync_2ff.sv

[Learn] This is a 2-flip-flop synchronizer. When a signal crosses
between clock domains, it can be captured during a metastable state.
Two back-to-back flip-flops reduce metastability probability to safe
levels. For multi-bit signals, use a Gray code FIFO or handshake instead.

Concept Tracking

Check ~/.gateflow/profile.json before explaining:

{
  "concepts_introduced": ["cdc", "fsm", "pipeline", "fifo", "axi"]
}

If concept is in the list, skip the explanation. After explaining, add the concept to the list.

Concept Library

| Concept | Trigger | Explanation Focus | |---------|---------|-------------------| | cdc | 2FF sync, async FIFO | Metastability, why 2 FFs | | fsm | State machine code | Two-process pattern, encoding | | pipeline | Pipeline register, stage, valid_q | Breaks long paths into stages for higher clock frequency | | fifo | FIFO instantiation | Full/empty, pointer math | | axi | AXI interface | Valid/ready handshake rules | | formal | SVA properties | Bounded proof, counterexample | | synthesis | Yosys output | LUTs vs FFs, resource meaning | | constraints | Pin mapping | IOSTANDARD, voltage rails | | vhdl | VHDL code | Comparison with SystemVerilog | | backpressure | ready signal, stall | Consumer tells producer to stop via ready deassertion | | clock_gating | gclk, ICG cell | Stops clock to idle registers, saves dynamic power | | reset_synchronizer | rst_sync, async assert/sync deassert | Prevents metastability on reset release | | gray_code | bin2gray, gray2bin | Changes one bit per increment, safe for CDC pointers | | dual_port_ram | sdp_ram, true dual-port | Two independent access ports, FPGA BRAM native | | arbitration | arbiter, grant, round-robin | Resolves contention for shared resources | | bus_protocol | AXI, Wishbone, APB | Defines master/slave communication rules | | timing_closure | slack, critical path | All paths meet setup/hold at target frequency | | register_file | regfile, read/write ports | Small fast memory with multiple read ports | | shift_register | LFSR, serial-to-parallel | Moves data one position per clock | | priority_encoder | casez, leading zero | Outputs index of highest-priority active bit | | barrel_shifter | rotate, variable shift | Variable-distance shift via mux cascade | | interrupt_controller | IRQ, pending, mask | Aggregates and prioritizes interrupt sources | | dma | descriptor, scatter-gather | Transfers data between memory without CPU |

Generative Exercises

When user asks to practice:

1. Generate a buggy version of a recent design
2. Ask user to find the error
3. Reveal answer with explanation

Example:

Want to practice? Here's a FIFO with a subtle bug.
Find what's wrong:

[buggy code]

Hint: Look at the full/empty logic...

Cross-HDL Explanations

When a SV user sees VHDL for the first time:

[Learn] VHDL uses 'signal' instead of 'logic', and 'process'
instead of 'always_ff'. The semantics are similar — sequential
logic with sensitivity lists. VHDL is more verbose but equally
capable for synthesis.

Cross-Reference Linking

When explaining a concept, append related GateFlow links:

• CDC -> "Use /gf-ip add cdc_2ff for a drop-in synchronizer."
• FIFO -> "Use /gf-ip add fifo_async for a verified async FIFO."
• Protocol -> "See /gf-protocols for AXI/SPI/UART references."
• Practice -> "Try /gf-learn <topic> for exercises."

Spaced Repetition

| Sessions Since Last Use | Action | |---|---| | 3-5 | Brief reminder (1 sentence) | | 6-10 | Medium reminder (2 sentences + link) | | 11+ | Full re-explanation |

Integration Hooks

Inject micro-lessons at these points in /gf orchestration:

• Post-codegen: scan generated code for new concepts
• Post-ip-add: explain the concept behind the IP block
• Post-lint-fail: teach concept if error involves one (e.g., latch = incomplete case)
• Post-sim-fail: explain if failure involves X-propagation or CDC
• Post-plan: introduce concepts user hasn't seen