From 276d0cc6cb944f295377675f7dff57b916d2c29f Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 12:27:47 -0500 Subject: [PATCH] feat: always-on ELI16 + branch detection (v0.4.3) (#108) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: always-on ELI16 + branch detection in preamble - Add _BRANCH detection to preamble bash block (git branch --show-current) - Merge ELI16 rules into default AskUserQuestion format (always-on) - Remove _SESSIONS >= 3 conditional — better questions always - Add simplification rules: plain English, no jargon, no raw function names - Update tests for branch detection and simplification regression guard * chore: bump version and changelog (v0.4.3) Co-Authored-By: Claude Opus 4.6 --------- Co-authored-by: Claude Opus 4.6 --- CHANGELOG.md | 11 +++++++++++ SKILL.md | 12 +++++++----- VERSION | 2 +- browse/SKILL.md | 12 +++++++----- plan-ceo-review/SKILL.md | 12 +++++++----- plan-eng-review/SKILL.md | 12 +++++++----- qa-only/SKILL.md | 12 +++++++----- qa/SKILL.md | 12 +++++++----- retro/SKILL.md | 12 +++++++----- review/SKILL.md | 12 +++++++----- scripts/gen-skill-docs.ts | 12 +++++++----- setup-browser-cookies/SKILL.md | 12 +++++++----- ship/SKILL.md | 12 +++++++----- test/gen-skill-docs.test.ts | 13 ++++++++++++- test/skill-validation.test.ts | 2 +- 15 files changed, 102 insertions(+), 58 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b4e93f94..99b7086c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,16 @@ # Changelog +## 0.4.3 — 2026-03-16 + +- **Every question is now crystal clear, every time.** You used to need 3+ sessions running before gstack would give you full context and plain English explanations. Now every question — even in a single session — tells you the project, branch, and what's happening, explained simply enough to understand mid-context-switch. No more "sorry, explain it to me more simply." +- **Branch name is always correct.** gstack now detects your current branch at runtime instead of relying on the snapshot from when the conversation started. Switch branches mid-session? gstack keeps up. + +### For contributors + +- Merged ELI16 rules into base AskUserQuestion format — one format instead of two, no `_SESSIONS >= 3` conditional. +- Added `_BRANCH` detection to preamble bash block (`git branch --show-current` with fallback). +- Added regression guard tests for branch detection and simplification rules. + ## 0.4.2 — 2026-03-16 - **`$B js "await fetch(...)"` now just works.** Any `await` expression in `$B js` or `$B eval` is automatically wrapped in an async context. No more `SyntaxError: await is only valid in async functions`. Single-line eval files return values directly; multi-line files use explicit `return`. diff --git a/SKILL.md b/SKILL.md index 2239a91b5..76007eee1 100644 --- a/SKILL.md +++ b/SKILL.md @@ -26,6 +26,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -33,12 +35,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/VERSION b/VERSION index 2b7c5ae01..17b2ccd9b 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.4.2 +0.4.3 diff --git a/browse/SKILL.md b/browse/SKILL.md index c0d7a4eb5..dd473dc06 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -26,6 +26,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -33,12 +35,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 07830998e..b05db5e9b 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -26,6 +26,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -33,12 +35,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index ad2baca6e..4cd8f481a 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -26,6 +26,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -33,12 +35,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 27d939bec..5e74f03e6 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -25,6 +25,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -32,12 +34,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/qa/SKILL.md b/qa/SKILL.md index 938bf10b2..6b078a9d6 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -30,6 +30,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -37,12 +39,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/retro/SKILL.md b/retro/SKILL.md index 39b7ee131..c77815259 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -25,6 +25,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -32,12 +34,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/review/SKILL.md b/review/SKILL.md index b94f8a30c..285a4922a 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -26,6 +26,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -33,12 +35,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/scripts/gen-skill-docs.ts b/scripts/gen-skill-docs.ts index f3d93dbbb..9d79189a0 100644 --- a/scripts/gen-skill-docs.ts +++ b/scripts/gen-skill-docs.ts @@ -105,6 +105,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" \`\`\` If output shows \`UPGRADE_AVAILABLE \`: read \`~/.claude/skills/gstack/gstack-upgrade/SKILL.md\` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If \`JUST_UPGRADED \`: tell user "Running gstack v{to} (just updated!)" and continue. @@ -112,12 +114,12 @@ If output shows \`UPGRADE_AVAILABLE \`: read \`~/.claude/skills/gstac ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. \`RECOMMENDATION: Choose [X] because [one-line reason]\` -4. Lettered options: \`A) ... B) ... C) ...\` +1. **Re-ground:** State the project, the current branch (use the \`_BRANCH\` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** \`RECOMMENDATION: Choose [X] because [one-line reason]\` +4. **Options:** Lettered options: \`A) ... B) ... C) ...\` -If \`_SESSIONS\` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index d522b270a..faebe5203 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -23,6 +23,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -30,12 +32,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/ship/SKILL.md b/ship/SKILL.md index 7791f4bcb..ee98ecaf5 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -25,6 +25,8 @@ touch ~/.gstack/sessions/"$PPID" _SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ') find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true _CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true) +_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown") +echo "BRANCH: $_BRANCH" ``` If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED `: tell user "Running gstack v{to} (just updated!)" and continue. @@ -32,12 +34,12 @@ If output shows `UPGRADE_AVAILABLE `: read `~/.claude/skills/gstack/g ## AskUserQuestion Format **ALWAYS follow this structure for every AskUserQuestion call:** -1. Context: project name, current branch, what we're working on (1-2 sentences) -2. The specific question or decision point -3. `RECOMMENDATION: Choose [X] because [one-line reason]` -4. Lettered options: `A) ... B) ... C) ...` +1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences) +2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called. +3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` +4. **Options:** Lettered options: `A) ... B) ... C) ...` -If `_SESSIONS` is 3 or more: the user is juggling multiple gstack sessions and context-switching heavily. **ELI16 mode** — they may not remember what this conversation is about. Every AskUserQuestion MUST re-ground them: state the project, the branch, the current plan/task, then the specific problem, THEN the recommendation and options. Be extra clear and self-contained — assume they haven't looked at this window in 20 minutes. +Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex. Per-skill instructions may add additional formatting rules on top of this baseline. diff --git a/test/gen-skill-docs.test.ts b/test/gen-skill-docs.test.ts index e77989f06..7ec8b2801 100644 --- a/test/gen-skill-docs.test.ts +++ b/test/gen-skill-docs.test.ts @@ -144,7 +144,18 @@ describe('gen-skill-docs', () => { const content = fs.readFileSync(path.join(ROOT, 'SKILL.md'), 'utf-8'); expect(content).toContain('_SESSIONS'); expect(content).toContain('RECOMMENDATION'); - expect(content).toContain('ELI16'); + }); + + test('generated SKILL.md contains branch detection', () => { + const content = fs.readFileSync(path.join(ROOT, 'SKILL.md'), 'utf-8'); + expect(content).toContain('_BRANCH'); + expect(content).toContain('git branch --show-current'); + }); + + test('generated SKILL.md contains ELI16 simplification rules', () => { + const content = fs.readFileSync(path.join(ROOT, 'SKILL.md'), 'utf-8'); + expect(content).toContain('No raw function names'); + expect(content).toContain('plain English'); }); test('qa and qa-only templates use QA_METHODOLOGY placeholder', () => { diff --git a/test/skill-validation.test.ts b/test/skill-validation.test.ts index 3ff5c356b..77f09ee05 100644 --- a/test/skill-validation.test.ts +++ b/test/skill-validation.test.ts @@ -491,7 +491,7 @@ describe('v0.4.1 preamble features', () => { test(`${skill} contains session awareness`, () => { const content = fs.readFileSync(path.join(ROOT, skill), 'utf-8'); expect(content).toContain('_SESSIONS'); - expect(content).toContain('ELI16'); + expect(content).toContain('RECOMMENDATION'); }); } });