From cdccdf95dd3ae48297bd090404f5daff5ff246e6 Mon Sep 17 00:00:00 2001 From: serenakeyitan Date: Thu, 23 Apr 2026 13:56:38 -0700 Subject: [PATCH 1/2] docs(onboarding): add 6.4.b real source-PR trigger to close #328 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Step 6.4 already demonstrated the tree side of the chain via manual gardener sync, but never stitched in the source-PR leg the README CTA promises ("source PR → tree issue → breeze pickup → draft-node PR"). Cold-start E2E on #327 confirmed the gap: a fresh agent following tree help onboarding has to invent the final leg. Split 6.4 into two labeled sub-steps: - 6.4.a (manual trigger, ~1 min) — existing gardener sync invocation, keeps the fast credential check path. - 6.4.b (real source-PR trigger, ~5 min, optional) — scripts the actual automatic chain: open a trivial source-repo PR, watch breeze pick it up via `breeze watch` / `breeze status`, confirm gardener posted a verdict, clean up. Verified command surfaces against src/products/breeze/cli.ts: - `breeze watch` is the live TUI (not `status --watch`) - `breeze status` is one-shot - `breeze doctor` reports interval + auth state Closes #328. --- skills/first-tree/references/onboarding.md | 54 +++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/skills/first-tree/references/onboarding.md b/skills/first-tree/references/onboarding.md index f41ddab..973d356 100644 --- a/skills/first-tree/references/onboarding.md +++ b/skills/first-tree/references/onboarding.md @@ -235,7 +235,12 @@ gardener as needed. ### 6.4 Verify End-To-End -Trigger one drift event: +Do the short manual trigger first, then optionally run a real source-PR +trigger to prove the full automatic chain. + +**6.4.a — Manual trigger (fast, ~1 min).** Fires gardener directly, so +you can confirm credentials and the tree side of the chain without +waiting on GitHub's notification delivery: ```bash TREE_REPO_TOKEN=$(gh auth token) \ @@ -254,6 +259,53 @@ Expect, in order: Report each step to the user as it happens. If any step is silent for more than a couple of minutes, check `first-tree breeze doctor`. +**6.4.b — Real source-PR trigger (optional, ~5 min).** This is what the +end-to-end pitch promises: a source-repo PR flows through breeze into a +draft-node PR on the tree repo, no manual gardener invocation. Only do +this once 6.4.a is green — it adds GitHub's notification latency on top +of everything else, so if 6.4.a is broken, this step will just look +silent. + +1. In the source repo checkout, open a trivial drift-inducing PR: + + ```bash + git -C checkout -b first-tree-smoke/drift-demo + echo "# drift demo $(date -u +%FT%TZ)" >> README.md + git -C commit -am "chore: first-tree drift-demo smoke" + git -C push -u origin first-tree-smoke/drift-demo + gh pr create --repo --fill --head first-tree-smoke/drift-demo + ``` + +2. Watch breeze pick it up: + + ```bash + first-tree breeze watch # live TUI: status board + activity feed + # or: first-tree breeze status # one-shot snapshot + ``` + + Expect a `source-pr:` entry within one GitHub polling cycle + (default 60 s; `first-tree breeze doctor` reports the live interval + and auth state if nothing shows up). + +3. Confirm gardener responded on the source PR: + + ```bash + gh pr view --repo --comments + ``` + + A gardener verdict comment should be present (or a + `first-tree:skipped` label if the classifier deemed the PR off-topic + — still a successful chain). + +4. Merge or close the smoke PR to clean up. If the PR was merged, a + draft-node PR will appear on the tree repo; reviewing it is Scenario + G in the gardener skill. + +Report each observed step. If breeze never picks up the PR, the two +common causes are (a) GitHub watch subscription missing on the source +repo (Step 6.2), or (b) the breeze allowlist did not include this +source repo — check `first-tree breeze status`. + ### Opting Modules Out (Rare) Gardener's `comment` and `respond` subcommands are **enabled by From ac9b834d5ae1519f533de166a84a630780636150 Mon Sep 17 00:00:00 2001 From: serenakeyitan Date: Thu, 23 Apr 2026 14:06:31 -0700 Subject: [PATCH 2/2] docs(onboarding): address yuezengwu review on #329 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three issues flagged, all real: 1. Mixed `git -C ` with a bare `echo >> README.md` that would hit cwd instead of the smoke repo. Rewrote the block to `cd ` once and keep every subsequent command plain. 2. Promised a literal `source-pr:` entry that the implementation does not emit. Breeze's real task-kind taxonomy (from src/products/breeze/engine/runtime/task-kind.ts) is `review_request` / `comment` / `mention` / `assigned_issue` / `assigned_pull_request` / `discussion` / `other`. Narrative now says "a row for the new PR shows up" and names the real taxonomy as informational. 3. Troubleshooting blamed "source-repo watch subscription missing" as the primary cause for silent pickup. Breeze polls `/notifications?participating=true`, and a PR author gets the notification via participation — not via repo watch. Rewrote the troubleshooting block to walk the real gates in order: (a) does `gh api /notifications` show it, (b) is the source repo in the breeze `--allow-repo` scope, (c) `breeze doctor` for runtime errors. --- skills/first-tree/references/onboarding.md | 39 ++++++++++++++++------ 1 file changed, 28 insertions(+), 11 deletions(-) diff --git a/skills/first-tree/references/onboarding.md b/skills/first-tree/references/onboarding.md index 973d356..3d928f4 100644 --- a/skills/first-tree/references/onboarding.md +++ b/skills/first-tree/references/onboarding.md @@ -266,13 +266,15 @@ this once 6.4.a is green — it adds GitHub's notification latency on top of everything else, so if 6.4.a is broken, this step will just look silent. -1. In the source repo checkout, open a trivial drift-inducing PR: +1. Run the whole block from inside the source-repo checkout so every + command hits the smoke repo, not your current cwd: ```bash - git -C checkout -b first-tree-smoke/drift-demo + cd + git checkout -b first-tree-smoke/drift-demo echo "# drift demo $(date -u +%FT%TZ)" >> README.md - git -C commit -am "chore: first-tree drift-demo smoke" - git -C push -u origin first-tree-smoke/drift-demo + git commit -am "chore: first-tree drift-demo smoke" + git push -u origin first-tree-smoke/drift-demo gh pr create --repo --fill --head first-tree-smoke/drift-demo ``` @@ -283,9 +285,13 @@ silent. # or: first-tree breeze status # one-shot snapshot ``` - Expect a `source-pr:` entry within one GitHub polling cycle - (default 60 s; `first-tree breeze doctor` reports the live interval - and auth state if nothing shows up). + Within one GitHub polling cycle (default 60 s), a new entry for the + smoke PR should appear. Breeze classifies it under its task-kind + taxonomy (`review_request`, `comment`, `mention`, `assigned_*`, etc.) + — which kind depends on how the PR notifies you (self-authored PRs + come in via the participation channel, not as a review request). + What matters is that a row for the new PR shows up; the exact kind + is informational. 3. Confirm gardener responded on the source PR: @@ -301,10 +307,21 @@ silent. draft-node PR will appear on the tree repo; reviewing it is Scenario G in the gardener skill. -Report each observed step. If breeze never picks up the PR, the two -common causes are (a) GitHub watch subscription missing on the source -repo (Step 6.2), or (b) the breeze allowlist did not include this -source repo — check `first-tree breeze status`. +If breeze never picks up the PR, walk the real gates in order: + +- **No source-PR notification at all.** `gh api /notifications` should + list the smoke PR. If it doesn't, the gh auth context isn't seeing it + — check `gh auth status` and confirm you're authed as the user who + opened the PR. Breeze polls `/notifications?participating=true`, so + the notification has to exist on the user's timeline for breeze to + see it. (Source-repo watch subscription is *not* the gate here: PR + authorship alone triggers participation.) +- **Notification exists, breeze shows nothing.** The source repo is + probably outside the breeze allowlist. `first-tree breeze status` + prints the active `--allow-repo` scope; re-run `breeze install + --allow-repo ,` if it's missing. +- **Breeze picked it up but no gardener action.** Check + `first-tree breeze doctor` for runtime + auth errors. ### Opting Modules Out (Rare)