Merge remote-tracking branch 'origin/garrytan/community-mode' into garrytan/persistent-docs

# Conflicts: # .agents/skills/gstack-browse/SKILL.md # .agents/skills/gstack-design-consultation/SKILL.md # .agents/skills/gstack-design-review/SKILL.md # .agents/skills/gstack-document-release/SKILL.md # .agents/skills/gstack-investigate/SKILL.md # .agents/skills/gstack-office-hours/SKILL.md # .agents/skills/gstack-plan-ceo-review/SKILL.md # .agents/skills/gstack-plan-design-review/SKILL.md # .agents/skills/gstack-plan-eng-review/SKILL.md # .agents/skills/gstack-qa-only/SKILL.md # .agents/skills/gstack-qa/SKILL.md # .agents/skills/gstack-retro/SKILL.md # .agents/skills/gstack-review/SKILL.md # .agents/skills/gstack-setup-browser-cookies/SKILL.md # .agents/skills/gstack-ship/SKILL.md # .agents/skills/gstack/SKILL.md # SKILL.md # browse/SKILL.md # codex/SKILL.md # design-consultation/SKILL.md # design-review/SKILL.md # document-release/SKILL.md # investigate/SKILL.md # office-hours/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 # review/SKILL.md # scripts/gen-skill-docs.ts # setup-browser-cookies/SKILL.md # ship/SKILL.md
2026-05-08 14:34:49 +02:00 · 2026-03-21 19:32:18 -07:00
parent 022de19ab3 b349769e2e
commit a14401f3db
48 changed files with 3646 additions and 3240 deletions
@@ -16,7 +16,6 @@ allowed-tools:
  - Grep
  - Glob
  - AskUserQuestion
-  - WebSearch
 hooks:
  PreToolUse:
    - matcher: "Edit"
@@ -55,6 +54,12 @@ _TEL_START=$(date +%s)
 _SESSION_ID="$$-$(date +%s)"
 echo "TELEMETRY: ${_TEL:-off}"
 echo "TEL_PROMPTED: $_TEL_PROMPTED"
+_EMAIL=$(~/.claude/skills/gstack/bin/gstack-config get email 2>/dev/null || true)
+_COMM_PROMPTED=$([ -f ~/.gstack/.community-prompted ] && echo "yes" || echo "no")
+_AUTH_OK=$(~/.claude/skills/gstack/bin/gstack-auth-refresh --check 2>/dev/null && echo "yes" || echo "no")
+echo "EMAIL: ${_EMAIL:-none}"
+echo "COMM_PROMPTED: $_COMM_PROMPTED"
+echo "AUTH: $_AUTH_OK"
 mkdir -p ~/.gstack/analytics
 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
 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
@@ -80,28 +85,31 @@ Only run `open` if the user says yes. Always run `touch` to mark as seen. This o
 If `TEL_PROMPTED` is `no` AND `LAKE_INTRO` is `yes`: After the lake intro is handled,
 ask the user about telemetry. Use AskUserQuestion:

-> Help gstack get better! Community mode shares usage data (which skills you use, how long
-> they take, crash info) with a stable device ID so we can track trends and fix bugs faster.
-> No code, file paths, or repo names are ever sent.
+> gstack can share usage data (which skills you use, how long they take, crash info)
+> to help improve the project. No code, file paths, or repo names are ever sent.
+>
+> The **community tier** unlocks extra features:
+> - **Cloud backup** of your gstack config + history (restore on new machines)
+> - **Benchmarks**: see how your usage compares to other builders
+> - **Skill recommendations** based on community patterns
+>
 > Change anytime with `gstack-config set telemetry off`.

 Options:
- A) Help gstack get better! (recommended)
- B) No thanks
+- A) Community — share data + email for backup, benchmarks & recommendations (recommended)
+- B) Anonymous — share data only, no account
+- C) No thanks

-If A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry community`
+If A: ask for their email via a follow-up AskUserQuestion, then run:
+```bash
+~/.claude/skills/gstack/bin/gstack-config set telemetry community
+~/.claude/skills/gstack/bin/gstack-auth <user-provided-email>
+```
+The auth script will send a verification code to their email. Wait for them to enter the 6-digit code.
+If auth succeeds, continue with the skill. If it fails, fall back to anonymous tier.

-If B: ask a follow-up AskUserQuestion:
-
-> How about anonymous mode? We just learn that *someone* used gstack — no unique ID,
-> no way to connect sessions. Just a counter that helps us know if anyone's out there.
-
-Options:
- A) Sure, anonymous is fine
- B) No thanks, fully off
-
-If B→A: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous`
-If B→B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off`
+If B: run `~/.claude/skills/gstack/bin/gstack-config set telemetry anonymous`
+If C: run `~/.claude/skills/gstack/bin/gstack-config set telemetry off`

 Always run:
 ```bash
@@ -110,6 +118,33 @@ touch ~/.gstack/.telemetry-prompted

 This only happens once. If `TEL_PROMPTED` is `yes`, skip this entirely.

+If `TELEMETRY` is `anonymous` AND `COMM_PROMPTED` is `no`: After the main skill workflow
+begins (not during preamble), offer the community tier upgrade once. Use AskUserQuestion:
+
+> You're already sharing anonymous usage data — nice! Want to unlock more?
+>
+> The **community tier** adds:
+> - Cloud backup of your gstack config (restore on new machines)
+> - Benchmarks: see how your /qa times compare to the community
+> - Skill recommendations based on what other builders use
+>
+> Just needs your email (verified via a one-time code).
+
+Options:
+- A) Yes, join community (enter email)
+- B) Not now
+
+If A: ask for their email, then run `~/.claude/skills/gstack/bin/gstack-auth <email>`.
+Wait for the verification code. On success, run `~/.claude/skills/gstack/bin/gstack-config set telemetry community`.
+If B: do nothing.
+
+Always run:
+```bash
+touch ~/.gstack/.community-prompted
+```
+
+This only happens once. If `COMM_PROMPTED` is `yes`, skip this entirely.
+
 ## AskUserQuestion Format

 **ALWAYS follow this structure for every AskUserQuestion call:**
@@ -147,26 +182,6 @@ AI-assisted coding makes the marginal cost of completeness near-zero. When you p
 - BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
 - BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")

-## Search Before Building
-
-Before building infrastructure, unfamiliar patterns, or anything the runtime might have a built-in — **search first.** Read `~/.claude/skills/gstack/ETHOS.md` for the full philosophy.
-
-**Three layers of knowledge:**
- **Layer 1** (tried and true — in distribution). Don't reinvent the wheel. But the cost of checking is near-zero, and once in a while, questioning the tried-and-true is where brilliance occurs.
- **Layer 2** (new and popular — search for these). But scrutinize: humans are subject to mania. Search results are inputs to your thinking, not answers.
- **Layer 3** (first principles — prize these above all). Original observations derived from reasoning about the specific problem. The most valuable of all.
-
-**Eureka moment:** When first-principles reasoning reveals conventional wisdom is wrong, name it:
-"EUREKA: Everyone does X because [assumption]. But [evidence] shows this is wrong. Y is better because [reasoning]."
-
-Log eureka moments:
-```bash
-jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" --arg skill "SKILL_NAME" --arg branch "$(git branch --show-current 2>/dev/null)" --arg insight "ONE_LINE_SUMMARY" '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
-```
-Replace SKILL_NAME and ONE_LINE_SUMMARY. Runs inline — don't stop the workflow.
-
-**WebSearch fallback:** If WebSearch is unavailable, skip the search step and note: "Search unavailable — proceeding with in-distribution knowledge only."
-
 ## Contributor Mode

 If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better.
@@ -236,10 +251,15 @@ 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).

-**PLAN MODE EXCEPTION — ALWAYS RUN:** This command writes telemetry to
-`~/.gstack/analytics/` (user config directory, not project files). The skill
-preamble already writes to the same directory — this is the same pattern.
-Skipping this command loses session duration and outcome data.
+**For errors:** Also determine:
+- `ERROR_CLASS`: a short category — one of: `timeout`, `test_failure`, `build_failure`,
+  `git_error`, `auth_error`, `network_error`, `browse_error`, `lint_error`,
+  `merge_conflict`, `permission_error`, `unknown_error`. Pick the most specific match.
+- `ERROR_MESSAGE`: a one-line summary of what went wrong (max 200 chars). Include the
+  command that failed and the key error text. Example: `"bun test: 3 tests failed in
+  auth.test.ts — expected 200 got 401"`. Never include file paths, secrets, or PII.
+- `FAILED_STEP`: which step in the skill workflow failed. Example: `"run_tests"`,
+  `"create_pr"`, `"merge_base"`, `"build"`, `"qa_browse"`. Use snake_case, max 30 chars.

 Run this bash:

@@ -249,12 +269,16 @@ _TEL_DUR=$(( _TEL_END - _TEL_START ))
 rm -f ~/.gstack/analytics/.pending-"$_SESSION_ID" 2>/dev/null || true
 ~/.claude/skills/gstack/bin/gstack-telemetry-log \
  --skill "SKILL_NAME" --duration "$_TEL_DUR" --outcome "OUTCOME" \
-  --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" 2>/dev/null &
+  --used-browse "USED_BROWSE" --session-id "$_SESSION_ID" \
+  --error-class "ERROR_CLASS" --error-message "ERROR_MESSAGE" \
+  --failed-step "FAILED_STEP" 2>/dev/null &
 ```

 Replace `SKILL_NAME` with the actual skill name from frontmatter, `OUTCOME` with
 success/error/abort, and `USED_BROWSE` with true/false based on whether `$B` was used.
-If you cannot determine the outcome, use "unknown". This runs in the background and
+For `ERROR_CLASS`, `ERROR_MESSAGE`, and `FAILED_STEP`: use empty string `""` if the
+outcome is not error. If the outcome is error but you cannot determine the details,
+use `"unknown_error"`, `""`, and `""` respectively. This runs in the background and
 never blocks the user.

 # Systematic Debugging
@@ -329,12 +353,6 @@ Also check:
 - `TODOS.md` for related known issues
 - `git log` for prior fixes in the same area — **recurring bugs in the same files are an architectural smell**, not a coincidence

-**External pattern search:** If the bug doesn't match a known pattern above, WebSearch for:
- "{framework} {generic error type}" — **sanitize first:** strip hostnames, IPs, file paths, SQL, customer data. Search the error category, not the raw message.
- "{library} {component} known issues"
-
-If WebSearch is unavailable, skip this search and proceed with hypothesis testing. If a documented solution or known dependency bug surfaces, present it as a candidate hypothesis in Phase 3.
-
 ---

 ## Phase 3: Hypothesis Testing
@@ -343,7 +361,7 @@ Before writing ANY fix, verify your hypothesis.

 1. **Confirm the hypothesis:** Add a temporary log statement, assertion, or debug output at the suspected root cause. Run the reproduction. Does the evidence match?

-2. **If the hypothesis is wrong:** Before forming the next hypothesis, consider searching for the error. **Sanitize first** — strip hostnames, IPs, file paths, SQL fragments, customer identifiers, and any internal/proprietary data from the error message. Search only the generic error type and framework context: "{component} {sanitized error type} {framework version}". If the error message is too specific to sanitize safely, skip the search. If WebSearch is unavailable, skip and proceed. Then return to Phase 1. Gather more evidence. Do not guess.
+2. **If the hypothesis is wrong:** Return to Phase 1. Gather more evidence. Do not guess.

 3. **3-strike rule:** If 3 hypotheses fail, **STOP**. Use AskUserQuestion:
   ```