codewhale.history 2.9.1 → 2.9.3

package/README.md

@@ -78,13 +78,22 @@ Git already has your back.
 
 ### `//teach-me`
 An interactive code-teaching quiz that randomly selects real snippets from your
-current project. Three modes across five difficulty levels:
+current project. Two independent dimensions 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.
-- **SOLID**: Working code is rewritten with deliberate anti-patterns (breaks
-  SOLID, DRY, cohesion). You restore good design, then say `done`.
+**Response mode** (how you answer):
+- **Passive** (default) — Describe your answer in the console.
+- **Interactive** (`teach me interactive`) — Edit the actual file, say `done`.
+
+**Content theme** (what it's about):
+- **Standard** (default) — Code comprehension or line reconstruction.
+- **SOLID** (`teach me solid`) — Anti-pattern detection and design restoration.
+
+| Trigger | Response | Theme | What happens |
+|---------|----------|-------|-------------|
+| `teach me` | passive | standard | Present code; you explain it |
+| `teach me interactive` | interactive | standard | Lines removed; you restore them |
+| `teach me solid` | passive | solid | Degraded code; you describe fixes |
+| `teach me solid interactive` | interactive | solid | Degraded code; you edit to fix it |
 
 **Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
 `drill me`
@@ -95,8 +104,8 @@ current project. Three modes across five difficulty levels:
 |----------|---------|-------------|
 | 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 — restore missing lines |
-| Mode | `teach me solid` | Anti-pattern detection — fix degraded design |
+| Response | `teach me interactive` | Edit the file instead of describing |
+| Theme | `teach me solid` | Anti-pattern detection — fix degraded design |
 | 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 |
 
@@ -117,19 +126,10 @@ current project. Three modes across five difficulty levels:
 **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.
 
-### SOLID Mode
-
-| Trigger | What happens |
-|---------|-------------|
-| `teach me solid` | SOLID mode at level 3, passive feedback |
-| `teach me SOLID level 4` | Level 4, passive |
-| `teach me solid interactive` | SOLID mode, you edit the file (not just describe) |
-
-**How it works:** The model picks code, rewrites it with deliberate anti-patterns
+In **SOLID theme**: the model rewrites code with deliberate anti-patterns
 (STUPID, WET, god objects, tight coupling), presents the degraded code, and you
-restore good design. The model assesses across anti-patterns fixed, design
-quality, functional correctness, and intentionality. Files are always restored
-with `git checkout` after each round.
+restore good design. Files are always restored with `git checkout` after each
+round.
 
 ## Requirements
 - Node.js (for the `codewhale-history` command)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codewhale.history",
-  "version": "2.9.1",
+  "version": "2.9.3",
   "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

@@ -6,16 +6,25 @@ description: Interactive code-teaching quiz. Selects random snippets from the cu
 # Teach Me — Interactive Code Quiz
 
 An interactive teaching session that randomly selects code snippets from the
-current project. Two modes:
+current project. Two independent dimensions combine to form each exercise:
 
-- **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.
-- **SOLID**: rewrites working code to be deliberately anti-pattern-ridden
-  (STUPID principles, WET code, poor cohesion). The user restores good
-  design and says `done`; the model evaluates against the original.
+**Response mode** (how you answer — mid-session commands `passive` / `interactive`):
+- **`passive`** (default) — You describe your answer in the console.
+- **`interactive`** — You edit the actual file, then say `done` for verification.
+
+**Content theme** (what the exercise is about — trigger keyword `solid`):
+- **Standard** (default) — Code comprehension or line reconstruction.
+- **`solid`** / **`SOLID`** — Anti-pattern detection and design restoration.
+
+| Trigger | Response | Theme | What happens |
+|---------|----------|-------|-------------|
+| `teach me` | passive | standard | Present code; you explain what it does and how it works |
+| `teach me interactive` | interactive | standard | Lines removed from file; you restore them, say `done` |
+| `teach me solid` | passive | solid | Code rewritten with anti-patterns; you describe design fixes |
+| `teach me solid interactive` | interactive | solid | Code rewritten with anti-patterns; you edit the file to restore good design, say `done` |
+
+Level, scope, language, and concept modifiers combine freely with any
+combination above.
 
 ## Session Trigger
 
@@ -37,22 +46,14 @@ Optionally followed by modifiers:
   `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`
+- `teach me interactive` — edit the file (instead of describing)
+- `teach me solid` / `teach me SOLID` — anti-pattern restoration theme
 
 Modifiers combine freely: `teach me decorators level 4`,
 `teach me async services/`, `teach me generators l2`,
 `teach me level 2 interactive`, `teach me interactive decorators`,
-`teach me solid level 3`, `teach me SOLID`
-
-Three 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.
-- **`solid`** / **`SOLID`** — Working code is rewritten with deliberate
-  anti-patterns (breaks SOLID, DRY, cohesion, abstraction). You restore good
-  design principles. When done, say `done` or `check my work`.
-
-Switch modes mid-session with `passive`, `interactive`, or `solid`.
+`teach me solid level 3`, `teach me SOLID`,
+`teach me solid interactive`
 
 If no level is specified, default to **level 3** and adjust based on
 performance across rounds.
@@ -132,10 +133,11 @@ 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
+### 2b. Interactive (Standard) — Line 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.
+When response mode is `interactive` (and theme is standard), 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
 
@@ -211,13 +213,19 @@ Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
 ---
 ```
 
-### 2c. SOLID Mode — Anti-Pattern Reconstruction
+### 2c. SOLID Theme — Anti-Pattern Reconstruction
 
-When mode is `solid` (or `SOLID`), the model rewrites working code to be
-deliberately anti-pattern-ridden — breaking SOLID principles, DRY, cohesion,
+When content theme is `solid` (or `SOLID`), the model rewrites working code to
+be deliberately anti-pattern-ridden — breaking SOLID principles, DRY, cohesion,
 and abstraction — while keeping the code functional. The user must restore
 good design.
 
+SOLID theme works with both response modes:
+- **passive + solid** (`teach me solid`): User describes design fixes in console.
+- **interactive + solid** (`teach me solid interactive`): User edits the file.
+
+The per-round flow below covers both; where they differ, both variants are noted.
+
 #### Scope by Level
 
 | Level | Scope | Anti-patterns introduced |
@@ -250,7 +258,7 @@ anti-patterns appropriate to the language and scope:
 - God object — one class/method that knows and does everything
 - Shotgun surgery — one change requires touching many files/methods
 
-#### SOLID Mode Per-Round Flow
+#### SOLID Theme Per-Round Flow
 
 0. **Snapshot git state.** Run `git status --porcelain <file>` before touching it.
 1. **Select** a snippet using the standard rules (section 2). For levels 3–5,
@@ -262,14 +270,20 @@ anti-patterns appropriate to the language and scope:
 4. **Present** the deconstructed code. State the scope, the number of
    anti-patterns introduced, but do NOT name or annotate them — the user must
    find them.
-5. **Instruct:** "Open `<file>`, find and fix the [N] anti-patterns. The code
-   should still work. Say `done` or `check my work` when ready."
-6. **Wait.** Do not evaluate until the user signals completion.
-7. **Re-read** the file. Compare against the saved original.
-8. **Feedback** (see SOLID Evaluation below). Restore with `git checkout -- <file>`.
-9. **Restore.** After feedback, `git checkout -- <file>` for a byte-perfect reset.
-   If pre-existing uncommitted changes (step 0), warn the user and offer manual
-   restore.
+5. **Instruct** (depends on response mode):
+   - *Interactive:* "Open `<file>`, fix the [N] anti-patterns. Say `done`."
+   - *Passive:* "Describe how you'd improve this code — what anti-patterns do
+     you see, and how would you fix them?"
+6. **Wait.** Do not evaluate until the user signals completion (`done` or answer).
+7. **Evaluate** (depends on response mode):
+   - *Interactive:* Re-read the file. Compare against saved original.
+   - *Passive:* Evaluate the user's description against the anti-patterns
+     that were introduced. No file re-read needed.
+8. **Feedback** (see SOLID Evaluation below).
+9. **Restore.** After feedback, `git checkout -- <file>` for a byte-perfect
+   reset. If pre-existing uncommitted changes (step 0), warn the user. For
+   passive mode, no file was modified by the user, but the deconstructed
+   code the model wrote must still be restored.
 
 #### Thinking Suppression (SOLID Mode)
 
@@ -281,7 +295,7 @@ original code or the specific anti-patterns chosen in your reasoning.
 
 ```
 ---
-## Round N — Level X · solid | `path/to/file.py` (lines A–B)
+## Round N — Level X · passive · solid | `path/to/file.py` (lines A–B)
 
 ```python
  42  class ReportGenerator:
@@ -320,7 +334,7 @@ For each round, present the snippet with its filename:
 
 ```
 ---
-## Round N — Level X · [interactive|passive] · concept | `path/to/file.py` (lines A–B)
+## Round N — Level X · [passive|interactive] · [concept|solid] | `path/to/file.py` (lines A–B)
 
 ```python
  42  def calculate_position_size(
@@ -349,8 +363,8 @@ 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
+- The response mode tag (`· passive` or `· interactive`) always appears in the header
+- The theme/concept tag (`· solid` for SOLID theme, or `· decorators` etc. for targeted concept) appears when applicable; omit during free-play standard 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,