# Gf Learn Ctx

> Contextual learning — micro-lessons embedded in workflow output. Explains hardware concepts on first encounter, tracks what has been taught, generates practice exercises on demand. Used internally by orchestrator — not typically invoked directly.

- Skill: `codejunkie99/gf-learn-ctx` (Agent Skill)
- Install (CLI): `npx skillmds@latest add codejunkie99/gf-learn-ctx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codejunkie99/gf-learn-ctx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: codejunkie99 (https://skillmd.com/u/codejunkie99)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/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:

```json
{
  "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