elliot-stack 1.0.28 → 1.0.30

package/README.md

@@ -20,13 +20,14 @@ This installs skills to `~/.agents/skills/` and symlinks them into `~/.claude/sk
 | **Active Learning Tutor** | `/estack-active-learning-tutor` | Tutors a student through exam preparation using active learning — questioning, gap diagnosis, and concept mastery tracking |
 | **Better Title** | `/estack-better-title` | Renames Claude Code chat sessions with descriptive titles |
 | **Chris Voss** | `/estack-chris-voss` | Applies negotiation principles from *Never Split the Difference* |
-| **CLAUDE.md Optimizer** | `/estack-claude-md-optimizer` | Creates, refines, and maintains CLAUDE.md / AGENTS.md files as short hand-authored letters of intent |
+| **CLAUDE.md Optimizer** | `/estack-claude-md-optimizer` | Creates, refines, and maintains CLAUDE.md / AGENTS.md files as short hand-authored letters of intent — welcomes first-time users with the why behind the format and coaches through pushback instead of enforcing rules |
 | **Customer Discovery** | `/estack-customer-discovery` | Guides through customer discovery — validating ideas, outreach, interviews, and analysis |
 | **Flight Planner** | `/estack-flight-planner` | Finds and ranks flights between two airports with config-driven preferences and optional ground-shuttle pairing |
 | **GitHub Issue Tracker** | `/estack-github-issue-tracker` | Tracks and manages GitHub issues across repos |
 | **Prompt Builder Coach** | `/estack-prompt-builder-coach` | Four-part kit for shaping, building, auditing, and scoping prompts for AI agents |
 | **Read Claude Session History** | `/estack-read-claude-session-history` | Searches, reads, recovers, and compares Claude Code session history across sessions, projects, and backups |
 | **Repo Search** | `/estack-repo-search` | Clones and searches external GitHub repos to answer questions about their code |
+| **VS Code File Recovery** | `/estack-vscode-file-recovery` | Recovers permanently deleted files from VS Code or Cursor Local History, Claude session transcripts, or Windows Shadow Copies |
 
 ## Hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elliot-stack",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Elliot's skill stack for Claude Code — install via npx elliot-stack@latest",
   "bin": {
     "elliot-stack": "bin/install.cjs"

package/skills/estack-claude-md-optimizer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: estack-claude-md-optimizer
-version: 1.0.1
+version: 1.2.0
 description: >-
   (claude-md-optimizer) Create, refine, and maintain CLAUDE.md / AGENTS.md files
   as short hand-authored letters of intent. Use whenever the user asks to create,
@@ -18,33 +18,82 @@ their intent, mental model, and the "why" — not a spec, not a rulebook, not an
 encyclopedia. This skill helps them write and keep that letter. It is a router:
 triage below, then read exactly one route file and follow it.
 
-## Opening message — buy the user in first
+## Opening message — welcome and teach first
 
-Your first message of any run, before the triage announcement, briefly explains
-the skill so the user knows what's happening and why (3–5 sentences, plain
-language, then move on):
+Assume the user has never used this skill before. Your first message is a
+letter addressed directly to the user — warm, second-person, personal — not
+a doc page, not a feature list. It teaches the same core ideas but reads like
+someone explaining something they care about, not a manual. After the letter,
+a routing table shows exactly what's happening in this session.
 
-- **What it is:** a tool for writing and maintaining a CLAUDE.md as a short
-  letter — prose that transfers your intent and "why" to the agent.
-- **Why it works that way:** bloated context files measurably make models worse
-  — the model isn't dumb, it's drowning. Intent transfers better than rules,
-  which is also why the human authors the letter and the skill only transcribes:
-  the file's job is to carry *your* thinking, and every line is earned by your
-  stated intent or a mistake that actually recurred — never padded.
-- **How this run works:** diagnose the file's state → name the route(s) →
-  interview or proposals → nothing touches disk without your approval.
+Structure the opening exactly like this (fill in the session plan table based
+on your triage — see the Triage section below for how to pick routes):
 
-This intro exists so the process (interviews, proposed deletions, refusing to
-add lines) reads as the method working, not as friction. Don't lecture; one
-tight paragraph, then the triage announcement.
+---
+
+Hey — welcome to the CLAUDE.md Optimizer.
+
+Before we start, here's what you should know about how this works and why.
+
+**Your `CLAUDE.md` is a letter, not a rulebook.** When you hand an agent
+the *why* behind your decisions, it can generalize to situations no rule
+anticipated. When you hand it a rulebook, it follows the rules off a cliff.
+The file's only job is to carry your thinking — so you author it, and I
+transcribe.
+
+**It has to stay short.** Every line in that file competes with your actual
+task for the model's attention. Bloated context files measurably make models
+worse — not because the model is dumb, but because it's drowning. Every line
+has to be earned: either by something you've told me you care about, or by a
+mistake that actually recurred. Never padded.
+
+**You start with a letter. Routing comes later, only if it's earned.** Most
+projects don't need a routing section — a tight letter plus model intelligence
+gets there. Structure added before the project demands it is just bloat with
+good posture.
+
+**No commands, paths, or stack details in the file.** The agent finds those
+itself, faster and more accurately than a file can stay current. Stale paths
+don't just not help — they actively mislead.
+
+Here's what we're doing today:
+
+| Step | What's happening | Why |
+|------|-----------------|-----|
+| **Diagnose** | I read your current file (or confirm there isn't one) | Can't plan without knowing where we're starting |
+| **Route** | I name which flow(s) apply and tell you why | So you can correct me before anything starts |
+| **[Route-specific steps]** | Interview, proposals, line-by-line review — depends on the route | See below |
+| **Approve & write** | Nothing touches disk until you've signed off on every line | The file is yours |
+
+*(I'll replace [Route-specific steps] with the actual steps once I've triaged
+the file and named the route — usually 2–3 more rows.)*
+
+---
+
+Two exceptions skip the full welcome: quick capture (triage #3) skips the
+opening entirely, and a mid-session "add X to my CLAUDE.md" gets a one-line
+greeting at most — they're in the middle of work, not onboarding.
+
+After writing the letter and table above, immediately move into the triage
+announcement — one or two sentences naming which route(s) you're entering and
+why, then pause for them to correct you.
 
 ## Progress header — every message, every step
 
-After the opening message, start every subsequent output with a one-line header:
-where we are in the flow, roughly what's left, and — most important — whether
-the flow is DONE or NOT DONE. Format:
+After the opening message, start every subsequent output with a one-line status
+header: where we are in the flow, roughly what's left, and — most important —
+whether the flow is DONE or NOT DONE. Render it inside a fenced code block
+drawn as a box, so it reads as a status instrument visually separate from the
+message itself, verbatim format:
 
-> **Create · step 2 of 4 (interview) · ~2 steps left · NOT DONE — next: draft**
+```
+┌──────────────────────────────────────────────────────────────
+│ Create · step 2 of 4 (interview) · ~2 steps left · NOT DONE — next: draft
+└──────────────────────────────────────────────────────────────
+```
+
+(The right edge stays open — never fiddle with padding to close the box. Keep
+the border lines exactly that width regardless of the status text's length.)
 
 Estimates are allowed to be rough (an incomplete answer can keep a step alive an
 extra turn — fine, don't apologize, just keep the count honest). What is not
@@ -148,6 +197,31 @@ session-capture first.
    and won't follow a pointer into AGENTS.md, so that direction is the only one
    that works for every tool.
 
+## Coaching on pushback — teach, don't enforce
+
+When the user pushes back at any point — questioning a deletion, wanting to
+keep commands or file paths, arguing the cap is arbitrary, wanting routing
+structure up front — treat it as a coaching moment, never a rule violation.
+Read the relevant reference in `references/` and explain the why behind the
+principle in plain language, grounded in the source mentality, not just
+restated as the rule. Then genuinely weigh their point — they might be right:
+
+1. **Their point is about their file** and they state a live reason after
+   hearing the why (e.g. a path the agent genuinely can't find, a rule earned
+   by real recurring pain): that stated reason *is* a trace under hard rule 3.
+   Their call wins — note the trace and apply it. The user authors; you
+   transcribe.
+2. **Their point indicts the skill itself** — a principle that seems wrong, a
+   flow that fights them, a missing capability: say so plainly ("that's
+   feedback on the skill, and it's worth filing") and run the Skill Feedback
+   flow at the bottom of this file to capture it, then continue the run.
+3. **The pushback dissolves once the why lands** — most do. Explain once, then
+   defer to their decision. Never lecture twice on the same point.
+
+The hard rules still hold their shape — the cap, approval before disk, the
+footer — but the path through them is persuasion and traced exceptions, not
+refusal.
+
 ## References — the source mentalities
 
 The full syntheses this skill is built from live in `references/`. Read them on

package/skills/estack-vscode-file-recovery/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: estack-vscode-file-recovery
+version: 1.2.0
+description: >
+  (vscode-file-recovery) Recover files that were permanently deleted (via rm, bash delete, or any method that bypasses the Recycle Bin) using VS Code's or Cursor's Local History snapshots, or from Claude session transcripts.
+  Use this skill immediately whenever: a file was deleted and git can't recover it (untracked or not committed), the user says "get it back", "restore that file", "I lost that file", "can you undo that delete", or any variation of wanting a deleted file recovered. Also use proactively after any rm or bash delete of files that weren't committed to git.
+  VS Code and Cursor silently save a snapshot every time you open or edit a file in the editor — this is often the only recovery path when git and Recycle Bin both fail.
+---
+
+# VS Code / Cursor File Recovery
+
+When a file is deleted outside of git (with `rm`, bash, or any method that bypasses the Recycle Bin), this skill recovers it from editor Local History or Claude session transcripts.
+
+## Recovery Sources — Try in Order
+
+1. **Editor Local History** (VS Code or Cursor) — covered below
+2. **Claude session transcript** — if Claude read the file in a prior session, its content may be in the JSONL. Use `/read-transcript` to search session history.
+3. **Git** — only if the file was ever committed
+4. **Cloud sync** (OneDrive, Dropbox) — check the cloud recycle bin / version history
+
+---
+
+## How Editor Local History Works
+
+VS Code and Cursor automatically save timestamped snapshots of every file opened in the editor. These live at:
+
+```
+VS Code  (Windows): C:\Users\[username]\AppData\Roaming\Code\User\History\
+Cursor   (Windows): C:\Users\[username]\AppData\Roaming\Cursor\User\History\
+VS Code  (Mac):     ~/Library/Application Support/Code/User/History/
+Cursor   (Mac):     ~/Library/Application Support/Cursor/User/History/
+VS Code  (Linux):   ~/.config/Code/User/History/
+Cursor   (Linux):   ~/.config/Cursor/User/History/
+```
+
+Each file gets a hash-named folder containing:
+- `entries.json` — maps the original file path to snapshot IDs and timestamps
+- `[id].[ext]` — the actual snapshot content (e.g., `dtgz.md`, `F9gm.txt`)
+
+**Critical limitation:** VS Code only snapshots files that were actually *opened as a tab in the editor*. Files visible only in the sidebar Explorer are not captured.
+
+---
+
+## Recovery Steps
+
+### Step 1: Identify what to search for
+
+Collect from the user (or from the deletion event):
+- The filename (e.g., `Untitled-1.md`)
+- The full path if known (e.g., `C:\Users\2supe\All Coding\akiflow-mcp\Untitled-1.md`)
+- Any partial path segments (folder name, project name)
+
+### Step 2: Search editor history for the file
+
+Search `entries.json` files in both VS Code and Cursor History directories.
+
+**Windows (PowerShell) — searches both editors:**
+```powershell
+@("Code", "Cursor") | ForEach-Object {
+  $histPath = "$env:APPDATA\$_\User\History"
+  if (Test-Path $histPath) {
+    Get-ChildItem $histPath -Recurse |
+      Where-Object { $_.Name -eq "entries.json" } |
+      ForEach-Object {
+        $content = Get-Content $_.FullName -Raw -ErrorAction SilentlyContinue
+        if ($content -like "*FILENAME_OR_PATH_PATTERN*") {
+          $_.FullName
+          $content
+        }
+      }
+  }
+}
+```
+
+Replace `FILENAME_OR_PATH_PATTERN` with the filename or path fragment. **Use `-like "*filename*"` rather than `-match "filename"` to avoid regex metacharacter issues** (`.`, `(`, `)`, `+` in filenames break `-match`).
+
+If matching a full path, note that editors URL-encode it in `entries.json`: drive colons become `%3A`, backslashes become `/`, and spaces become `%20`. Example: `C:\Users\2supe\My App (v2).md` → `file:///c%3A/Users/2supe/My%20App%20%28v2%29.md`. **Searching by filename alone is simpler and usually sufficient.**
+
+**Mac (bash) — searches both editors:**
+```bash
+for app in "Code" "Cursor"; do
+  grep -rl "FILENAME_OR_PATH_PATTERN" "$HOME/Library/Application Support/$app/User/History/" 2>/dev/null
+done
+```
+
+### Step 3: Read the entries.json to find the latest snapshot
+
+The `entries.json` looks like:
+```json
+{
+  "version": 1,
+  "resource": "file:///c%3A/Users/2supe/path/to/Untitled-1.md",
+  "entries": [
+    {"id": "F9gm.md", "source": "Workspace Edit", "timestamp": 1776196985353},
+    {"id": "U4ha.md", "source": "Workspace Edit", "timestamp": 1776197058059},
+    {"id": "dtgz.md", "source": "Workspace Edit", "timestamp": 1776197128275}
+  ]
+}
+```
+
+The **last entry** in the array is the most recent snapshot. Take its `id` field.
+
+### Step 4: Read the snapshot content
+
+```powershell
+Get-Content "C:\Users\[username]\AppData\Roaming\Code\User\History\[hash-folder]\[id]"
+```
+
+Or use the Read tool with the full path.
+
+### Step 5: Restore the file
+
+Write the content back to the original location using the Write tool.
+
+---
+
+## When Editor History Won't Help
+
+- **File was never opened as an editor tab** — files only visible in the sidebar Explorer are not snapshotted.
+- **History was cleared** — default retention is 30 days / 50 entries per file.
+
+If editor history doesn't have the file, fall back to:
+1. **`/read-transcript`** — if Claude read the file in a prior session, the content is in the session JSONL. Use `--mode search --query "filename"` to find it. Note: you need to point it at the right project's sessions — if the file lived in a different project folder, search that project's transcript directory instead.
+2. **Windows Shadow Copies** (last resort, requires admin) — Windows VSS may have a snapshot of the volume. Check if any exist first:
+   ```powershell
+   vssadmin list shadows
+   ```
+   If a shadow copy exists, mount it and browse (**requires an elevated/admin shell**; the trailing backslash on the device path is required or `mklink` fails silently):
+   ```powershell
+   cmd /c mklink /d C:\shadow \\?\GLOBALROOT\Device\HarddiskVolumeShadowCopy3\
+   ```
+   Replace the device path with the one from `vssadmin list shadows`. Browse `C:\shadow\` like a normal drive to find and copy the file back. Clean up after: `cmd /c rmdir C:\shadow`.
+3. **File recovery software** (Recuva on Windows) — only works if the disk blocks haven't been overwritten yet.
+
+---
+
+## Example
+
+**Scenario:** `rm` deleted `Untitled-1.md` which was untracked by git.
+
+```powershell
+# Search
+Get-ChildItem "$env:APPDATA\Code\User\History" -Recurse |
+  Where-Object { $_.Name -eq "entries.json" } |
+  ForEach-Object {
+    $content = Get-Content $_.FullName -Raw -ErrorAction SilentlyContinue
+    if ($content -like "*Untitled-1*") { $_.FullName; $content }
+  }
+
+# Result shows: C:\...\History\-6e228c75\entries.json
+# entries.json has latest id: "dtgz.md"
+
+# Read snapshot
+Get-Content "C:\Users\2supe\AppData\Roaming\Code\User\History\-6e228c75\dtgz.md"
+
+# Restore
+# (Use Write tool to recreate the file at original path)
+```
+---
+
+## Skill Feedback
+
+If the user shares feedback about this skill — a bug, something confusing, a missing feature, or a suggestion — ask them to describe it in a bit more detail (what they expected, what happened, and any relevant context). Then file the issue using whichever method is available:
+
+**If `gh` is installed** (`gh --version` succeeds), create the issue directly:
+
+```bash
+gh issue create \
+  --repo ElliotDrel/e-stack \
+  --title "estack-vscode-file-recovery: <concise summary>" \
+  --body "<description from user feedback — expected vs. actual behavior and context>"
+```
+
+**If `gh` is not installed**, build a pre-filled URL:
+
+```bash
+python3 -c "
+import urllib.parse
+title = 'estack-vscode-file-recovery: <concise summary>'
+body = '<description from user feedback — expected vs. actual behavior and context>'
+base = 'https://github.com/ElliotDrel/e-stack/issues/new'
+print(base + '?title=' + urllib.parse.quote(title) + '&body=' + urllib.parse.quote(body))
+"
+```
+
+Share the printed URL with the user and offer to open it in their browser.
+
+They can also click it directly, review the pre-filled title and body, and click **Submit new issue**.