mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-07 05:56:41 +02:00
Merge remote-tracking branch 'origin/main' into garrytan/usage-telemetry
# Conflicts: # SKILL.md # TODOS.md # browse/SKILL.md # design-consultation/SKILL.md # design-review/SKILL.md # document-release/SKILL.md # plan-ceo-review/SKILL.md # plan-design-review/SKILL.md # plan-eng-review/SKILL.md # qa-only/SKILL.md # qa/SKILL.md # retro/SKILL.md # retro/SKILL.md.tmpl # review/SKILL.md # scripts/gen-skill-docs.ts # setup-browser-cookies/SKILL.md # ship/SKILL.md
This commit is contained in:
Garry Tan
+120
-31
@@ -8,6 +8,8 @@ description: |
|
||||
expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
|
||||
Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
|
||||
or "is this ambitious enough".
|
||||
Proactively suggest when the user is questioning scope or ambition of a plan,
|
||||
or when the plan feels like it could be thinking bigger.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Grep
|
||||
@@ -41,7 +43,8 @@ _SESSION_ID="$$-$(date +%s)"
|
||||
echo "TELEMETRY: ${_TEL:-off}"
|
||||
echo "TEL_PROMPTED: $_TEL_PROMPTED"
|
||||
mkdir -p ~/.gstack/analytics
|
||||
for _PF in ~/.gstack/analytics/.pending-* 2>/dev/null; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done
|
||||
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
|
||||
for _PF in ~/.gstack/analytics/.pending-*; do [ -f "$_PF" ] && ~/.claude/skills/gstack/bin/gstack-telemetry-log --event-type skill_run --skill _pending_finalize --outcome unknown --session-id "$_SESSION_ID" 2>/dev/null || true; break; done
|
||||
```
|
||||
|
||||
If `PROACTIVE` is `"false"`, do not proactively suggest gstack skills — only invoke
|
||||
@@ -156,13 +159,37 @@ Hey gstack team — ran into this while using /{skill-name}:
|
||||
|
||||
Slug: lowercase, hyphens, max 60 chars (e.g. `browse-js-no-await`). Skip if file already exists. Max 3 reports per session. File inline and continue — don't stop the workflow. Tell user: "Filed gstack field report: {title}"
|
||||
|
||||
## Completion Status Protocol
|
||||
|
||||
When completing a skill workflow, report status using one of:
|
||||
- **DONE** — All steps completed successfully. Evidence provided for each claim.
|
||||
- **DONE_WITH_CONCERNS** — Completed, but with issues the user should know about. List each concern.
|
||||
- **BLOCKED** — Cannot proceed. State what is blocking and what was tried.
|
||||
- **NEEDS_CONTEXT** — Missing information required to continue. State exactly what you need.
|
||||
|
||||
### Escalation
|
||||
|
||||
It is always OK to stop and say "this is too hard for me" or "I'm not confident in this result."
|
||||
|
||||
Bad work is worse than no work. You will not be penalized for escalating.
|
||||
- If you have attempted a task 3 times without success, STOP and escalate.
|
||||
- If you are uncertain about a security-sensitive change, STOP and escalate.
|
||||
- If the scope of work exceeds what you can verify, STOP and escalate.
|
||||
|
||||
Escalation format:
|
||||
```
|
||||
STATUS: BLOCKED | NEEDS_CONTEXT
|
||||
REASON: [1-2 sentences]
|
||||
ATTEMPTED: [what you tried]
|
||||
RECOMMENDATION: [what the user should do next]
|
||||
```
|
||||
|
||||
## Telemetry (run last)
|
||||
|
||||
After the skill workflow completes (success, error, or abort), write the .pending marker
|
||||
with the actual skill name, then log the telemetry event. Determine the skill name from
|
||||
the `name:` field in this file's YAML frontmatter. Determine the outcome from the
|
||||
workflow result (success if completed normally, error if it failed, abort if the user
|
||||
interrupted). Run this bash:
|
||||
After the skill workflow completes (success, error, or abort), log the telemetry event.
|
||||
Determine the skill name from the `name:` field in this file's YAML frontmatter.
|
||||
Determine the outcome from the workflow result (success if completed normally, error
|
||||
if it failed, abort if the user interrupted). Run this bash:
|
||||
|
||||
```bash
|
||||
_TEL_END=$(date +%s)
|
||||
@@ -212,7 +239,7 @@ Do NOT make any code changes. Do NOT start implementation. Your only job right n
|
||||
|
||||
## Prime Directives
|
||||
1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan.
|
||||
2. Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what rescues it, what the user sees, and whether it's tested. rescue StandardError is a code smell — call it out.
|
||||
2. Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what catches it, what the user sees, and whether it's tested. Catch-all error handling (e.g., catch Exception, rescue StandardError, except Exception) is a code smell — call it out.
|
||||
3. Data flows have shadow paths. Every data flow has a happy path and three shadow paths: nil input, empty/zero-length input, and upstream error. Trace all four for every new flow.
|
||||
4. Interactions have edge cases. Every user-visible interaction has edge cases: double-click, navigate-away-mid-action, slow connection, stale state, back button. Map them.
|
||||
5. Observability is scope, not afterthought. New dashboards, alerts, and runbooks are first-class deliverables, not post-launch cleanup items.
|
||||
@@ -270,10 +297,22 @@ Run the following commands:
|
||||
git log --oneline -30 # Recent history
|
||||
git diff <base> --stat # What's already changed
|
||||
git stash list # Any stashed work
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l
|
||||
find . -name "*.rb" -newer Gemfile.lock | head -20 # Recently touched files
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX" -l --exclude-dir=node_modules --exclude-dir=vendor --exclude-dir=.git . | head -30
|
||||
git log --since=30.days --name-only --format="" | sort | uniq -c | sort -rn | head -20 # Recently touched files
|
||||
```
|
||||
Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically:
|
||||
Then read CLAUDE.md, TODOS.md, and any existing architecture docs.
|
||||
|
||||
**Design doc check:**
|
||||
```bash
|
||||
SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
|
||||
DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
||||
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
|
||||
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"
|
||||
```
|
||||
If a design doc exists (from `/office-hours`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design.
|
||||
|
||||
When reading TODOS.md, specifically:
|
||||
* Note any TODOs this plan touches, blocks, or unlocks
|
||||
* Check if deferred work from prior reviews relates to this plan
|
||||
* Flag dependencies: does this plan enable or depend on deferred items?
|
||||
@@ -313,6 +352,36 @@ Describe the ideal end state of this system 12 months from now. Does this plan m
|
||||
[describe] ---> [describe delta] ---> [describe target]
|
||||
```
|
||||
|
||||
### 0C-bis. Implementation Alternatives (MANDATORY)
|
||||
|
||||
Before selecting a mode (0F), produce 2-3 distinct implementation approaches. This is NOT optional — every plan must consider alternatives.
|
||||
|
||||
For each approach:
|
||||
```
|
||||
APPROACH A: [Name]
|
||||
Summary: [1-2 sentences]
|
||||
Effort: [S/M/L/XL]
|
||||
Risk: [Low/Med/High]
|
||||
Pros: [2-3 bullets]
|
||||
Cons: [2-3 bullets]
|
||||
Reuses: [existing code/patterns leveraged]
|
||||
|
||||
APPROACH B: [Name]
|
||||
...
|
||||
|
||||
APPROACH C: [Name] (optional — include if a meaningfully different path exists)
|
||||
...
|
||||
```
|
||||
|
||||
**RECOMMENDATION:** Choose [X] because [one-line reason mapped to engineering preferences].
|
||||
|
||||
Rules:
|
||||
- At least 2 approaches required. 3 preferred for non-trivial plans.
|
||||
- One approach must be the "minimal viable" (fewest files, smallest diff).
|
||||
- One approach must be the "ideal architecture" (best long-term trajectory).
|
||||
- If only one approach exists, explain concretely why alternatives were eliminated.
|
||||
- Do NOT proceed to mode selection (0F) without user approval of the chosen approach.
|
||||
|
||||
### 0D. Mode-Specific Analysis
|
||||
**For SCOPE EXPANSION** — run all three, then the opt-in ceremony:
|
||||
1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely.
|
||||
@@ -342,8 +411,7 @@ Describe the ideal end state of this system 12 months from now. Does this plan m
|
||||
After the opt-in/cherry-pick ceremony, write the plan to disk so the vision and decisions survive beyond this conversation. Only run this step for EXPANSION and SELECTIVE EXPANSION modes.
|
||||
|
||||
```bash
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
```
|
||||
|
||||
Before writing, check for existing CEO plans in the ceo-plans/ directory. If any are >30 days old or their branch has been merged/deleted, offer to archive them:
|
||||
@@ -420,6 +488,8 @@ Context-dependent defaults:
|
||||
* User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question
|
||||
* User says "hold scope but tempt me" / "show me options" / "cherry-pick" → SELECTIVE EXPANSION, no question
|
||||
|
||||
After mode is selected, confirm which implementation approach (from 0C-bis) applies under the chosen mode. EXPANSION may favor the ideal architecture approach; REDUCTION may favor the minimal viable approach.
|
||||
|
||||
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.
|
||||
|
||||
@@ -456,24 +526,24 @@ For every new method, service, or codepath that can fail, fill in this table:
|
||||
```
|
||||
METHOD/CODEPATH | WHAT CAN GO WRONG | EXCEPTION CLASS
|
||||
-------------------------|-----------------------------|-----------------
|
||||
ExampleService#call | API timeout | Faraday::TimeoutError
|
||||
ExampleService#call | API timeout | TimeoutError
|
||||
| API returns 429 | RateLimitError
|
||||
| API returns malformed JSON | JSON::ParserError
|
||||
| DB connection pool exhausted| ActiveRecord::ConnectionTimeoutError
|
||||
| Record not found | ActiveRecord::RecordNotFound
|
||||
| API returns malformed JSON | JSONParseError
|
||||
| DB connection pool exhausted| ConnectionPoolExhausted
|
||||
| Record not found | RecordNotFound
|
||||
-------------------------|-----------------------------|-----------------
|
||||
|
||||
EXCEPTION CLASS | RESCUED? | RESCUE ACTION | USER SEES
|
||||
-----------------------------|-----------|------------------------|------------------
|
||||
Faraday::TimeoutError | Y | Retry 2x, then raise | "Service temporarily unavailable"
|
||||
TimeoutError | Y | Retry 2x, then raise | "Service temporarily unavailable"
|
||||
RateLimitError | Y | Backoff + retry | Nothing (transparent)
|
||||
JSON::ParserError | N ← GAP | — | 500 error ← BAD
|
||||
ConnectionTimeoutError | N ← GAP | — | 500 error ← BAD
|
||||
ActiveRecord::RecordNotFound | Y | Return nil, log warning | "Not found" message
|
||||
JSONParseError | N ← GAP | — | 500 error ← BAD
|
||||
ConnectionPoolExhausted | N ← GAP | — | 500 error ← BAD
|
||||
RecordNotFound | Y | Return nil, log warning | "Not found" message
|
||||
```
|
||||
Rules for this section:
|
||||
* `rescue StandardError` is ALWAYS a smell. Name the specific exceptions.
|
||||
* `rescue => e` with only `Rails.logger.error(e.message)` is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
|
||||
* Catch-all error handling (`rescue StandardError`, `catch (Exception e)`, `except Exception`) is ALWAYS a smell. Name the specific exceptions.
|
||||
* Catching an error with only a generic log message is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
|
||||
* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
|
||||
* 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.
|
||||
@@ -770,9 +840,7 @@ If any AskUserQuestion goes unanswered, note it here. Never silently default.
|
||||
After producing the Completion Summary above, persist the review result:
|
||||
|
||||
```bash
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
mkdir -p ~/.gstack/projects/$SLUG
|
||||
echo '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Before running this command, substitute the placeholder values from the Completion Summary you just produced:
|
||||
@@ -781,19 +849,17 @@ Before running this command, substitute the placeholder values from the Completi
|
||||
- **unresolved**: number from "Unresolved decisions" in the summary
|
||||
- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
|
||||
- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
## Review Readiness Dashboard
|
||||
|
||||
After completing the review, read the review log and config to display the dashboard.
|
||||
|
||||
```bash
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
cat ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl 2>/dev/null || echo "NO_REVIEWS"
|
||||
echo "---CONFIG---"
|
||||
~/.claude/skills/gstack/bin/gstack-config get skip_eng_review 2>/dev/null || echo "false"
|
||||
~/.claude/skills/gstack/bin/gstack-review-read
|
||||
```
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, plan-design-review, design-review-lite). Ignore entries with timestamps older than 7 days. For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. Display:
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, plan-design-review, design-review-lite, codex-review). Ignore entries with timestamps older than 7 days. For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. Display:
|
||||
|
||||
```
|
||||
+====================================================================+
|
||||
@@ -804,6 +870,7 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
|
||||
| Eng Review | 1 | 2026-03-16 15:00 | CLEAR | YES |
|
||||
| CEO Review | 0 | — | — | no |
|
||||
| Design Review | 0 | — | — | no |
|
||||
| Codex Review | 0 | — | — | no |
|
||||
+--------------------------------------------------------------------+
|
||||
| VERDICT: CLEARED — Eng Review passed |
|
||||
+====================================================================+
|
||||
@@ -813,13 +880,35 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
|
||||
- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
|
||||
- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
|
||||
- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
|
||||
- **Codex Review (optional):** Independent second opinion from OpenAI Codex CLI. Shows pass/fail gate. Recommend for critical code changes where a second AI perspective adds value. Skip when Codex CLI is not installed.
|
||||
|
||||
**Verdict logic:**
|
||||
- **CLEARED**: Eng Review has >= 1 entry within 7 days with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
|
||||
- CEO and Design reviews are shown for context but never block shipping
|
||||
- CEO, Design, and Codex reviews are shown for context but never block shipping
|
||||
- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
|
||||
|
||||
**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
|
||||
- Parse the \`---HEAD---\` section from the bash output to get the current HEAD commit hash
|
||||
- For each review entry that has a \`commit\` field: compare it against the current HEAD. If different, count elapsed commits: \`git rev-list --count STORED_COMMIT..HEAD\`. Display: "Note: {skill} review from {date} may be stale — {N} commits since review"
|
||||
- For entries without a \`commit\` field (legacy entries): display "Note: {skill} review from {date} has no commit tracking — consider re-running for accurate staleness detection"
|
||||
- If all reviews match the current HEAD, do not display any staleness notes
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
|
||||
|
||||
**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate), then design review.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-design-review next (only if UI scope detected)
|
||||
- **C)** Skip — I'll handle reviews manually
|
||||
|
||||
## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
|
||||
|
||||
At the end of the review, if the vision produced a compelling feature direction, offer to promote the CEO plan to the project repo. AskUserQuestion:
|
||||
|
||||
@@ -8,6 +8,8 @@ description: |
|
||||
expansions), HOLD SCOPE (maximum rigor), SCOPE REDUCTION (strip to essentials).
|
||||
Use when asked to "think bigger", "expand scope", "strategy review", "rethink this",
|
||||
or "is this ambitious enough".
|
||||
Proactively suggest when the user is questioning scope or ambition of a plan,
|
||||
or when the plan feels like it could be thinking bigger.
|
||||
allowed-tools:
|
||||
- Read
|
||||
- Grep
|
||||
@@ -35,7 +37,7 @@ Do NOT make any code changes. Do NOT start implementation. Your only job right n
|
||||
|
||||
## Prime Directives
|
||||
1. Zero silent failures. Every failure mode must be visible — to the system, to the team, to the user. If a failure can happen silently, that is a critical defect in the plan.
|
||||
2. Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what rescues it, what the user sees, and whether it's tested. rescue StandardError is a code smell — call it out.
|
||||
2. Every error has a name. Don't say "handle errors." Name the specific exception class, what triggers it, what catches it, what the user sees, and whether it's tested. Catch-all error handling (e.g., catch Exception, rescue StandardError, except Exception) is a code smell — call it out.
|
||||
3. Data flows have shadow paths. Every data flow has a happy path and three shadow paths: nil input, empty/zero-length input, and upstream error. Trace all four for every new flow.
|
||||
4. Interactions have edge cases. Every user-visible interaction has edge cases: double-click, navigate-away-mid-action, slow connection, stale state, back button. Map them.
|
||||
5. Observability is scope, not afterthought. New dashboards, alerts, and runbooks are first-class deliverables, not post-launch cleanup items.
|
||||
@@ -93,10 +95,22 @@ Run the following commands:
|
||||
git log --oneline -30 # Recent history
|
||||
git diff <base> --stat # What's already changed
|
||||
git stash list # Any stashed work
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX" --include="*.rb" --include="*.js" -l
|
||||
find . -name "*.rb" -newer Gemfile.lock | head -20 # Recently touched files
|
||||
grep -r "TODO\|FIXME\|HACK\|XXX" -l --exclude-dir=node_modules --exclude-dir=vendor --exclude-dir=.git . | head -30
|
||||
git log --since=30.days --name-only --format="" | sort | uniq -c | sort -rn | head -20 # Recently touched files
|
||||
```
|
||||
Then read CLAUDE.md, TODOS.md, and any existing architecture docs. When reading TODOS.md, specifically:
|
||||
Then read CLAUDE.md, TODOS.md, and any existing architecture docs.
|
||||
|
||||
**Design doc check:**
|
||||
```bash
|
||||
SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
|
||||
DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
|
||||
[ -z "$DESIGN" ] && DESIGN=$(ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null | head -1)
|
||||
[ -n "$DESIGN" ] && echo "Design doc found: $DESIGN" || echo "No design doc found"
|
||||
```
|
||||
If a design doc exists (from `/office-hours`), read it. Use it as the source of truth for the problem statement, constraints, and chosen approach. If it has a `Supersedes:` field, note that this is a revised design.
|
||||
|
||||
When reading TODOS.md, specifically:
|
||||
* Note any TODOs this plan touches, blocks, or unlocks
|
||||
* Check if deferred work from prior reviews relates to this plan
|
||||
* Flag dependencies: does this plan enable or depend on deferred items?
|
||||
@@ -136,6 +150,36 @@ Describe the ideal end state of this system 12 months from now. Does this plan m
|
||||
[describe] ---> [describe delta] ---> [describe target]
|
||||
```
|
||||
|
||||
### 0C-bis. Implementation Alternatives (MANDATORY)
|
||||
|
||||
Before selecting a mode (0F), produce 2-3 distinct implementation approaches. This is NOT optional — every plan must consider alternatives.
|
||||
|
||||
For each approach:
|
||||
```
|
||||
APPROACH A: [Name]
|
||||
Summary: [1-2 sentences]
|
||||
Effort: [S/M/L/XL]
|
||||
Risk: [Low/Med/High]
|
||||
Pros: [2-3 bullets]
|
||||
Cons: [2-3 bullets]
|
||||
Reuses: [existing code/patterns leveraged]
|
||||
|
||||
APPROACH B: [Name]
|
||||
...
|
||||
|
||||
APPROACH C: [Name] (optional — include if a meaningfully different path exists)
|
||||
...
|
||||
```
|
||||
|
||||
**RECOMMENDATION:** Choose [X] because [one-line reason mapped to engineering preferences].
|
||||
|
||||
Rules:
|
||||
- At least 2 approaches required. 3 preferred for non-trivial plans.
|
||||
- One approach must be the "minimal viable" (fewest files, smallest diff).
|
||||
- One approach must be the "ideal architecture" (best long-term trajectory).
|
||||
- If only one approach exists, explain concretely why alternatives were eliminated.
|
||||
- Do NOT proceed to mode selection (0F) without user approval of the chosen approach.
|
||||
|
||||
### 0D. Mode-Specific Analysis
|
||||
**For SCOPE EXPANSION** — run all three, then the opt-in ceremony:
|
||||
1. 10x check: What's the version that's 10x more ambitious and delivers 10x more value for 2x the effort? Describe it concretely.
|
||||
@@ -165,8 +209,7 @@ Describe the ideal end state of this system 12 months from now. Does this plan m
|
||||
After the opt-in/cherry-pick ceremony, write the plan to disk so the vision and decisions survive beyond this conversation. Only run this step for EXPANSION and SELECTIVE EXPANSION modes.
|
||||
|
||||
```bash
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
source <(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null) && mkdir -p ~/.gstack/projects/$SLUG/ceo-plans
|
||||
```
|
||||
|
||||
Before writing, check for existing CEO plans in the ceo-plans/ directory. If any are >30 days old or their branch has been merged/deleted, offer to archive them:
|
||||
@@ -243,6 +286,8 @@ Context-dependent defaults:
|
||||
* User says "go big" / "ambitious" / "cathedral" → EXPANSION, no question
|
||||
* User says "hold scope but tempt me" / "show me options" / "cherry-pick" → SELECTIVE EXPANSION, no question
|
||||
|
||||
After mode is selected, confirm which implementation approach (from 0C-bis) applies under the chosen mode. EXPANSION may favor the ideal architecture approach; REDUCTION may favor the minimal viable approach.
|
||||
|
||||
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.
|
||||
|
||||
@@ -279,24 +324,24 @@ For every new method, service, or codepath that can fail, fill in this table:
|
||||
```
|
||||
METHOD/CODEPATH | WHAT CAN GO WRONG | EXCEPTION CLASS
|
||||
-------------------------|-----------------------------|-----------------
|
||||
ExampleService#call | API timeout | Faraday::TimeoutError
|
||||
ExampleService#call | API timeout | TimeoutError
|
||||
| API returns 429 | RateLimitError
|
||||
| API returns malformed JSON | JSON::ParserError
|
||||
| DB connection pool exhausted| ActiveRecord::ConnectionTimeoutError
|
||||
| Record not found | ActiveRecord::RecordNotFound
|
||||
| API returns malformed JSON | JSONParseError
|
||||
| DB connection pool exhausted| ConnectionPoolExhausted
|
||||
| Record not found | RecordNotFound
|
||||
-------------------------|-----------------------------|-----------------
|
||||
|
||||
EXCEPTION CLASS | RESCUED? | RESCUE ACTION | USER SEES
|
||||
-----------------------------|-----------|------------------------|------------------
|
||||
Faraday::TimeoutError | Y | Retry 2x, then raise | "Service temporarily unavailable"
|
||||
TimeoutError | Y | Retry 2x, then raise | "Service temporarily unavailable"
|
||||
RateLimitError | Y | Backoff + retry | Nothing (transparent)
|
||||
JSON::ParserError | N ← GAP | — | 500 error ← BAD
|
||||
ConnectionTimeoutError | N ← GAP | — | 500 error ← BAD
|
||||
ActiveRecord::RecordNotFound | Y | Return nil, log warning | "Not found" message
|
||||
JSONParseError | N ← GAP | — | 500 error ← BAD
|
||||
ConnectionPoolExhausted | N ← GAP | — | 500 error ← BAD
|
||||
RecordNotFound | Y | Return nil, log warning | "Not found" message
|
||||
```
|
||||
Rules for this section:
|
||||
* `rescue StandardError` is ALWAYS a smell. Name the specific exceptions.
|
||||
* `rescue => e` with only `Rails.logger.error(e.message)` is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
|
||||
* Catch-all error handling (`rescue StandardError`, `catch (Exception e)`, `except Exception`) is ALWAYS a smell. Name the specific exceptions.
|
||||
* Catching an error with only a generic log message is insufficient. Log the full context: what was being attempted, with what arguments, for what user/request.
|
||||
* Every rescued error must either: retry with backoff, degrade gracefully with a user-visible message, or re-raise with added context. "Swallow and continue" is almost never acceptable.
|
||||
* 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.
|
||||
@@ -593,9 +638,7 @@ If any AskUserQuestion goes unanswered, note it here. Never silently default.
|
||||
After producing the Completion Summary above, persist the review result:
|
||||
|
||||
```bash
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
mkdir -p ~/.gstack/projects/$SLUG
|
||||
echo '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE"}' >> ~/.gstack/projects/$SLUG/$BRANCH-reviews.jsonl
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-ceo-review","timestamp":"TIMESTAMP","status":"STATUS","unresolved":N,"critical_gaps":N,"mode":"MODE","commit":"COMMIT"}'
|
||||
```
|
||||
|
||||
Before running this command, substitute the placeholder values from the Completion Summary you just produced:
|
||||
@@ -604,9 +647,25 @@ Before running this command, substitute the placeholder values from the Completi
|
||||
- **unresolved**: number from "Unresolved decisions" in the summary
|
||||
- **critical_gaps**: number from "Failure modes: ___ CRITICAL GAPS" in the summary
|
||||
- **MODE**: the mode the user selected (SCOPE_EXPANSION / SELECTIVE_EXPANSION / HOLD_SCOPE / SCOPE_REDUCTION)
|
||||
- **COMMIT**: output of `git rev-parse --short HEAD`
|
||||
|
||||
{{REVIEW_DASHBOARD}}
|
||||
|
||||
## Next Steps — Review Chaining
|
||||
|
||||
After displaying the Review Readiness Dashboard, recommend the next review(s) based on what this CEO review discovered. Read the dashboard output to see which reviews have already been run and whether they are stale.
|
||||
|
||||
**Recommend /plan-eng-review if eng review is not skipped globally** — check the dashboard output for `skip_eng_review`. If it is `true`, eng review is opted out — do not recommend it. Otherwise, eng review is the required shipping gate. If this CEO review expanded scope, changed architectural direction, or accepted scope expansions, emphasize that a fresh eng review is needed. If an eng review already exists in the dashboard but the commit hash shows it predates this CEO review, note that it may be stale and should be re-run.
|
||||
|
||||
**Recommend /plan-design-review if UI scope was detected** — specifically if Section 11 (Design & UX Review) was NOT skipped, or if accepted scope expansions included UI-facing features. If an existing design review is stale (commit hash drift), note that. In SCOPE REDUCTION mode, skip this recommendation — design review is unlikely relevant for scope cuts.
|
||||
|
||||
**If both are needed, recommend eng review first** (required gate), then design review.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-design-review next (only if UI scope detected)
|
||||
- **C)** Skip — I'll handle reviews manually
|
||||
|
||||
## docs/designs Promotion (EXPANSION and SELECTIVE EXPANSION only)
|
||||
|
||||
At the end of the review, if the vision produced a compelling feature direction, offer to promote the CEO plan to the project repo. AskUserQuestion:
|
||||
|
||||
Reference in New Issue
Block a user