ToolJet Pull Request Creator

Create a pull request for the current branch. Pushes, creates submodule PRs if needed, and creates the main PR.

User input: $ARGUMENTS

Parse the input as follows:

• If empty: auto-detect the base branch (see detection logic below).
• Otherwise: use the entire input as the base branch name.

Requires the gh CLI, authenticated against both ToolJet and the submodule repos.

Shell environment notes

IMPORTANT: The Bash tool executes in zsh via eval. for loops cause git: command not found — never use loops. Use inline per-repo commands instead.

Phase 1 — Analysis

Step 1: Branch and base detection

Pick the base from what's known, in this order (the user input was: $ARGUMENTS):

1. The user input, if given.
2. An existing PR for this branch: keep its base (gh pr view --json baseRefName).
3. A stack: the branch below it (gh stack view), or a base the user named earlier in the conversation.
4. Otherwise the remote's default branch (main). Ask the remote, because a local origin/HEAD goes stale:

git ls-remote --symref origin HEAD | awk '/^ref:/ {sub("refs/heads/","",$2); print $2}'

If these disagree, or the work clearly belongs on a release line (e.g. an lts-* backport), ask the user instead of guessing.

Step 2: Gather commits and diff

Run in a single Bash call:

ROOT=$(git rev-parse --show-toplevel)
BRANCH=$(git -C "$ROOT" rev-parse --abbrev-ref HEAD)
BASE="<detected base>"
echo "=== COMMITS ==="
git -C "$ROOT" log --oneline --no-merges "origin/${BASE}..HEAD"
echo "=== DIFF STAT ==="
git -C "$ROOT" diff --stat "origin/${BASE}..HEAD"
echo "=== SUBMODULE CHANGES ==="
git -C "$ROOT" diff "origin/${BASE}..HEAD" -- server/ee frontend/ee
echo "=== CROSS-REPO STATUS ==="
git -C "$ROOT" status --short
git -C "$ROOT/server/ee" status --short
git -C "$ROOT/frontend/ee" status --short

If there are no commits ahead of the base branch, say "No commits ahead of <base> — nothing to create." and stop.

If you need deeper understanding of specific changes, read key modified files with git diff origin/<base>..HEAD -- <path>.

Step 3: Check submodules

For each submodule that has pointer changes, check its branch and recent commits:

echo "BRANCH=$(git -C "$ROOT/server/ee" rev-parse --abbrev-ref HEAD 2>/dev/null)"
git -C "$ROOT/server/ee" log --oneline -5 2>/dev/null
echo "BRANCH=$(git -C "$ROOT/frontend/ee" rev-parse --abbrev-ref HEAD 2>/dev/null)"
git -C "$ROOT/frontend/ee" log --oneline -5 2>/dev/null

A submodule sitting on a detached HEAD has no branch to open a PR from — note it and skip its PR.

Step 4: Check for existing PRs

Run in a single Bash call:

BRANCH=$(git -C "$ROOT" rev-parse --abbrev-ref HEAD)
echo "=== MAIN REPO ==="
gh pr list --repo ToolJet/ToolJet --head "$BRANCH" --json url,title,state,number 2>/dev/null
echo "=== SERVER_EE ==="
gh pr list --repo ToolJet/ee-server --head "$BRANCH" --json url,title,state,number 2>/dev/null
echo "=== FRONTEND_EE ==="
gh pr list --repo ToolJet/ee-frontend --head "$BRANCH" --json url,title,state,number 2>/dev/null

Step 5: Generate PR content

Analyze the commits and diff to determine:

PR Title — format rules:

• Title case prefix: Feature:, Fix:, Chore:, Refactor:, Docs:, Test:, Perf:, CI:
• Rest in running case (normal sentence case)
• Under 72 chars total
• Branch name hints: feature/ → Feature, fix/ → Fix, chore/ → Chore, etc.

Writing style — CRITICAL rules for PR descriptions:

• Write like you're explaining to a teammate, not documenting for a spec
• "What this does" = the elevator pitch (1-2 sentences, high-level why)
• "Changes" = concrete what changed (no overlap with the summary above)
• No file paths, function names, or class names unless they ARE the change
• No per-line prefixes (fix:/feat: etc.) — the PR title already has the category
• Keep change bullets short, one line each, past tense, max 5. Combine related items if needed
• Break up anything verbose. A paragraph running past 2-3 lines, or a bullet carrying more than one idea, gets split into separate lines or sub-bullets — one idea per line. Reviewers skim; a wall of text hides the change instead of explaining it. If a section still reads long after splitting, it is saying too much — cut it, don't reformat it
• Test steps: action-first, short. "Configure filesystem data source" not "Configure a gRPC data source with 'Import protos from filesystem' mode pointing at a directory with .proto files"
• Only include evidence that was actually produced: never add an empty or placeholder section
• Separate block elements (paragraphs, labelled lines, lists, code) with a blank line. GitHub joins consecutive lines into one paragraph, so two labelled lines with no blank line between them render as one.
• Don't use GitHub alert boxes (> [!TIP] and similar) for routine notes. Their built-in label ("Tip", "Note") reads as noise under a section heading.

Merge impact: always state it, as a folded <details> block at the end of Changes. It tells the reviewer how hard to look.

• The summary line is the only place the verdict appears, so it reads without expanding:
  • 🟢 reversible when a plain revert undoes the PR;
  • 🔴 not reversible for a migration that drops or rewrites data, a public API or contract change, a release or external side effect, or a deletion.
• Irreversible changes use <details open>, so the risk is never folded away.
• Leave a blank line after </summary> and before </details>, or GitHub won't render the bullets.
• Can't undo: irreversible changes only. What a revert leaves behind.
• Rollback: irreversible changes only. The plan for recovering.
• Reach: what the change can affect: editions (CE/EE/Cloud), tenants, modules, consumers of a contract, existing saved apps.
• Not included: optional. Deliberate omissions or surprising decisions, so they aren't buried in the Changes bullets.

Sources: a 📎 **Sources:** label under the summary, then one bullet per item. Include only items with content, and drop the block when there are none:

• Issue:
  • Closes #123 when the PR fully resolves the issue, Relates to #123 when it only partly does.
  • Issues in the private tracker (e.g. from kickoff) need the full reference, ToolJet/tj-ee#123. Use the reference only, never the issue title or body, in a public PR.
• PRD and design: PRD: [title](url) and Design: [title](url), when those links (ClickUp, Figma, a GitHub spec issue) are in the conversation.
• Sub-issues: Sub-issues: #124, #125. Use numbers only, because GitHub renders the titles.
  • With multiple parents, use one bullet each: Sub-issues (#123): #124, #125.
  • Wrap the list in <details> when there are more than about 6.

Submodules: a **Submodules:** label followed by one bullet per submodule PR: - [ee-server #123](url). Leave out a submodule with no changes, and the whole block when neither changed.

Conditional sections: include only when they apply.

• Architecture: when the change has a shape worth seeing (new entities, permission models, flows, a refactor across files). Use the smallest view that makes the point, placed next to the sentence it supports:

  • Mermaid for anything with steps or order: interactions, flows, lifecycles and entity models (sequenceDiagram, flowchart, erDiagram);
  • an ASCII call tree, component tree or shallow file tree, only for a real hierarchy. Nodes are bare names, with a file path at most and no notes;
  • a diff over the table, entity or type when the data shape changes;
  • pseudocode for business logic.

  Pick one or two, not all. Skip it for small fixes, config or copy changes. A note longer than a few words goes inside a Mermaid node or in the prose, not after an arrow in an ASCII block: packed annotations make the block hard to read.

• API Reference: when HTTP endpoints are added or changed. A table with Method, Route, Permission, Request and Response columns.

• Evidence: when runtime behaviour changes. Show proof it works, as before → after:

  • a screenshot for visual changes (capture it with Playwright MCP when a dev server is running);
  • otherwise the failing → passing test, or command output;
  • for kickoff slices, link the verifier's report comment.

  Skip it for docs, tooling, config or CI-only changes.

• How to test: when there is runtime behaviour a reviewer can exercise. Skip it for docs, tooling, config or CI-only changes.

Main PR body: use this template exactly as written, including the emoji prefixes. Every line and section after the summary is conditional; omit any that doesn't apply.

## 📝 What this does
<1-2 sentence elevator pitch — what changed and why it matters>

📎 **Sources:**
- Closes <#issue>
- PRD: [title](url)
- Design: [title](url)
- Sub-issues: <#num, #num>

**Submodules:**
- [ee-server #<n>](<url>)
- [ee-frontend #<n>](<url>)

## 🔀 Changes
- <what changed, past tense, no prefixes, max 5 bullets>

<details>
<summary>🛡️ <b>Merge impact:</b> <🟢 reversible | 🔴 not reversible></summary>

- **Can't undo:** <irreversible only: what a revert leaves behind>
- **Rollback:** <irreversible only: plan>
- **Reach:** <scope>
- **Not included:** <optional: deliberate omissions or surprising decisions>

</details>

## 🏗️ Architecture
<smallest view that fits: mermaid / ASCII tree / diff sketch / pseudocode>

## 🔌 API Reference
| Method | Route | Permission | Request | Response |
|--------|-------|------------|---------|----------|
| **POST** | `/api/...` | `PERM` | `{ body }` | `{ response }` |

## 🧾 Evidence
- **Before:** <screenshot / output / failing test>
- **After:** <screenshot / output / passing test>

## 🧪 How to test
- [ ] <short action-first step>

Omit the Sources and Submodules blocks, or any bullet in them, when there's no content.

The section order follows the questions a reviewer asks: why, how risky, what changed, how it fits, does it work, how do I try it. The Evidence and Merge impact ideas and the "smallest view that fits" visuals are adapted from Matt Pocock's pr skill and HumanLayer's show-me and visual-pr skills by Dex Horthy (both MIT).

Submodule PR body (for each submodule with changes) — simplified template, NO test plan, NO Submodules, NO Screenshots. Use headings EXACTLY as shown, including emoji prefixes:

## 📝 What this does
<1-2 sentence summary>

**Main PR:**
- [ToolJet #<n>](<main repo PR url or PENDING>)

## 🔀 Changes
- <what changed, past tense, no prefixes>