# Create Diff

> Create a YugabyteDB Phorge diff for the current branch's changes. Use when the user wants to publish their changes for review.

- Skill: `yugabyte/create-diff` (Agent Skill)
- Install (CLI): `npx skillmds@latest add yugabyte/create-diff`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yugabyte/create-diff/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: yugabyte (https://skillmd.com/u/yugabyte)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yugabyte/create-diff

---


# Create Diff

Create a Phorge diff for the current branch using `arc diff --create`.


## Confidentiality -- read before you write anything

**Treat Phorge as public.** Two reasons: (1) Phorge revisions and the
Jenkins logs they trigger are visible to anyone with company access, not
just the reviewers you @-mention; (2) anything you put into the test
code, code comments, fixtures, or golden outputs on this diff lands on
the public GitHub repo verbatim when this work is later upstreamed via a
PR — there is no separate scrubbing pass at that boundary.  So apply the
public-repo rules now: diff title, summary, test plan, inline comments,
commit messages, code, tests, fixtures, golden output, and filenames all
get the same treatment as a public GitHub PR.

**Never put any of the following into the diff title, summary, test
plan, Phorge comments, commit messages, code comments, test code, test
fixtures, golden output, or filenames:**

- **Customer-identifying data** — company names, account IDs,
  universe/cluster names or UUIDs, support case numbers, environment
  names, region/zone names tied to a customer deployment.  Substitute
  with `customer-1`, `acme-corp`, or a generic description.
- **PII** — real names, real emails, real phone numbers, real postal
  addresses, real IP addresses (public or private).  In tests use only
  the documentation ranges: IPv4 `192.0.2.0/24` / `198.51.100.0/24` /
  `203.0.113.0/24` (RFC 5737), IPv6 `2001:db8::/32` (RFC 3849),
  hostnames `example.com` / `example.org` / `example.net` (RFC 2606),
  names `Alice`/`Bob`/`Carol`, phone numbers `555-0100`–`555-0199`.
- **Unanonymized customer schema or queries** — table names, column
  names, SQL text, query plans, or sample rows pulled from a real
  customer report.  Reconstruct a synthetic minimal reproducer with
  generic identifiers (`t1`, `users`, `id`, `value`) that demonstrates
  the same defect.
- **Secrets / credentials** — API keys, tokens, passwords, TLS
  certificates, private keys, license keys, kubeconfigs, production S3
  buckets, internal Slack/JIRA/Linear URLs (other than referencing them
  by ticket key like `PLAT-20518`), internal hostnames, vault paths.
  Use placeholders like `AKIAIOSFODNN7EXAMPLE` in mocks.
- **YugabyteDB-internal information not yet public** — unreleased
  roadmap, internal SLAs, embargoed security findings, internal infra
  hostnames.

applies to the test code and test data you write too** — `.cc`, `.py`,
  `.java`, `.sql`, golden `.out` files, YAML fixtures, mock responses.
  If a customer's reproducer uses `acme_orders` with a `customer_email`
  column populated with real addresses, rewrite it as `t1`/`email` with
  `user@example.com` before the test goes anywhere near a diff.

**When the source is a customer report:** read the original from the
internal source (JIRA / support ticket / Slack) — don't paste or link
it.  Reproduce locally with synthetic inputs.  Land only the synthetic
reproducer.  Reference the issue by internal ticket ID (`PLAT-20518`)
only.

**If you're unsure whether a string is sensitive, don't write it down --
ask the user.** See `src/AGENTS.md` section on Confidentiality for the
canonical list.

This rule applies at every step below: Step 1 (commit message), Steps
3-3.5 (issue body if auto-creating), Step 4 (title), and Step 6 (summary
/ test plan).


## Prerequisites

This skill requires `arc` (Arcanist) to be installed and configured for
the YugabyteDB Phorge instance.  If `arc` is not available, instruct the
user to set it up.


## Workflow

### Step 1: Commit pending changes

`arc diff --create` requires a clean working copy — any unstaged or
untracked changes on the branch must be committed first.

Run `git status`.  If there are uncommitted changes:

1. Stage the relevant files (avoid `git add -A`/`.` — pick files
   explicitly so secrets or stray artifacts don't get included).
2. Draft a commit message based on the changes and confirm it with the
   user before committing.
3. Create the commit.

If the branch already has at least one commit and the working copy is
clean, skip to Step 2.

### Step 2: Run linter and confirm no lint errors

Run `./build-support/lint.sh` from the repo root.  Report the output to
the user.

- If there are **errors**, stop and fix the issues before continuing.
  Do not proceed to `arc diff --create`.
- If there are only **warnings or advice**, show them to the user and
  ask whether to proceed.
- If the output is clean, continue to the next step.

### Step 2.5: PG code style pass (only when src/postgres files changed)

If the branch changes anything under `src/postgres`, load the
`pg-code-style-guide` skill and check the diff against it (yb prefixes,
YB marker blocks, upstream lines untouched, regress test rules).  Fix
violations now -- this is the last point where cleanup is free; after
publishing they come back as review comments.

Commit any resulting fixes on the branch -- amend Step 1's commit or add
a new one -- before Step 6, and re-run the linter (Step 2).

### Step 3: Determine tracker reference

You will need a GitHub or JIRA issue describing the issue this diff is
fixing in order to create the diff.  Normally there is a one-to-one
relationship between tracking issues and diffs.

First, check which area the changes touch:
  - If changes are in core DB code (`src/`, `java/`, `cmake_modules/`,
    `build-support/`), remind the user that most core DB changes should
    have a GitHub issue.
  - If changes are in YBA/platform code (`managed/`), remind the user
    that most platform changes should have a JIRA ticket.

Second, scan the current conversation history for any issue reference
the user has already mentioned (i.e., GitHub issue numbers like
`#31151`, JIRA keys like `PLAT-20518`, or URLs pointing at either).  If
you find a candidate, surface it to the user and ask them to confirm
it's the one to use *before* asking them to supply a fresh one.  Only
prompt for a new reference if no candidate is found or the user rejects
the candidate.

When asking the user for a tracking reference, acceptable forms are:
   - A GitHub issue number (e.g., `#31151`)
   - A JIRA ticket (e.g., `PLAT-20518`)
Offer to **auto-create** a GitHub issue or JIRA ticket if the user
doesn't have one yet. If they accept, invoke the **`/create-issue`**
skill to file it (GitHub issue for core DB code, JIRA ticket for
`managed/` platform work), then capture the issue number / JIRA key it
reports back. Since the issue tracks this diff's work, tell
`/create-issue` to assign it to the invoker (`@me`) rather than leaving
it unassigned.

### Step 3.5: Gather remaining title metadata

Prompt the user for the following, one at a time:

1. **Component** — the component tag that will appear in the title
   (e.g., `DocDB`, `YSQL`, `YBA`, `CDC`, `xCluster`).  If the user is
   unsure, suggest a component based on the files changed (e.g.,
   `src/yb/` → `DocDB`, `src/postgres/` → `YSQL`, `managed/` → `YBA`).

2. **Title** — a short description of the change.  If the user doesn't
   provide one, propose a title, possibly based on the commit messages
   on the branch if they are informative, and confirm it with the user.

### Step 4: Build the title

Construct the title in the format:

```
[<#GH issue> or <JIRA>] <Component>: <Title>
```

Examples:
- `[#31151] DocDB: Fix SamplingProfilerTest.EstimatedBytesAndCount in release`
- `[PLAT-20518] YBA: Fix full move edit universe to populate userIntentOverrides during configure call`

### Step 5: Determine subscribers

Based on the files changed on the branch, decide the default subscriber:

- If changes are in DB code (`src/`, `java/`, `cmake_modules/`,
  `build-support/`, etc.) → add `ybase` as a subscriber.
- If changes are in YBA / platform code (`managed/`) → add `yugaware` as
  a subscriber.
- If changes span both, add both `ybase` and `yugaware`.

Confirm the subscriber list with the user before creating the diff.

### Step 5.5: Cut the prose the branch added

Re-read the **text** the branch adds — comments, `architecture/` docs,
agent docs — and apply [`AGENTS.md` Prose
discipline](../../../AGENTS.md#prose-discipline--write-for-the-reader-not-for-volume).
It is a gate here because it is easy to hold at the start of a task and
gone by the end of one, and this is the last point where cutting is
free.

```
git diff <base>...HEAD -- '*.md'   # doc prose; also skim added comments in the code diff
```

Commit any resulting edits on the branch before Step 6, and re-run the
linter (Step 2).

### Step 6: Create the diff with `arc diff --create`

**Confidentiality — final scrub before publishing.** Phorge is treated
as public (company-wide visible + test code lands on the public GitHub
repo verbatim when upstreamed).  Before composing the message file,
re-read the summary, test plan, commit messages, **and the test code
being added**, and confirm none of the following appear: customer names
or identifiers (universe UUIDs, account IDs, support cases, environment
names, region/zone names); PII (real names / emails / phone numbers /
postal addresses / IP addresses — use RFC 5737/3849 documentation ranges
in tests); unanonymized customer schemas (table / column / query text /
query plans / sample rows from a real customer — reconstruct a synthetic
reproducer); credentials, tokens, certificates, private keys, or license
keys; internal-only hostnames, URLs, Grafana/Slack/Linear links, or
vault paths; unreleased internal information (roadmap, SLAs, embargoed
security findings, internal infra hostnames).  See the top of this skill
and `src/AGENTS.md` Confidentiality for the full rule.  If unsure
whether a string is sensitive, don't write it down — ask the user.

Run `arc diff --create` **without** using the Phorge MCP server.  Do
**not** amend the user's existing commit to change its title — always
pass the Phorge revision title and body via `--message-file` so the
local commit stays untouched.

A typical invocation:

```
arc diff --create --message-file <path> --reviewers <reviewers> --cc <subscribers> <base>
```

Pre-fill the message file with:

- **Title**: the constructed title from step 4
- **Summary**: derived from the branch commits.  Say **why**, always —
  a reviewer who has to reverse-engineer the motivation is the
  expensive case — then what changed, and whatever the reader must *act*
  on (new gflags, upgrade/rollback consequences, migration steps).  Not
  a narration of the diff.  See [`AGENTS.md` Prose
  discipline](../../../AGENTS.md#prose-discipline--write-for-the-reader-not-for-volume).
- **Test Plan**: ask the user for one if not obvious from the branch.
  Keep it to what was actually run — it is not a place for prose.
- **Reviewers**: (as provided)
- **Subscribers**: `ybase` and/or `yugaware` per Step 4

If tests were added or considered important to verify the change works,
add the commands for running those tests to the test plan.

Show the user the resulting diff URL (e.g., `https://phorge.dev.yugabyte.com/D<id>`).

### Step 7: Post a "trigger jenkins" comment

After the diff is created, post a comment on the new revision with the
exact text:
```
trigger Jenkins
```

Use `arc` to post the comment (do not use the Phorge MCP server).  For
example:
```
echo "trigger jenkins" | arc call-conduit differential.createcomment -- '{"revision_id": "<id>", "message": "trigger jenkins"}'
```

Or use whatever `arc` subcommand is appropriate for the local setup.
Confirm the comment was posted successfully.

### Step 8: Report back to the user

Output:

- The diff URL
- The constructed title
- The subscribers that were added
- Confirmation that `trigger Jenkins` was posted


## Notes

- Never use the Phorge MCP server for creating the diff — use `arc` CLI
  only.
- Always run `./build-support/lint.sh` first; a failing lint should
  block diff creation.
- The title format is strict: `[<issue>] <Component>: <Title>`.  Don't
  deviate.
- `ybase` for DB, `yugaware` for YBA/platform — add both when changes
  span both.
- The `trigger jenkins` comment kicks off continuous integration
  testing; forgetting it is a common mistake.