codewhale.history 2.8.6 → 2.8.8

package/README.md

@@ -78,8 +78,11 @@ Git already has your back.
 
 ### `//teach-me`
 An interactive code-teaching quiz that randomly selects real snippets from your
-current project and quizzes you on what they do and how they work. Great for
-onboarding to a new codebase or sharpening your language skills.
+current project. Two modes across five difficulty levels:
+
+- **Passive** (default): Explain what the code does and how it works.
+- **Interactive**: Lines are removed from the file — you restore the missing
+  logic, then say `done` for the model to verify your work.
 
 **Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
 `drill me`
@@ -90,6 +93,7 @@ onboarding to a new codebase or sharpening your language skills.
 |----------|---------|-------------|
 | Language | `teach me python` | Restrict to Python, TypeScript, Rust, Go, Java… |
 | Level | `teach me level 3` or `teach me l3` | Set difficulty 1–5 (default: 3) |
+| Mode | `teach me interactive` | Reconstruction mode — you restore missing lines |
 | Scope | `teach me services/` | Narrow to a specific file or folder |
 | Concept | `teach me decorators` | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |
 
@@ -104,10 +108,11 @@ onboarding to a new codebase or sharpening your language skills.
 | 5 | 25–55 | Metaclasses, complex async patterns, multi-threading, architectural glue |
 
 **Mid-round commands:** `hint` (get a nudge) · `skip` (see the answer) ·
-`next` (draw a new snippet) · `level N` · `easier` · `harder` · `stop`
+`next` (draw a new snippet) · `level N` · `easier` · `harder` ·
+`interactive` · `passive` · `done` (verify restoration) · `stop`
 
-**At the end** you get a session summary: rounds completed, files covered, what
-you're strong on, what to review, and a suggested next level.
+**At the end** you get a session summary: rounds completed, mode, files covered,
+what you're strong on, what to review, and a suggested next level.
 
 ## Requirements
 - Node.js (for the `codewhale-history` command)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codewhale.history",
-  "version": "2.8.6",
+  "version": "2.8.8",
   "description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
   "bin": {
     "codewhale-history": "./_list_sessions.js",

package/skills/teach-me/SKILL.md

@@ -1,14 +1,18 @@
 ---
 name: teach-me
-description: Interactive code-teaching quiz. Selects random snippets from the current project and quizzes the user on application logic and language semantics. Triggered by 'teach me', 'quiz me', 'test my knowledge', 'code quiz', or 'drill me'. Supports difficulty levels 1–5.
+description: Interactive code-teaching quiz. Selects random snippets from the current project and quizzes the user on application logic and language semantics. Triggered by 'teach me', 'quiz me', 'test my knowledge', 'code quiz', or 'drill me'. Supports difficulty levels 1–5 and two modes: passive (explain) and interactive (reconstruct).
 ---
 
 # Teach Me — Interactive Code Quiz
 
 An interactive teaching session that randomly selects code snippets from the
-current project, presents them to the user, asks the user to explain them, and
-provides constructive feedback on both **application logic** (what the code
-accomplishes) and **language mechanics** (syntax and semantics).
+current project. Two modes:
+
+- **Passive** (default): presents code, asks the user to explain it, and
+  provides constructive feedback on **application logic** (what the code
+  accomplishes) and **language mechanics** (syntax and semantics).
+- **Interactive**: removes lines from the file; the user restores them and
+  says `done`; the model diffs against the original and gives feedback.
 
 ## Session Trigger
 
@@ -32,7 +36,16 @@ Optionally followed by modifiers:
   `teach me error handling`, `teach me type hints`, `teach me threading`
 
 Modifiers combine freely: `teach me decorators level 4`,
-`teach me async services/`, `teach me generators l2`
+`teach me async services/`, `teach me generators l2`,
+`teach me level 2 interactive`, `teach me interactive decorators`
+
+Two modes are available, orthogonal to difficulty:
+
+- **`passive`** (default) — You explain what the code does and how it works.
+- **`interactive`** — Lines are removed from the file; you restore the missing
+  logic. When done, say `done` or `check my work` and the model verifies.
+
+Switch modes mid-session with `interactive` or `passive`.
 
 If no level is specified, default to **level 3** and adjust based on
 performance across rounds.
@@ -57,7 +70,9 @@ specified a language, filter by extension.
 ### 2. Selection — Pick a Snippet
 
 Randomly select a file from the index, then randomly select a function,
-method, or logical block from that file. Use these rules:
+method, or logical block from that file. **Re-read the file before each round**
+to ensure the snippet reflects the current on-disk state — the code may have
+changed since the session started. Use these rules:
 
 #### Good Snippets (select these)
 - Functions or methods 5–55 lines long (after stripping docstrings and blank lines)
@@ -110,13 +125,76 @@ match, relax the filter and note the fallback to the user).
 | `type hints` | `:` type annotation in function signatures or variable assignments |
 | `threading` | `Thread(`, `Lock(`, `Queue(`, or `threading.` |
 
+### 2b. Interactive Mode — Reconstruction
+
+When mode is `interactive`, each round follows a different flow from passive
+explanation. The model removes lines from the file and the user restores them.
+
+#### Lines Removed by Level
+
+| Level | Snippet lines | Lines removed |
+|-------|--------------|---------------|
+| 1     | 5–15         | 1             |
+| 2     | 8–20         | 1–2           |
+| 3     | 12–30        | 1–2           |
+| 4     | 18–45        | 2–3           |
+| 5     | 25–55        | 2–3           |
+
+#### Lines to Remove — Selection Heuristic
+
+- **Remove:** assignment statements, conditional branches, loop bodies, return
+  statements, function calls — lines that carry semantic weight and that
+  downstream lines depend on. Removing them should break the function.
+- **Never remove:** imports, blank lines, closing braces/brackets/parens,
+  decorator lines, function/class signatures, docstrings, comments.
+- Replace each removed span with a single placeholder comment:
+  `# ... N lines removed ...`
+- After removing lines from the file, **save the original lines** in memory for
+  later diffing against the user's restoration.
+
+#### Interactive Mode Per-Round Flow
+
+1. **Select** a snippet using the standard rules (section 2).
+2. **Save** the original lines in memory.
+3. **Remove** 1–3 lines from the actual file on disk using `edit_file`.
+4. **Present** the gapped snippet with the placeholder and the original line
+   numbers.
+5. **Instruct:** "Open `<file>`, restore the missing logic at the gap.
+   Say `done` or `check my work` when ready."
+6. **Wait.** Do not evaluate, hint, or proceed until the user signals
+   completion.
+7. **Re-read** the file. Diff the user's restored lines against the saved
+   original.
+8. **Feedback** (see Interactive Evaluation below). Offer to restore the
+   original if the user wants to undo.
+
+#### Interactive Mode Presentation Format
+
+```
+---
+## Round N — Level X · interactive · concept | `path/to/file.py` (lines A–B)
+
+```python
+ 48      risk_amount = capital * (risk_per_trade / 100)
+ 49      # ... 2 lines removed ...
+ 50      return max(shares, 0)
+```
+
+⚠️ **Interactive — Reconstruction.** 2 lines have been removed (originally
+lines 49–50). Open `path/to/file.py`, find the placeholder, and restore the
+missing logic. When you're done, say **`done`** or **`check my work`**.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
 ### 3. Presentation — Show the Snippet
 
 For each round, present the snippet with its filename:
 
 ```
 ---
-## Round N — Level X · concept | `path/to/file.py` (lines A–B)
+## Round N — Level X · [interactive|passive] · concept | `path/to/file.py` (lines A–B)
 
 ```python
  42  def calculate_position_size(
@@ -133,8 +211,8 @@ For each round, present the snippet with its filename:
  53      return max(shares, 0)
 ```
 
-**Your turn:** Explain what this code does (application logic) AND how it
-works (syntax and semantics). Include any edge cases you notice.
+**Your turn:** (Passive mode) Explain what this code does (application logic)
+AND how it works (syntax and semantics). Include any edge cases you notice.
 
 Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
 ---
@@ -145,6 +223,7 @@ Guidelines:
 - Strip only excessive blank lines; keep natural spacing
 - Show the function/class signature with its decorators
 - Show the filename and line range in the header
+- The mode tag (`· interactive` or `· passive`) always appears in the header
 - The `· concept` portion only appears when a concept is targeted; omit it during free-play rounds
 - If the snippet depends on one obvious external type or constant, include a
   brief inline note
@@ -176,6 +255,46 @@ Evaluate across two dimensions, scaled to the current difficulty level.
 | 4 | Generator mechanics (`yield`), `async`/`await` internals, descriptor protocol, closures, threading primitives |
 | 5 | Coroutine internals, metaclass programming, GIL implications, memory model, `__slots__`, MRO, weak references |
 
+#### C. Interactive Mode Evaluation
+
+When mode is `interactive`, evaluation is a diff between the user's restored
+lines and the saved original:
+
+| Outcome | Criteria | Feedback |
+|---------|----------|----------|
+| **Exact match** | Lines match character-for-character | ✅ Perfect. Note what the lines do and why they matter. |
+| **Semantic match** | Same logic, different variable names or formatting | ✅ Good — logic is correct. Note the stylistic difference. |
+| **Partial match** | Some lines correct, some missing/wrong | Point out which line(s) are correct and which need work. Treat as strike 1 or 2 depending on how much is missing. |
+| **No match** | Lines are absent or entirely wrong | Strike-1 nudge toward the missing logic. |
+
+Do not use the standard three-strikes verbal pipeline for interactive mode.
+Instead, use targeted hints about what the missing lines should compute:
+
+**Strike 1** — Category nudge:
+```
+Not quite. Think about what calculation happens between [visible line above
+the gap] and [visible line below the gap].
+```
+
+**Strike 2** — Near-explicit hint:
+```
+You need to [specific operation — e.g., "divide risk_amount by price_risk
+and guard against division by zero"].
+```
+
+**Strike 3** — Reveal the original lines and move to the next round:
+```
+Here's what was removed:
+```python
+ 49      price_risk = abs(entry_price - stop_loss)
+ 50      if price_risk == 0:
+ 51          return 0
+ 52      shares = int(risk_amount / price_risk)
+```
+
+After strike 3, restore the original lines in the file and proceed to the
+next round automatically (no "another round?" prompt).
+
 #### Weighted Evaluation for Targeted Concepts
 
 When a concept is targeted (e.g., `teach me decorators`), bias the
@@ -254,15 +373,19 @@ nailed everything at-level, say so and highlight the nuance they caught.
 | `level N` / `lN` (e.g. `level 5`, `l2`) | Adjust difficulty for subsequent rounds. |
 | `easier` | Decrease level by 1 (minimum 1). |
 | `harder` | Increase level by 1 (maximum 5). |
-| `stop` / `done` / `end` | End session. Deliver summary. |
+| `interactive` | Switch to interactive (reconstruction) mode for subsequent rounds. |
+| `passive` | Switch to passive (explanation) mode for subsequent rounds. |
+| `done` / `check my work` | (Interactive mode only) Signal that missing lines have been restored. Triggers verification. |
+| `stop` / `end` | End session. Deliver summary. |
 
 ### 5. Loop — Keep Going
 
 After a successful evaluation or a `next` skip, ask:
-"Another round? (yes / no / level N / stop)"
+"Another round? (yes / no / level N / interactive / passive / stop)"
 
 After a strike-3 reveal, do **not** ask — proceed directly to the next
-round with: "Round N+1 — Level X | `file.py`"
+round with:
+"Round N+1 — Level X · [mode] | `file.py`"
 
 ### End-of-Session Summary
 
@@ -272,7 +395,7 @@ When the user says `stop`:
 ## Session Summary
 
 Rounds completed: 5
-Level played: 3
+Level played: 3 · Mode: passive
 Files covered:
   - services/position_sizer.py (rounds 1, 4)
   - agents/news_agent.py (round 2)
@@ -314,12 +437,24 @@ criteria for the Mechanics axis:
   do not squeeze in another round.
 - **Stay in teaching mode.** Do not fix bugs, refactor, or edit code during a
   teaching session unless the user explicitly asks to switch modes.
+- **Interactive mode file edits.** The model MAY remove lines from files to set
+  up reconstruction exercises. The model MUST NOT add or modify lines — only
+  the user restores code. After the session ends, offer to restore any
+  remaining gapped files.
+- **Restore on session end.** When the session ends, check whether any files
+  still contain `# ... N lines removed ...` placeholders from interactive mode.
+  If so, offer to restore the original lines.
 
 ## Verification
 
 After each round, confirm:
 - The snippet was actually read from the file (not hallucinated)
 - The line numbers match the source
+- The mode was correctly announced in the round header
 - The feedback accurately describes what the code does
 - No secrets or PII were exposed
 - The strike count was tracked correctly
+- (Interactive mode) The original lines were saved before the edit
+- (Interactive mode) The file was re-read before evaluating the user's restoration
+- (Interactive mode) Feedback accurately describes any differences from the original
+- (Interactive mode) Gapped files were restored or the user was offered restoration on session end