From b45a7d064d56b0c020bda5e365115e4ef707efdb Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Tue, 14 Apr 2026 10:53:05 -0700 Subject: [PATCH] chore: regenerate all SKILL.md files Regenerated from templates after Confusion Protocol, GBrain resolver placeholders, slop:diff in review, HARD GATE reminders, investigation learnings, design doc visibility, and retro non-git context changes. Co-Authored-By: Claude Opus 4.6 (1M context) --- autoplan/SKILL.md | 13 +++++++++++++ canary/SKILL.md | 13 +++++++++++++ checkpoint/SKILL.md | 13 +++++++++++++ codex/SKILL.md | 13 +++++++++++++ cso/SKILL.md | 13 +++++++++++++ design-consultation/SKILL.md | 13 +++++++++++++ design-html/SKILL.md | 13 +++++++++++++ design-review/SKILL.md | 13 +++++++++++++ design-shotgun/SKILL.md | 13 +++++++++++++ devex-review/SKILL.md | 13 +++++++++++++ document-release/SKILL.md | 13 +++++++++++++ health/SKILL.md | 13 +++++++++++++ investigate/SKILL.md | 25 +++++++++++++++++++++++++ land-and-deploy/SKILL.md | 13 +++++++++++++ learn/SKILL.md | 13 +++++++++++++ office-hours/SKILL.md | 22 +++++++++++++++++++++- open-gstack-browser/SKILL.md | 13 +++++++++++++ pair-agent/SKILL.md | 13 +++++++++++++ plan-ceo-review/SKILL.md | 29 +++++++++++++++++++++++++++++ plan-design-review/SKILL.md | 13 +++++++++++++ plan-devex-review/SKILL.md | 13 +++++++++++++ plan-eng-review/SKILL.md | 13 +++++++++++++ qa-only/SKILL.md | 13 +++++++++++++ qa/SKILL.md | 13 +++++++++++++ retro/SKILL.md | 27 +++++++++++++++++++++++++++ review/SKILL.md | 26 ++++++++++++++++++++++++++ setup-deploy/SKILL.md | 13 +++++++++++++ ship/SKILL.md | 13 +++++++++++++ 28 files changed, 427 insertions(+), 1 deletion(-) diff --git a/autoplan/SKILL.md b/autoplan/SKILL.md index 7b05d620..6b71dc5e 100644 --- a/autoplan/SKILL.md +++ b/autoplan/SKILL.md @@ -383,6 +383,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/canary/SKILL.md b/canary/SKILL.md index 6cf76203..79ac9594 100644 --- a/canary/SKILL.md +++ b/canary/SKILL.md @@ -375,6 +375,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/checkpoint/SKILL.md b/checkpoint/SKILL.md index 22b5d3ad..cdc3fc3c 100644 --- a/checkpoint/SKILL.md +++ b/checkpoint/SKILL.md @@ -378,6 +378,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/codex/SKILL.md b/codex/SKILL.md index 9b40b27e..fa5ff728 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -377,6 +377,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/cso/SKILL.md b/cso/SKILL.md index 89f2b13f..26ae171f 100644 --- a/cso/SKILL.md +++ b/cso/SKILL.md @@ -380,6 +380,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/design-consultation/SKILL.md b/design-consultation/SKILL.md index 68e48879..c066288c 100644 --- a/design-consultation/SKILL.md +++ b/design-consultation/SKILL.md @@ -380,6 +380,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/design-html/SKILL.md b/design-html/SKILL.md index 10aaece0..e030cf93 100644 --- a/design-html/SKILL.md +++ b/design-html/SKILL.md @@ -382,6 +382,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/design-review/SKILL.md b/design-review/SKILL.md index b87c509d..abcc3c6d 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -380,6 +380,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/design-shotgun/SKILL.md b/design-shotgun/SKILL.md index d254d9d2..f00bed78 100644 --- a/design-shotgun/SKILL.md +++ b/design-shotgun/SKILL.md @@ -377,6 +377,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/devex-review/SKILL.md b/devex-review/SKILL.md index 96575fea..31defe1b 100644 --- a/devex-review/SKILL.md +++ b/devex-review/SKILL.md @@ -380,6 +380,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/document-release/SKILL.md b/document-release/SKILL.md index 90b84d2d..84001853 100644 --- a/document-release/SKILL.md +++ b/document-release/SKILL.md @@ -377,6 +377,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/health/SKILL.md b/health/SKILL.md index f8f7b2ae..46dcac22 100644 --- a/health/SKILL.md +++ b/health/SKILL.md @@ -377,6 +377,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/investigate/SKILL.md b/investigate/SKILL.md index 30feccd0..d4f86d80 100644 --- a/investigate/SKILL.md +++ b/investigate/SKILL.md @@ -392,6 +392,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: @@ -559,6 +572,8 @@ Fixing symptoms creates whack-a-mole debugging. Every fix that doesn't address r --- + + ## Phase 1: Root Cause Investigation Gather context before forming any hypothesis. @@ -575,6 +590,8 @@ Gather context before forming any hypothesis. 4. **Reproduce:** Can you trigger the bug deterministically? If not, gather more evidence before proceeding. +5. **Check investigation history:** Search prior learnings for investigations on the same files. Recurring bugs in the same area are an architectural smell. If prior investigations exist, note patterns and check if the root cause was structural. + ## Prior Learnings Search for relevant learnings from previous sessions: @@ -736,6 +753,12 @@ Status: DONE | DONE_WITH_CONCERNS | BLOCKED ════════════════════════════════════════ ``` +Log the investigation as a learning for future sessions. Use `type: "investigation"` and include the affected files so future investigations on the same area can find this: + +```bash +~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"investigate","type":"investigation","key":"ROOT_CAUSE_KEY","insight":"ROOT_CAUSE_SUMMARY","confidence":9,"source":"observed","files":["affected/file1.ts","affected/file2.ts"]}' +``` + ## Capture Learnings If you discovered a non-obvious pattern, pitfall, or architectural insight during @@ -761,6 +784,8 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. + + --- ## Important Rules diff --git a/land-and-deploy/SKILL.md b/land-and-deploy/SKILL.md index 64402009..9017f075 100644 --- a/land-and-deploy/SKILL.md +++ b/land-and-deploy/SKILL.md @@ -374,6 +374,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/learn/SKILL.md b/learn/SKILL.md index 656ae76b..61a02d3f 100644 --- a/learn/SKILL.md +++ b/learn/SKILL.md @@ -377,6 +377,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/office-hours/SKILL.md b/office-hours/SKILL.md index bcb3557c..89208bdd 100644 --- a/office-hours/SKILL.md +++ b/office-hours/SKILL.md @@ -384,6 +384,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: @@ -603,6 +616,8 @@ You are a **YC office hours partner**. Your job is to ensure the problem is unde --- + + ## Phase 1: Context Gathering Understand the project and the area the user wants to change. @@ -1322,7 +1337,10 @@ PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head ``` If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions. -Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`: +Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`. + +After writing the design doc, tell the user: +**"Design doc saved to: {full path}. Other skills (/plan-ceo-review, /plan-eng-review) will find it automatically."** ### Startup mode design doc template: @@ -1511,6 +1529,8 @@ Present the reviewed design doc to the user via AskUserQuestion: - B) Revise — specify which sections need changes (loop back to revise those sections) - C) Start over — return to Phase 2 + + --- ## Phase 6: Handoff — The Relationship Closing diff --git a/open-gstack-browser/SKILL.md b/open-gstack-browser/SKILL.md index 126bd5fb..2c049250 100644 --- a/open-gstack-browser/SKILL.md +++ b/open-gstack-browser/SKILL.md @@ -374,6 +374,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/pair-agent/SKILL.md b/pair-agent/SKILL.md index 6a7ddbbb..db5814c0 100644 --- a/pair-agent/SKILL.md +++ b/pair-agent/SKILL.md @@ -375,6 +375,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-ceo-review/SKILL.md b/plan-ceo-review/SKILL.md index 78e87f4d..13bbd469 100644 --- a/plan-ceo-review/SKILL.md +++ b/plan-ceo-review/SKILL.md @@ -380,6 +380,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: @@ -868,6 +881,8 @@ matches a past learning, display: This makes the compounding visible. The user should see that gstack is getting smarter on their codebase over time. + + ## Step 0: Nuclear Scope Challenge + Mode Selection ### 0A. Premise Challenge @@ -1090,6 +1105,7 @@ After mode is selected, confirm which implementation approach (from 0C-bis) appl Once selected, commit fully. Do not silently drift. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ## Review Sections (11 sections, after scope and mode are agreed) @@ -1119,6 +1135,7 @@ Evaluate and diagram: Required ASCII diagram: full system architecture showing new components and their relationships to existing ones. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 2: Error & Rescue Map This is the section that catches silent failures. It is not optional. @@ -1148,6 +1165,7 @@ Rules for this section: * For each GAP (unrescued error that should be rescued): specify the rescue action and what the user should see. * For LLM/AI service calls specifically: what happens when the response is malformed? When it's empty? When it hallucinates invalid JSON? When the model returns a refusal? Each of these is a distinct failure mode. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 3: Security & Threat Model Security is not a sub-bullet of architecture. It gets its own section. @@ -1163,6 +1181,7 @@ Evaluate: For each finding: threat, likelihood (High/Med/Low), impact (High/Med/Low), and whether the plan mitigates it. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 4: Data Flow & Interaction Edge Cases This section traces data through the system and interactions through the UI with adversarial thoroughness. @@ -1199,6 +1218,7 @@ For each node: what happens on each shadow path? Is it tested? ``` Flag any unhandled edge case as a gap. For each gap, specify the fix. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 5: Code Quality Review Evaluate: @@ -1211,6 +1231,7 @@ Evaluate: * Under-engineering check. Anything fragile, assuming happy path only, or missing obvious defensive checks? * Cyclomatic complexity. Flag any new method that branches more than 5 times. Propose a refactor. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 6: Test Review Make a complete diagram of every new thing this plan introduces: @@ -1251,6 +1272,7 @@ Load/stress test requirements: For any new codepath called frequently or process For LLM/prompt changes: Check CLAUDE.md for the "Prompt/LLM changes" file patterns. If this plan touches ANY of those patterns, state which eval suites must be run, which cases should be added, and what baselines to compare against. **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 7: Performance Review Evaluate: @@ -1262,6 +1284,7 @@ Evaluate: * Slow paths. Top 3 slowest new codepaths and estimated p99 latency. * Connection pool pressure. New DB connections, Redis connections, HTTP connections? **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 8: Observability & Debuggability Review New systems break. This section ensures you can see why. @@ -1278,6 +1301,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What observability would make this feature a joy to operate? (For SELECTIVE EXPANSION, include observability for any accepted cherry-picks.) **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 9: Deployment & Rollout Review Evaluate: @@ -1293,6 +1317,7 @@ Evaluate: **EXPANSION and SELECTIVE EXPANSION addition:** * What deploy infrastructure would make shipping this feature routine? (For SELECTIVE EXPANSION, assess whether accepted cherry-picks change the deployment risk profile.) **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 10: Long-Term Trajectory Review Evaluate: @@ -1308,6 +1333,7 @@ Evaluate: * Platform potential. Does this create capabilities other features can leverage? * (SELECTIVE EXPANSION only) Retrospective: Were the right cherry-picks accepted? Did any rejected expansions turn out to be load-bearing for the accepted ones? **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ### Section 11: Design & UX Review (skip if no UI scope detected) The CEO calling in the designer. Not a pixel-level audit — that's /plan-design-review and /design-review. This is ensuring the plan has design intentionality. @@ -1330,6 +1356,7 @@ Required ASCII diagram: user flow showing screens/states and transitions. If this plan has significant UI scope, recommend: "Consider running /plan-design-review for a deep design review of this plan before implementation." **STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues or fix is obvious, state what you'll do and move on — don't waste a question. Do NOT proceed until user responds. +**Reminder: Do NOT make any code changes. Review only.** ## Outside Voice — Independent Plan Challenge (optional, recommended) @@ -1797,6 +1824,8 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. + + ## Mode Quick Reference ``` ┌────────────────────────────────────────────────────────────────────────────────┐ diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md index bc9a1d16..89139061 100644 --- a/plan-design-review/SKILL.md +++ b/plan-design-review/SKILL.md @@ -378,6 +378,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-devex-review/SKILL.md b/plan-devex-review/SKILL.md index 56a51ba2..a9d2ddab 100644 --- a/plan-devex-review/SKILL.md +++ b/plan-devex-review/SKILL.md @@ -382,6 +382,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/plan-eng-review/SKILL.md b/plan-eng-review/SKILL.md index 93f71bd7..22d406ce 100644 --- a/plan-eng-review/SKILL.md +++ b/plan-eng-review/SKILL.md @@ -380,6 +380,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/qa-only/SKILL.md b/qa-only/SKILL.md index f1eeedff..23ac8fca 100644 --- a/qa-only/SKILL.md +++ b/qa-only/SKILL.md @@ -376,6 +376,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/qa/SKILL.md b/qa/SKILL.md index edb475c9..d6cfb43b 100644 --- a/qa/SKILL.md +++ b/qa/SKILL.md @@ -382,6 +382,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: diff --git a/retro/SKILL.md b/retro/SKILL.md index b2f43419..68d457c3 100644 --- a/retro/SKILL.md +++ b/retro/SKILL.md @@ -375,6 +375,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: @@ -588,6 +601,8 @@ When the user types `/retro`, run this skill. - `/retro global` — cross-project retro across all AI coding tools (7d default) - `/retro global 14d` — cross-project retro with explicit window + + ## Instructions Parse the argument to determine the time window. Default to 7 days if no argument given. All times should be reported in the user's **local timezone** (use the system default — do NOT set `TZ`). @@ -647,6 +662,16 @@ matches a past learning, display: This makes the compounding visible. The user should see that gstack is getting smarter on their codebase over time. +### Non-git context (optional) + +Check for non-git context that should be included in the retro: + +```bash +[ -f ~/.gstack/retro-context.md ] && echo "RETRO_CONTEXT_FOUND" || echo "NO_RETRO_CONTEXT" +``` + +If `RETRO_CONTEXT_FOUND`: read `~/.gstack/retro-context.md`. This file is user-authored and may contain meeting notes, calendar events, decisions, and other context that doesn't appear in git history. Incorporate this context into the retro narrative where relevant. + ### Step 1: Gather Raw Data First, fetch origin and identify the current user: @@ -891,6 +916,8 @@ staleness detection: if those files are later deleted, the learning can be flagg **Only log genuine discoveries.** Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it. + + ### Step 10: Week-over-Week Trends (if window >= 14d) If the time window is 14 days or more, split into weekly buckets and show trends: diff --git a/review/SKILL.md b/review/SKILL.md index 9e2965db..2bd2df1b 100644 --- a/review/SKILL.md +++ b/review/SKILL.md @@ -378,6 +378,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: @@ -842,6 +855,19 @@ git fetch origin --quiet Run `git diff origin/` to get the full diff. This includes both committed and uncommitted changes against the latest base branch. +## Step 3.5: Slop scan (advisory) + +Run a slop scan on changed files to catch AI code quality issues (empty catches, +redundant `return await`, overcomplicated abstractions): + +```bash +bun run slop:diff origin/ 2>/dev/null || true +``` + +If findings are reported, include them in the review output as an informational +diagnostic. Slop findings are advisory, never blocking. If slop:diff is not +available (e.g., slop-scan not installed), skip this step silently. + --- ## Prior Learnings diff --git a/setup-deploy/SKILL.md b/setup-deploy/SKILL.md index 41ba613e..1c7e7dee 100644 --- a/setup-deploy/SKILL.md +++ b/setup-deploy/SKILL.md @@ -378,6 +378,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Completion Status Protocol When completing a skill workflow, report status using one of: diff --git a/ship/SKILL.md b/ship/SKILL.md index f3bfd626..df43048c 100644 --- a/ship/SKILL.md +++ b/ship/SKILL.md @@ -379,6 +379,19 @@ AI makes completeness near-free. Always recommend the complete option over short Include `Completeness: X/10` for each option (10=all edge cases, 7=happy path, 3=shortcut). +## Confusion Protocol + +When you encounter high-stakes ambiguity during coding: +- Two plausible architectures or data models for the same requirement +- A request that contradicts existing patterns and you're unsure which to follow +- A destructive operation where the scope is unclear +- Missing context that would change your approach significantly + +STOP. Name the ambiguity in one sentence. Present 2-3 options with tradeoffs. +Ask the user. Do not guess on architectural or data model decisions. + +This does NOT apply to routine coding, small features, or obvious changes. + ## Repo Ownership — See Something, Say Something `REPO_MODE` controls how to handle issues outside your branch: