TexLeeV/cursor-socratic-mentor
Language-agnostic Cursor mentoring rules: Q/A/R in code, skill profiles, optional lesson-authoring guide.
Actual rules from this repo
Path in source repo: .cursor/rules/learning-module-implementation.mdc · format: mdc
---
description: How to build Socratic learning modules with runnable lessons and Q/A/R prompts
alwaysApply: false
---
# Learning Module Implementation
Optional methodology for authoring learning modules. Separate from the Socratic core and `profiles/`.
## Scope
- **USE** when creating or extending a learning module.
- **MODULE** = lesson files that teach one topic via runnable checks plus inline Q/A/R.
## Workflow
**MUST** complete and validate one lesson file before starting the next:
1. Write the full lesson file
2. Enable it in the project's build or test setup
3. Build and run that file's checks
4. Fix failures immediately
5. Start the next file only after this one passes
**MUST NOT** batch-implement or batch-fix across multiple files.
## Lesson file requirements
Each lesson file **MUST** include:
- Header: time estimate, difficulty, topic scope
- Setup that resets shared state before every check
- 3-6 checks with rising difficulty
- Q/A/R at key learning points
- Mix of worked examples and thinking prompts
- At least one observable signal (print, assert, log, trace, counter, or equivalent)
### Fill level
- **DEFAULT:** filled demonstration code (`all-ops`)
- **GOAL:** mental model and Q/A/R, not retyping known syntax
- **OPTIONAL:** learner TODOs only when `fill: minimal` or `fill: trivial-only` is intentional
### Independence
**MUST:**
- Run each lesson file in isolation
- Keep each check independent of other checks
- Reset all shared state in setup
- Avoid order dependence between checks
- Avoid side effects that affect later checks
### Difficulty labels
- **Easy:** main idea, happy path
- **Moderate:** realistic use, common pitfalls
- **Hard:** edge cases, failure modes, awkward boundaries
**MUST** assume surface syntax is known. **MUST** focus questions on mechanisms and failure modes.
### Q/A/R
**FORM** (use the active language's line-comment prefix):
```
# Q: [Ask how the mechanism works]
# A:
# R:
```
**MUST:**
- Ask how/why, not trivia
- Tie questions to observable signals
- Challenge topic-relevant rules (contracts, ownership, sharing, structure)
- Require answers that can be checked against code or output
**PLACEMENT:**
- **MUST** put Q/A/R immediately after the behavior being questioned
- **SHOULD** keep Q/A/R inside the check
- **MAY** place Q/A/R by a helper only when the question is about that helper's contract
## Size targets
| Metric | Target |
|--------|--------|
| Lines per file | 200-400 (max 450) |
| Checks per file | 3-6 |
| Q/A/R pairs per file | 10-20 |
| Learner time per file | 1-4 hours |
**SHOULD** keep teaching logic in the checks. **MAY** extract helpers for clarity or reuse only.
## Post-file checklist
After each file, verify:
- [ ] Builds without errors
- [ ] All checks pass
- [ ] Q/A/R present after relevant observable behavior
- [ ] Within size target; few or no one-off helpers
- [ ] Observable signal available to the learner
- [ ] Difficulty progresses Easy → Hard
- [ ] No dependence on other lesson files or checks
## Anti-patterns
**MUST NOT:**
- Finish all files before running any
- Skip running checks after a build
- Continue while checks fail
- Share hidden state across files or checks
- Hide important logic in single-use helpers
- Exceed ~450 lines per file
**MUST:**
- Validate each file before moving on
- Keep checks self-contained
- Keep each question next to what was just observed
## If a file exceeds ~400 lines
Ask and act on:
1. Are helpers used only once?
2. Does the file cover more than one idea?
3. Should it split into two lesson files?
Why this is listed
This repository appears on Cursor Rules Live because it matches the tracker's GitHub Search criteria (cursor-rules) and was active in the recent indexing window. The tracker refreshes every 15 minutes, so the metadata above reflects the state at the most recent index pass. If the data here looks stale, the source repository may have been archived or moved out of the tracked topic; the next cron tick will reconcile.