From dfc091fca1d12d9a3c7d355c881326748508500e Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 18 Apr 2026 11:39:10 +0800 Subject: [PATCH] chore: regenerate SKILL.md files + golden fixtures for V1 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Mechanical regeneration from the updated templates in prior commits: - Writing Style section now appears in tier-≥2 skill output. - EXPLAIN_LEVEL + WRITING_STYLE_PENDING echoes in preamble bash. - V1 migration-prompt block fires conditionally on first upgrade. - Jargon list inlined into preamble prose at gen time. - Retro template's logical SLOC + weighted commits order applied. Regenerated for all 8 hosts via bun run gen:skill-docs --host all. Golden ship-skill fixtures refreshed from regenerated outputs. Co-Authored-By: Claude Opus 4.7 (1M context) --- SKILL.md | 30 +++++ autoplan/SKILL.md | 125 ++++++++++++++++++ benchmark/SKILL.md | 30 +++++ browse/SKILL.md | 30 +++++ canary/SKILL.md | 125 ++++++++++++++++++ checkpoint/SKILL.md | 125 ++++++++++++++++++ codex/SKILL.md | 125 ++++++++++++++++++ cso/SKILL.md | 125 ++++++++++++++++++ design-consultation/SKILL.md | 125 ++++++++++++++++++ design-html/SKILL.md | 125 ++++++++++++++++++ design-review/SKILL.md | 125 ++++++++++++++++++ design-shotgun/SKILL.md | 125 ++++++++++++++++++ devex-review/SKILL.md | 125 ++++++++++++++++++ document-release/SKILL.md | 125 ++++++++++++++++++ health/SKILL.md | 125 ++++++++++++++++++ investigate/SKILL.md | 125 ++++++++++++++++++ land-and-deploy/SKILL.md | 125 ++++++++++++++++++ learn/SKILL.md | 125 ++++++++++++++++++ office-hours/SKILL.md | 125 ++++++++++++++++++ open-gstack-browser/SKILL.md | 125 ++++++++++++++++++ pair-agent/SKILL.md | 125 ++++++++++++++++++ plan-ceo-review/SKILL.md | 125 ++++++++++++++++++ plan-design-review/SKILL.md | 125 ++++++++++++++++++ plan-devex-review/SKILL.md | 125 ++++++++++++++++++ plan-eng-review/SKILL.md | 125 ++++++++++++++++++ plan-tune/SKILL.md | 125 ++++++++++++++++++ qa-only/SKILL.md | 125 ++++++++++++++++++ qa/SKILL.md | 125 ++++++++++++++++++ retro/SKILL.md | 142 ++++++++++++++++++++- review/SKILL.md | 125 ++++++++++++++++++ setup-browser-cookies/SKILL.md | 30 +++++ setup-deploy/SKILL.md | 125 ++++++++++++++++++ ship/SKILL.md | 125 ++++++++++++++++++ test/fixtures/golden/claude-ship-SKILL.md | 125 ++++++++++++++++++ test/fixtures/golden/codex-ship-SKILL.md | 125 ++++++++++++++++++ test/fixtures/golden/factory-ship-SKILL.md | 125 ++++++++++++++++++ 36 files changed, 4133 insertions(+), 4 deletions(-) diff --git a/SKILL.md b/SKILL.md index ae7dbd45..4d3b1d41 100644 --- a/SKILL.md +++ b/SKILL.md @@ -52,6 +52,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"gstack","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -113,6 +120,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 86c19932..c2c6493e 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -61,6 +61,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"autoplan","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -122,6 +129,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -377,6 +407,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/benchmark/SKILL.md b/benchmark/SKILL.md index ee12582e..cd46976b 100644 --- a/benchmark/SKILL.md +++ b/benchmark/SKILL.md @@ -54,6 +54,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"benchmark","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -115,6 +122,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" diff --git a/browse/SKILL.md b/browse/SKILL.md index 5801b627..d112a9d4 100644 --- a/browse/SKILL.md +++ b/browse/SKILL.md @@ -53,6 +53,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"browse","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -114,6 +121,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" diff --git a/canary/SKILL.md b/canary/SKILL.md index 5f5892bc..ed839ab0 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -53,6 +53,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"canary","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -114,6 +121,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -369,6 +399,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/checkpoint/SKILL.md b/checkpoint/SKILL.md index 829ab589..63489875 100644 --- a/checkpoint/SKILL.md +++ b/checkpoint/SKILL.md @@ -56,6 +56,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"checkpoint","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -117,6 +124,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -372,6 +402,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/codex/SKILL.md b/codex/SKILL.md index fdfdf3e4..82355fd0 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -55,6 +55,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"codex","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -116,6 +123,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -371,6 +401,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/cso/SKILL.md b/cso/SKILL.md index ed656d3f..bc2e045d 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"cso","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 4d2e0458..cf60243d 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"design-consultation","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/design-html/SKILL.md b/design-html/SKILL.md index 41419ca9..ae90753b 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -60,6 +60,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"design-html","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -121,6 +128,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -376,6 +406,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 2c6f97d3..2b849a9c 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"design-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index fa7f3414..5f6bb8ed 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -55,6 +55,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"design-shotgun","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -116,6 +123,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -371,6 +401,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 1f386569..53c9886e 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"devex-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 1c7c23c4..be338e83 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -55,6 +55,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"document-release","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -116,6 +123,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -371,6 +401,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/health/SKILL.md b/health/SKILL.md index f3f0867b..bc9d366c 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -55,6 +55,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"health","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -116,6 +123,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -371,6 +401,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/investigate/SKILL.md b/investigate/SKILL.md index ba97ebce..6500c507 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -72,6 +72,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"investigate","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -133,6 +140,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -388,6 +418,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index bbd473eb..67f1e73b 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -52,6 +52,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"land-and-deploy","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -113,6 +120,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -368,6 +398,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/learn/SKILL.md b/learn/SKILL.md index ef66affe..331fe9ed 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -55,6 +55,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"learn","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -116,6 +123,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -371,6 +401,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index 562ff966..06ca310e 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -63,6 +63,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -124,6 +131,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -379,6 +409,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index 4e5a2834..6dead0ea 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -52,6 +52,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"open-gstack-browser","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -113,6 +120,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -368,6 +398,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index ed7f42a2..cc151578 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -53,6 +53,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"pair-agent","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -114,6 +121,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -369,6 +399,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index bd1002ad..85f287aa 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -59,6 +59,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"plan-ceo-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -120,6 +127,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -375,6 +405,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index b8abe166..86a44f07 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -56,6 +56,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"plan-design-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -117,6 +124,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -372,6 +402,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index b4a297a6..8f867ae1 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -60,6 +60,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"plan-devex-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -121,6 +128,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -376,6 +406,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 885e7db1..b19bde7e 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"plan-eng-review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/plan-tune/SKILL.md b/plan-tune/SKILL.md index 41438ff3..7ffcdd8e 100644 --- a/plan-tune/SKILL.md +++ b/plan-tune/SKILL.md @@ -66,6 +66,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"plan-tune","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -127,6 +134,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -382,6 +412,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index 64494c50..2b1e8913 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -54,6 +54,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"qa-only","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -115,6 +122,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -370,6 +400,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/qa/SKILL.md b/qa/SKILL.md index 3ef53adf..e1d5fd58 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -60,6 +60,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"qa","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -121,6 +128,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -376,6 +406,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/retro/SKILL.md b/retro/SKILL.md index 6539d1d8..509f958c 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -53,6 +53,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"retro","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -114,6 +121,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -369,6 +399,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. @@ -779,21 +904,30 @@ Calculate and present these metrics in a summary table: | Metric | Value | |--------|-------| +| **Features shipped** (from CHANGELOG + merged PR titles) | N | | Commits to main | N | +| Weighted commits (commits × avg files-touched, capped at 20 per commit) | N | | Contributors | N | | PRs merged | N | -| Total insertions | N | -| Total deletions | N | -| Net LOC added | N | +| **Logical SLOC added** (non-blank, non-comment — primary code-volume metric) | N | +| Raw LOC: insertions | N | +| Raw LOC: deletions | N | +| Raw LOC: net | N | | Test LOC (insertions) | N | | Test LOC ratio | N% | | Version range | vX.Y.Z.W → vX.Y.Z.W | | Active days | N | | Detected sessions | N | -| Avg LOC/session-hour | N | +| Avg raw LOC/session-hour | N | | Greptile signal | N% (Y catches, Z FPs) | | Test Health | N total tests · M added this period · K regression tests | +**Metric order rationale (V1):** features shipped leads — what users got. Commits +and weighted commits reflect intent-to-ship. Logical SLOC added reflects real +new functionality. Raw LOC is demoted to context because AI inflates it; ten +lines of a good fix is not less shipping than ten thousand lines of scaffold. +See docs/designs/PLAN_TUNING_V1.md §Workstream C. + Then show a **per-author leaderboard** immediately below: ``` diff --git a/review/SKILL.md b/review/SKILL.md index 93eb617f..526315d8 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -57,6 +57,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"review","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -118,6 +125,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -373,6 +403,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/setup-browser-cookies/SKILL.md b/setup-browser-cookies/SKILL.md index 98a914b9..d7228d3f 100644 --- a/setup-browser-cookies/SKILL.md +++ b/setup-browser-cookies/SKILL.md @@ -50,6 +50,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"setup-browser-cookies","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -111,6 +118,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index da573c5b..1d5286a3 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -56,6 +56,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"setup-deploy","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -117,6 +124,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -372,6 +402,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/ship/SKILL.md b/ship/SKILL.md index 4c2ee927..7fa076fc 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"ship","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/test/fixtures/golden/claude-ship-SKILL.md b/test/fixtures/golden/claude-ship-SKILL.md index 4c2ee927..7fa076fc 100644 --- a/test/fixtures/golden/claude-ship-SKILL.md +++ b/test/fixtures/golden/claude-ship-SKILL.md @@ -58,6 +58,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$(~/.claude/skills/gstack/bin/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$(~/.claude/skills/gstack/bin/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"ship","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -119,6 +126,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa 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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `~/.claude/skills/gstack/bin/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -374,6 +404,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/test/fixtures/golden/codex-ship-SKILL.md b/test/fixtures/golden/codex-ship-SKILL.md index 7a57626a..6553f3b2 100644 --- a/test/fixtures/golden/codex-ship-SKILL.md +++ b/test/fixtures/golden/codex-ship-SKILL.md @@ -47,6 +47,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$($GSTACK_BIN/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$($GSTACK_BIN/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"ship","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -108,6 +115,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa If output shows `UPGRADE_AVAILABLE `: read `$GSTACK_ROOT/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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `$GSTACK_BIN/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -363,6 +393,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans. diff --git a/test/fixtures/golden/factory-ship-SKILL.md b/test/fixtures/golden/factory-ship-SKILL.md index c715fb40..736d1fc9 100644 --- a/test/fixtures/golden/factory-ship-SKILL.md +++ b/test/fixtures/golden/factory-ship-SKILL.md @@ -49,6 +49,13 @@ echo "TEL_PROMPTED: $_TEL_PROMPTED" # Question tuning (opt-in; see /plan-tune + docs/designs/PLAN_TUNING_V0.md) _QUESTION_TUNING=$($GSTACK_BIN/gstack-config get question_tuning 2>/dev/null || echo "false") echo "QUESTION_TUNING: $_QUESTION_TUNING" +# Writing style (V1: default = ELI10-style, terse = V0 prose. See docs/designs/PLAN_TUNING_V1.md) +_EXPLAIN_LEVEL=$($GSTACK_BIN/gstack-config get explain_level 2>/dev/null || echo "default") +if [ "$_EXPLAIN_LEVEL" != "default" ] && [ "$_EXPLAIN_LEVEL" != "terse" ]; then _EXPLAIN_LEVEL="default"; fi +echo "EXPLAIN_LEVEL: $_EXPLAIN_LEVEL" +# V1 upgrade migration pending-prompt flag +_WRITING_STYLE_PENDING=$([ -f ~/.gstack/.writing-style-prompt-pending ] && echo "yes" || echo "no") +echo "WRITING_STYLE_PENDING: $_WRITING_STYLE_PENDING" mkdir -p ~/.gstack/analytics if [ "$_TEL" != "off" ]; then echo '{"skill":"ship","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","repo":"'$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unknown")'"}' >> ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true @@ -110,6 +117,29 @@ of `/qa`, `/gstack-ship` instead of `/ship`). Disk paths are unaffected — alwa If output shows `UPGRADE_AVAILABLE `: read `$GSTACK_ROOT/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. +If `WRITING_STYLE_PENDING` is `yes`: You're on the first skill run after upgrading +to gstack v1. Ask the user once about the new default writing style. Use AskUserQuestion: + +> v1 prompts = simpler. Technical terms get a one-sentence gloss on first use, +> questions are framed in outcome terms, sentences are shorter. +> +> Keep the new default, or prefer the older tighter prose? + +Options: +- A) Keep the new default (recommended — good writing helps everyone) +- B) Restore V0 prose — set `explain_level: terse` + +If A: leave `explain_level` unset (defaults to `default`). +If B: run `$GSTACK_BIN/gstack-config set explain_level terse`. + +Always run (regardless of choice): +```bash +rm -f ~/.gstack/.writing-style-prompt-pending +touch ~/.gstack/.writing-style-prompted +``` + +This only happens once. If `WRITING_STYLE_PENDING` is `no`, skip this entirely. + If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle. Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean" @@ -365,6 +395,101 @@ Assume the user hasn't looked at this window in 20 minutes and doesn't have the Per-skill instructions may add additional formatting rules on top of this baseline. +## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output) + +These rules apply to every AskUserQuestion, every response you write to the user, and every review finding. They compose with the AskUserQuestion Format section above: Format = *how* a question is structured; Writing Style = *the prose quality of the content inside it*. + +1. **Jargon gets a one-sentence gloss on first use per skill invocation.** Even if the user's own prompt already contained the term — users often paste jargon from someone else's plan. Gloss unconditionally on first use. No cross-invocation memory: a new skill fire is a new first-use opportunity. Example: "race condition (two things happen at the same time and step on each other)". +2. **Frame questions in outcome terms, not implementation terms.** Bad: "Is this endpoint idempotent?" Good: "If someone double-clicks the button, is it OK for the action to run twice?" Ask the question the user would actually want to answer. +3. **Short sentences. Concrete nouns. Active voice.** Standard advice from any good writing guide. Prefer "the cache stores the result for 60s" over "results will have been cached for a period of 60s." +4. **Close every decision with user impact.** Connect the technical call back to who's affected. "If we skip this, your users will see a 3-second spinner on every page load." Make the user's user real. +5. **User-turn override.** If the user's current message says "be terse" / "no explanations" / "brutally honest, just the answer" / similar, skip this entire Writing Style block for your next response, regardless of config. User's in-turn request wins. +6. **Glossary boundary is the curated list.** Terms below get glossed. Terms not on the list are assumed plain-English enough. If you see a term that genuinely needs glossing but isn't listed, note it (once) in your response so it can be added via PR. + +**Jargon list** (gloss each on first use per skill invocation, if the term appears in your output): + +- idempotent +- idempotency +- race condition +- deadlock +- cyclomatic complexity +- N+1 +- N+1 query +- backpressure +- memoization +- eventual consistency +- CAP theorem +- CORS +- CSRF +- XSS +- SQL injection +- prompt injection +- DDoS +- rate limit +- throttle +- circuit breaker +- load balancer +- reverse proxy +- SSR +- CSR +- hydration +- tree-shaking +- bundle splitting +- code splitting +- hot reload +- tombstone +- soft delete +- cascade delete +- foreign key +- composite index +- covering index +- OLTP +- OLAP +- sharding +- replication lag +- quorum +- two-phase commit +- saga +- outbox pattern +- inbox pattern +- optimistic locking +- pessimistic locking +- thundering herd +- cache stampede +- bloom filter +- consistent hashing +- virtual DOM +- reconciliation +- closure +- hoisting +- tail call +- GIL +- zero-copy +- mmap +- cold start +- warm start +- green-blue deploy +- canary deploy +- feature flag +- kill switch +- dead letter queue +- fan-out +- fan-in +- debounce +- throttle (UI) +- hydration mismatch +- memory leak +- GC pause +- heap fragmentation +- stack overflow +- null pointer +- dangling pointer +- buffer overflow + +Terms not on this list are assumed plain-English enough. + +Terse mode (EXPLAIN_LEVEL: terse): skip this entire section. Emit output in V0 prose style — no glosses, no outcome-framing layer, shorter responses. Power users who know the terms get tighter output this way. + ## Completeness Principle — Boil the Lake AI makes completeness near-free. Always recommend the complete option over shortcuts — the delta is minutes with CC+gstack. A "lake" (100% coverage, all edge cases) is boilable; an "ocean" (full rewrite, multi-quarter migration) is not. Boil lakes, flag oceans.