Create PR

create-pr

Purpose

Opening a PR on this repo is mechanically simple (gh pr create) but four things consistently go wrong if rushed:

1. The branch name doesn't describe the change. Codenames like agate-surgeon, throwaways like wip, or repurposed branches like fix-bug survive into the merged history and make git log --graph useless. The branch name is the only summary that shows up in every future git log line for these commits — get it right before publishing.
2. docs-site/ rots silently. This repo ships its own user-facing docs (docs-site/content/docs/{en,zh}/). Code changes that touch user-visible behavior — CLI flags, settings, timeouts, file formats, error messages, supported environments — almost always have a paragraph somewhere in docs-site/ that now lies. The PR author is the only person with the context to spot it; reviewers will miss it.
3. New user-facing flows ship without telemetry. This repo has a structured PostHog event model (crates/uc-observability/src/analytics/, schema doc docs/architecture/telemetry-events.md). When a PR adds or changes an activation/reliability flow — pairing, sync, setup, update, mobile-sync — but doesn't capture(Event::...) the new milestone or failure path, the funnel silently goes blind. The author is the only one who knows the flow is new.
4. Tracing drifts from the spec. The repo has a strict layered tracing spec (docs/guides/tracing.md): only the use-case layer owns spans, domain stays span-free, fields must be low-cardinality and privacy-safe, and log levels have defined meanings. New code routinely forgets a use-case span, logs at the wrong level, or leaks high-cardinality / clipboard data into a field.

This skill enforces all four checks before pushing, so the PR that lands on GitHub is already named correctly, has its docs/telemetry/tracing gaps either addressed or explicitly deferred with the user's sign-off.

When to trigger

Trigger on any of:

• "create PR", "open PR", "make a PR", "raise a PR"
• "提 PR", "开 PR", "打 PR", "建 PR"
• User pastes / mentions an issue URL and says something like "PR it" or "close that with a PR"

Do not trigger on "commit" / "push" alone — those are pre-PR steps that the user is doing manually.

Refuse / pause conditions

Workflow

Step 1 — Take stock (run in parallel)

git status                                       # working tree state (never -uall)
git rev-parse --abbrev-ref HEAD                  # current branch
git log main..HEAD --format="%h %s"              # commits this PR will include
git diff main...HEAD --stat                      # files touched
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>&1 || echo NO_UPSTREAM
gh auth status 2>&1 | head -5                    # auth sanity

Also scan the recent conversation for:

• An issue number or URL the user wants this PR to close (e.g. #652, https://github.com/.../issues/652). If present, fetch it once so the Summary can reference it accurately:

  gh issue view <N> --repo UniClipboard/UniClipboard --json number,title,body,state

• Any user statement that this PR is partial / draft / WIP — that changes the PR body wording and may want gh pr create --draft.

Apply the refuse-conditions in the table above before going further.

Step 2 — Branch-name review

Evaluate the current branch name against the commits in git log main..HEAD. A good name:

• Is kebab-case (matches the existing style in git branch -a).
• Reflects the scope of the change, not its codename or a ticket id alone. Read the commit subjects and ask: would a teammate skimming git log --oneline main.. understand what this branch was for from the name?
• Is short (≤ 40 chars is a soft target).

If the name passes, say so in one line and move on. If it doesn't:

1. Propose one new name derived from the commit subjects. Don't dump three options — pick the best one and let the user counter.

2. Show: current name → proposed name, with a one-sentence justification ("the commits are all about X; current name is a codename that doesn't say that").

3. Ask the user: accept, counter-propose, or skip.

4. On accept:

   git branch -m <new>                            # rename locally
   # If the old name was already pushed:
   git push origin -u <new>                       # push under the new name
   git push origin --delete <old>                 # remove the old remote branch

   If the old branch already has an open PR pointing at it, stop and tell the user — renaming will orphan that PR. Don't try to rewire it silently.

Step 3 — docs-site impact review (the part that's easy to skip)

The repo's user docs live in docs-site/content/docs/{en,zh}/. Skim the PR diff and identify any change whose user-visible contract may now disagree with the docs. The categories below are the high-yield ones — search the diff for these before declaring no impact.

For each candidate hit, produce a one-line entry:

- <docs file>:<line> — current text says "<short quote>"; this PR changes <X> so it should say "<short suggested replacement>". (Reason: <which commit / which line in the code>.)

Always show the candidate list to the user before editing anything. Even if the list is empty, say so explicitly ("Scanned docs-site; found nothing that depends on this PR's surface area"). Then ask:

• Apply all? Apply some (which)? Apply none?
• If the answer is "apply none", record the explicit decision so the PR body can mention "docs left as-is — no user-facing surface changed" (rather than silently omitting it, which leaves reviewers guessing).

On approval, edit the listed files, then commit them as a separate commit:

docs(docs-site): <one-line summary that matches the code change>

Don't fold docs edits into a fix/feat commit by amending — keep them as their own commit in the PR. (Amending also breaks the rule about not modifying already-pushed commits.)

Both en/ and zh/ versions must be updated in lockstep when both exist — never ship a PR that updates only one language.

Step 4 — PostHog telemetry gap review

Gate first — skip cheaply. Telemetry is only ever emitted from the use-case layer via self.analytics.capture(Event::...); uc-core and infra never emit. So run this before reading anything:

git diff main...HEAD --name-only | grep -qE '^crates/uc-application/|mobile.sync' || echo SKIP_TELEMETRY

If it prints SKIP_TELEMETRY, state one line ("diff doesn't touch uc-application / mobile-sync — no telemetry surface") and go to Step 5. Do not read the spec docs for an unrelated diff.

If the gate passes, the source of truth (not your memory) is:

• Event catalog — crates/uc-observability/src/analytics/events.rs (the Event enum + its enumerable property types). The closed set of events that already exist.
• Schema doc — docs/architecture/telemetry-events.md: §7 v1 event list, §12 roadmap of planned-but-not-yet-emitted events, §6 privacy contract.

You don't need to read these end-to-end. Scan the diff for the key positions below; only when you're about to suggest a specific Event::Variant do you rg '<Variant>' crates/uc-observability/src/analytics/events.rs to confirm it exists (or check §12 if it's planned).

Scan the diff for key positions where a milestone or failure outcome now happens but no capture(...) accompanies it:

For each candidate, emit a one-line entry:

- <code file>:<line> — <flow> reaches <milestone/outcome> but emits no event. Suggest capture(Event::<Variant>{...}) (or: already specced in telemetry-events.md §<n>). Confidence: <high/low>.

Privacy & double-count red lines (from schema doc §6 and the existing call sites) — call these out if the diff violates them, they are bugs not suggestions:

• Never put clipboard content, raw file names, full settings, or raw sizes into a property. Sizes go through PayloadSizeBucket; latency-sensitive durations (e.g. sync_latency_ms) report a precise u32 while coarse durations use LatencyBucket; everything must stay low-cardinality.
• Inbound-sync paths that write the local clipboard (e.g. a RemotePush origin) must not emit capture/DAU events — that double-counts. See the red-line comment around clipboard_capture/usecase.rs.
• Event names and property values are frozen once shipped — never rename an existing variant; evolve with a *_v2.

Always show the candidate list to the user before adding any instrumentation. If the diff has no telemetry-worthy surface, say so explicitly ("Scanned the uc-application diff; no new activation/reliability milestone, nothing to instrument"). Then ask: add now, or defer (and note it in the PR body)? Telemetry is normal code — if added, it belongs in the relevant feat/fix commit, not the docs commit.