codewhale.history 2.7.0 → 2.8.1

package/README.md

@@ -1,6 +1,6 @@
 # CodeWhale Tools Pack
 
-A portable pack of global CodeWhale commands: `//tools`, `//history`, and `//snapshot`.
+A portable pack of global CodeWhale commands: `//tools`, `//history`, `//snapshot`, and `//teach-me`.
 
 Cross-platform — works on Windows, Mac, Linux.
 
@@ -14,6 +14,7 @@ tools_for_codewhale/
 ├── skills/
 │   ├── history/SKILL.md      # //history — calls codewhale-history
 │   ├── snapshot/SKILL.md     # //snapshot — pre-edit file backups
+│   ├── teach-me/SKILL.md     # //teach-me — interactive code quiz
 │   └── tools/tools-skill/SKILL.md  # //tools — lists all available tools
 ├── instructions.md         # Trigger config (drop into any .codewhale/)
 └── README.md               # This file
@@ -40,6 +41,7 @@ codewhale-tools-install -p <target-path>        # specific workspace
 - **`//tools`** — lists every tool available in the current session
 - **`//history`** — lists all chat sessions for the current workspace with cost totals
 - **`//snapshot`** — toggle pre-edit file backups (`on`, `off`, `status`)
+- **`//teach-me`** — interactive code quiz that tests your knowledge of the current codebase
 
 ## Requirements
 - Node.js (for the `codewhale-history` command)

package/instructions.md

@@ -8,3 +8,6 @@ When the user types `//history`, immediately load the `history` skill (from `his
 
 ## //snapshot Command
 When the user types `//snapshot`, immediately load the `snapshot` skill (from `snapshot/SKILL.md`) and follow its instructions. `//snapshot on` enables automatic pre-edit file backups to `_snapshots/` when no Git repo is present. `//snapshot off` disables it. `//snapshot status` reports the current state. This works in all sessions once the skill is installed globally.
+
+## //teach-me Command
+When the user types `//teach-me` (or any trigger phrase from the teach-me skill, including `teach me`, `quiz me`, `test my knowledge`, `code quiz`, `drill me`), immediately load the `teach-me` skill (from `teach-me/SKILL.md`) and start an interactive code-teaching quiz. Supports optional modifiers: `teach me <language>`, `teach me level N`, `teach me <file/module>`. This works in all sessions once the skill is installed globally.

package/package.json

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

package/skills/teach-me/SKILL.md

@@ -0,0 +1,325 @@
+---
+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.
+---
+
+# 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).
+
+## Session Trigger
+
+Activate when the user says any of:
+
+- `teach me`
+- `quiz me`
+- `test my knowledge`
+- `code quiz`
+- `drill me`
+- `explain this codebase`
+
+Optionally followed by modifiers:
+
+- `teach me python` — restrict to a specific language
+- `teach me level 3` / `teach me l3` — set difficulty (1–5)
+- `teach me <file or module>` — narrow scope to a specific file, directory, or module
+- `teach me <concept>` — target a specific language concept. Examples:
+  `teach me decorators`, `teach me async`, `teach me generators`,
+  `teach me context managers`, `teach me comprehensions`,
+  `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`
+
+If no level is specified, default to **level 3** and adjust based on
+performance across rounds.
+
+## Session Lifecycle
+
+### 1. Discovery — Map the Project
+
+Before presenting the first snippet:
+
+```
+A. Use file_search or list_dir to find source directories.
+B. Use grep_files to count function/class definitions per file.
+C. Build a mental index: file path → rough function/class count.
+D. Determine the primary language(s) from file extensions.
+E. Report: "Found ~N candidates across M files. Starting at level X. Ready."
+```
+
+If the user specified a scope, apply it during discovery. If the user
+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:
+
+#### Good Snippets (select these)
+- Functions or methods 5–55 lines long (after stripping docstrings and blank lines)
+- Classes with 10–60 lines of method bodies
+- Blocks containing: decorators, comprehensions, generators, context managers,
+  async/await, error handling, design patterns, algorithm implementations,
+  non-obvious control flow, or domain-specific logic
+- Code that can be understood with at most one level of external context
+
+#### Avoid (skip these)
+- Pure getters/setters/properties (single-line `return self._x`)
+- Imports, module-level constants, config dicts, `__init__.py` with only imports
+- Boilerplate: `if __name__ == "__main__"`, argument parsers, logging setup
+- Dunder methods that only delegate
+- Functions shorter than 5 effective lines or longer than 60 lines
+- Code that requires reading 3+ other files to understand
+
+#### Difficulty → Line Ranges
+
+| Level | Lines  | Suitable patterns |
+|-------|--------|-------------------|
+| 1     | 5–15   | Straight-line logic, `if`/`else`, basic function calls |
+| 2     | 8–20   | Loops, list/dict operations, simple `try`/`except` |
+| 3     | 12–30  | Comprehensions, decorators, `with` statements, multiple branches |
+| 4     | 18–45  | Generators, `async`/`await`, descriptors, threading, closures |
+| 5     | 25–55  | Metaclasses, complex async patterns, multi-threading with synchronization, architectural glue code |
+
+#### No-repeats rule
+Track which snippets have been shown this session (file + line range).
+Do not repeat a snippet unless the user explicitly asks or all candidates
+are exhausted. Prefer cycling through files before returning to the same
+file.
+
+#### Concept Targeting
+
+When the user targets a specific concept, filter snippets to ensure they
+contain that concept. After selecting a random candidate, verify it with
+`grep_files` on the file for the concept signal. If the candidate doesn't
+match, pick another random snippet (retry up to 10 times; if still no
+match, relax the filter and note the fallback to the user).
+
+| Trigger phrase | Signal to verify in the snippet |
+|---|---|
+| `decorators` | `@` immediately above a `def` line |
+| `async` | `async def` or `await` |
+| `generators` | `yield` |
+| `context managers` | `with` statement or `__enter__`/`__exit__` |
+| `comprehensions` | `for ... in` inside `[`, `{`, or `(` |
+| `error handling` | `try:`, `except`, or `finally` |
+| `type hints` | `:` type annotation in function signatures or variable assignments |
+| `threading` | `Thread(`, `Lock(`, `Queue(`, or `threading.` |
+
+### 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)
+
+```python
+ 42  def calculate_position_size(
+ 43      capital: float,
+ 44      risk_per_trade: float,
+ 45      entry_price: float,
+ 46      stop_loss: float
+ 47  ) -> int:
+ 48      risk_amount = capital * (risk_per_trade / 100)
+ 49      price_risk = abs(entry_price - stop_loss)
+ 50      if price_risk == 0:
+ 51          return 0
+ 52      shares = int(risk_amount / price_risk)
+ 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.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+Guidelines:
+- Include realistic line numbers (1-based from the actual file)
+- 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 `· 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
+- **Before presenting, scan for secrets.** Redact API keys, tokens, passwords,
+  connection strings with `[REDACTED]`. Skip snippets that are entirely
+  secrets or contain PII/email addresses/personal identifiers.
+
+### 4. Evaluation — Assess the Answer
+
+Evaluate across two dimensions, scaled to the current difficulty level.
+
+#### A. Application Logic (what the code does in the project)
+
+| Level | Expectation |
+|-------|-------------|
+| 1 | Names what the function does at a basic level |
+| 2 | Identifies inputs, outputs, and at least one edge case |
+| 3 | Explains the module role, failure modes, and upstream/downstream connections |
+| 4 | Identifies the design pattern, multi-component interaction, and concurrency edge cases |
+| 5 | Explains architectural role across system layers, performance implications, and subtle bugs or limitations |
+
+#### B. Language Mechanics (syntax and semantics)
+
+| Level | Expectation |
+|-------|-------------|
+| 1 | Basic types, function definition syntax, simple `if`/`else` |
+| 2 | Loop mechanics, list/dict operations, basic `try`/`except`, string formatting |
+| 3 | Comprehensions, decorator syntax and effect, `with` / context managers, type hints, exception chaining |
+| 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 |
+
+#### Weighted Evaluation for Targeted Concepts
+
+When a concept is targeted (e.g., `teach me decorators`), bias the
+evaluation toward that concept:
+
+- **Mechanics axis:** The targeted concept carries extra weight. Missing
+  it is a significant gap even if other mechanics are handled well.
+- **Strike hints:** Always steer strike 1 toward the targeted concept
+  before hinting about any other missed item.
+- **Feedback ordering:** List the targeted concept first under "What you
+  missed" or "What you could sharpen."
+- **Success bar:** To "meet expectations," the user must correctly
+  explain the targeted concept at the current level's depth.
+
+#### The Three-Strikes Rule
+
+If the user's answer does **not** meet the expectations for the current
+difficulty level:
+
+**Strike 1** — Give a category-level nudge:
+```
+Good start, but at Level N I'd expect you to also notice [category — e.g.,
+"how errors are handled" or "what the decorator is doing"]. Try again —
+what about [specific nudge — e.g., "the return type on line 47"]?
+```
+
+**Strike 2** — Give a near-explicit hint:
+```
+Getting closer. One more thing — [nearly names the concept — e.g., "that
+@retry decorator wraps the function"]. Look at line X.
+```
+
+**Strike 3** — Reveal the full answer and move on:
+```
+Let me walk you through it.
+```
+Then deliver the complete evaluation (both axes) as if they had skipped.
+After the evaluation, proceed directly to the next round — do not ask
+"another round?" after a strike-3 reveal; just present the next snippet.
+
+If the user gets it on attempt 2 or 3:
+```
+There you go! Now let me fill in what else is notable.
+```
+Then provide the remaining feedback they missed, and ask "Another round?".
+
+If the user's answer **meets** expectations (any attempt):
+- Highlight 2–4 specific things they got right
+- Add 1–3 things they could sharpen (even a strong answer has nuance)
+- Reveal the file context
+- Ask "Another round?"
+
+#### Feedback structure (success or strike-3)
+
+```
+**What you got right:**
+- [2–4 specific things correctly identified]
+
+**What you missed or could sharpen:**
+- [1–3 things, with brief explanation]
+
+**Context:** `services/position_sizer.py` — called by the OrderManager before
+placing any trade. Sits between the signal generator and the exchange adapter.
+```
+
+Keep feedback constructive. The goal is learning, not grading. If they
+nailed everything at-level, say so and highlight the nuance they caught.
+
+#### Handling commands mid-round
+
+| Command | Behavior |
+|---------|----------|
+| `hint` | Give one strike-1 level nudge (counts as an attempt in the strike system) |
+| `skip` / `reveal` | Show full evaluation immediately. Move to next round. |
+| `next` / `another` | Skip this snippet, draw a new one. No strike counted. |
+| `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. |
+
+### 5. Loop — Keep Going
+
+After a successful evaluation or a `next` skip, ask:
+"Another round? (yes / no / level N / stop)"
+
+After a strike-3 reveal, do **not** ask — proceed directly to the next
+round with: "Round N+1 — Level X | `file.py`"
+
+### End-of-Session Summary
+
+When the user says `stop`:
+
+```
+## Session Summary
+
+Rounds completed: 5
+Level played: 3
+Files covered:
+  - services/position_sizer.py (rounds 1, 4)
+  - agents/news_agent.py (round 2)
+  - utils/fuzzy_dedup.py (round 3)
+  - database.py (round 5)
+
+What you're strong on: [concepts consistently identified]
+What to review:    [concepts missed across multiple rounds]
+Suggested next level: [3 → 4, or stay, or 3 → 2]
+```
+
+## Multilingual Projects
+
+If the project contains multiple languages, let the user's `teach me <lang>`
+filter govern. If no filter, sample all languages proportionally but announce
+the language in each round header. Use language-appropriate evaluation
+criteria for the Mechanics axis:
+
+- **Python:** decorators, generators, descriptors, `async`/`await`, type hints,
+  context managers, MRO, slots, data classes
+- **JavaScript/TypeScript:** closures, prototypes, `this` binding, promises,
+  async/await, destructuring, spread, arrow functions, TypeScript generics
+- **Rust:** ownership, borrowing, lifetimes, pattern matching, `Result`/`Option`,
+  traits, generics, macros
+- **Go:** goroutines, channels, interfaces, defer, error handling conventions,
+  zero values
+- **Java:** streams, generics, annotations, try-with-resources, concurrency
+  primitives, inheritance vs composition
+
+## Guardrails
+
+- **Never show secrets.** Scan every snippet before display. Redact API keys,
+  tokens, passwords, connection strings with `[REDACTED]`. Skip entire snippets
+  that are only secrets/config.
+- **Never show user data.** Skip snippets containing PII, email addresses,
+  phone numbers, or personal identifiers.
+- **One snippet per turn.** Wait for the user's response before showing the next.
+- **Respect stop immediately.** If the user says `stop`, deliver the summary —
+  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.
+
+## Verification
+
+After each round, confirm:
+- The snippet was actually read from the file (not hallucinated)
+- The line numbers match the source
+- The feedback accurately describes what the code does
+- No secrets or PII were exposed
+- The strike count was tracked correctly

package/tools-install.js

@@ -2,7 +2,7 @@
 /**
  * CodeWhale Tools Installer
  *
- * Installs global skills and workspace triggers for //tools, //history, and //snapshot.
+ * Installs global skills and workspace triggers for //tools, //history, //snapshot, and //teach-me.
  *
  * Usage:
  *   node tools-install.js                          # current directory
@@ -55,12 +55,12 @@ if (fs.existsSync(instructionsSource)) {
   if (fs.existsSync(instructionsDest)) {
     const existingContent = fs.readFileSync(instructionsDest, 'utf-8');
     // Only append if it's not already there (idempotent)
-    if (!existingContent.includes('## //tools Command') && !existingContent.includes('## //history Command') && !existingContent.includes('## //snapshot Command')) {
+    if (!existingContent.includes('## //tools Command') && !existingContent.includes('## //history Command') && !existingContent.includes('## //snapshot Command') && !existingContent.includes('## //teach-me Command')) {
       const separator = `\n\n---\n\n`;
       fs.writeFileSync(instructionsDest, existingContent + separator + newContent, 'utf-8');
-      console.log('  Appended //tools, //history, and //snapshot instructions to existing instructions.md');
+      console.log('  Appended //tools, //history, //snapshot, and //teach-me instructions to existing instructions.md');
     } else {
-      console.log('  //tools, //history, and //snapshot already present in instructions.md — skipped.');
+      console.log('  //tools, //history, //snapshot, and //teach-me already present in instructions.md — skipped.');
     }
   } else {
     fs.writeFileSync(instructionsDest, newContent, 'utf-8');
@@ -78,6 +78,7 @@ const checklist = {
   'history skill': path.join(skillsDest, 'history', 'SKILL.md'),
   'tools skill': path.join(skillsDest, 'tools', 'tools-skill', 'SKILL.md'),
   'snapshot skill': path.join(skillsDest, 'snapshot', 'SKILL.md'),
+  'teach-me skill': path.join(skillsDest, 'teach-me', 'SKILL.md'),
   'workspace instructions': instructionsDest
 };
 
@@ -94,7 +95,7 @@ console.log('');
 if (errors === 0) {
   console.log('=== Installation complete! ===');
   console.log('Make sure codewhale-history is installed globally: npm install -g <path-to-tools_for_codewhale>');
-  console.log('Then type //tools, //history, or //snapshot in any CodeWhale session.');
+  console.log('Then type //tools, //history, //snapshot, or //teach-me in any CodeWhale session.');
 } else {
   console.log(`=== Installation finished with ${errors} error(s). ===`);
 }