From 17a96b096a6db7f1c09ae8f3bc4f39a2ca75643d Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Mon, 16 Mar 2026 12:21:58 -0500 Subject: [PATCH] feat: always-on ELI16 + branch detection in preamble MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- SKILL.md | 12 +++++++----- 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 +- 13 files changed, 90 insertions(+), 57 deletions(-) diff --git a/SKILL.md b/SKILL.md index 2239a91b..76007eee 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/browse/SKILL.md b/browse/SKILL.md index c0d7a4eb..dd473dc0 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 07830998..b05db5e9 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 ad2baca6..4cd8f481 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 27d939be..5e74f03e 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 938bf10b..6b078a9d 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 39b7ee13..c7781525 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 b94f8a30..285a4922 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 f3d93dbb..9d79189a 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 d522b270..faebe520 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 7791f4bc..ee98ecaf 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 e77989f0..7ec8b280 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 3ff5c356..77f09ee0 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'); }); } });