From 103eea252c22428724189a45e1d2227b98c64b0a Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 12:51:37 +0800 Subject: [PATCH 01/23] Add initial skill version --- .github/skills/create-pull-request/SKILL.md | 196 ++++++++++++++++++++ 1 file changed, 196 insertions(+) create mode 100644 .github/skills/create-pull-request/SKILL.md diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md new file mode 100644 index 0000000000..5e488ca36b --- /dev/null +++ b/.github/skills/create-pull-request/SKILL.md @@ -0,0 +1,196 @@ +--- +name: create-pull-request +description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. +--- + +# Create Pull Request + +This skill guides you through creating a well-structured GitHub pull request that follows project conventions and best practices. + +## Prerequisites Check + +Before proceeding, verify the following: + +### 1. Check if `gh` CLI is installed + +```bash +gh --version +``` + +If not installed, inform the user: +> The GitHub CLI (`gh`) is required but not installed. Please install it: +> - macOS: `brew install gh` +> - Other: https://cli.github.com/ + +### 2. Check if authenticated with GitHub + +```bash +gh auth status +``` + +If not authenticated, guide the user to run `gh auth login`. + +### 3. Verify clean working directory + +```bash +git status +``` + +If there are uncommitted changes, ask the user whether to: +- Commit them as part of this PR +- Stash them temporarily +- Discard them (with caution) + +## Gather Context + +### 1. Identify the current branch + +```bash +git branch --show-current +``` + +Ensure you're not on `main` or `master`. If so, ask the user to create or switch to a feature branch. + +### 2. Find the base branch + +```bash +git remote show origin | grep "HEAD branch" +``` + +This is typically `main` or `master`. + +### 3. Analyze recent commits relevant to this PR + +```bash +git log origin/main..HEAD --oneline --no-decorate +``` + +Review these commits to understand: +- What changes are being introduced +- The scope of the PR (single feature/fix or multiple changes) +- Whether commits should be squashed or reorganized + +### 4. Review the diff + +```bash +git diff origin/main..HEAD --stat +``` + +This shows which files changed and helps identify the type of change. + +## Information Gathering + +Before creating the PR, you need the following information. Check if it can be inferred from: +- Commit messages +- Branch name (e.g., `fix/issue-123`, `feature/new-login`) +- Changed files and their content + +If any critical information is missing, use `ask_followup_question` to ask the user: + +### Required Information + +1. **Related Issue Number**: Look for patterns like `#123`, `fixes #123`, or `closes #123` in commit messages +2. **Description**: What problem does this solve? Why were these changes made? +3. **Type of Change**: Bug fix, new feature, breaking change, refactor, cosmetic, documentation, or workflow +4. **Test Procedure**: How was this tested? What could break? + +### Example clarifying question + +If the issue number is not found: +> I couldn't find a related issue number in the commit messages or branch name. What GitHub issue does this PR address? (Enter the issue number, e.g., "123" or "N/A" for small fixes) + +## Git Best Practices + +Before creating the PR, consider these best practices: + +### Commit Hygiene + +1. **Atomic commits**: Each commit should represent a single logical change +2. **Clear commit messages**: Follow conventional commit format when possible +3. **No merge commits**: Prefer rebasing over merging to keep history clean + +### Branch Management + +1. **Rebase on latest main** (if needed): + ```bash + git fetch origin + git rebase origin/main + ``` + +2. **Squash if appropriate**: If there are many small "WIP" commits, consider interactive rebase: + ```bash + git rebase -i origin/main + ``` + Only suggest this if commits appear messy and the user is comfortable with rebasing. + +### Push Changes + +Ensure all commits are pushed: +```bash +git push origin HEAD +``` + +If the branch was rebased, you may need: +```bash +git push origin HEAD --force-with-lease +``` + +## Create the Pull Request + +**IMPORTANT**: Read and use the PR template at `.github/pull_request_template.md`. The PR body format must **strictly match** the template structure. Do not deviate from the template format. + +When filling out the template: +- Replace `#XXXX` with the actual issue number, or keep as `#XXXX` if no issue exists (for small fixes) +- Fill in all sections with relevant information gathered from commits and context +- Mark the appropriate "Type of Change" checkbox(es) +- Complete the "Pre-flight Checklist" items that apply + +### Create PR with gh CLI + +```bash +gh pr create --title "PR_TITLE" --body "PR_BODY" --base main +``` + +Alternatively, create as draft if the user wants review before marking ready: +```bash +gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft +``` + +## Post-Creation + +After creating the PR: + +1. **Display the PR URL** so the user can review it +2. **Remind about CI checks**: Tests and linting will run automatically +3. **Suggest next steps**: + - Add reviewers if needed: `gh pr edit --add-reviewer USERNAME` + - Add labels if needed: `gh pr edit --add-label "bug"` + +## Error Handling + +### Common Issues + +1. **No commits ahead of main**: The branch has no changes to submit + - Ask if the user meant to work on a different branch + +2. **Branch not pushed**: Remote doesn't have the branch + - Push the branch first: `git push -u origin HEAD` + +3. **PR already exists**: A PR for this branch already exists + - Show the existing PR: `gh pr view` + - Ask if they want to update it instead + +4. **Merge conflicts**: Branch conflicts with base + - Guide user through resolving conflicts or rebasing + +## Summary Checklist + +Before finalizing, ensure: +- [ ] `gh` CLI is installed and authenticated +- [ ] Working directory is clean +- [ ] All commits are pushed +- [ ] Branch is up-to-date with base branch +- [ ] Related issue number is identified, or placeholder is used +- [ ] PR description follows the template exactly +- [ ] Appropriate type of change is selected +- [ ] Pre-flight checklist items are addressed \ No newline at end of file From 3b024d4ef3dc8a45892230a48729359bf7a368de Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 13:01:24 +0800 Subject: [PATCH 02/23] Edit skill for upstream PR specifically --- .github/skills/create-pull-request/SKILL.md | 34 +++++++++++++-------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 5e488ca36b..e2c90b2a20 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -3,7 +3,7 @@ name: create-pull-request description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. --- -# Create Pull Request +# Create Pull Request (Fork-to-Upstream Version) This skill guides you through creating a well-structured GitHub pull request that follows project conventions and best practices. @@ -51,18 +51,28 @@ git branch --show-current Ensure you're not on `main` or `master`. If so, ask the user to create or switch to a feature branch. -### 2. Find the base branch +### 2. Identify the Upstream Remote ```bash -git remote show origin | grep "HEAD branch" +git remote -v ``` -This is typically `main` or `master`. +If 'upstream' is missing, instruct the user to add it: git remote add upstream `https://github.com/ORIGINAL_OWNER/REPO_NAME.git` -### 3. Analyze recent commits relevant to this PR +### 3. Find the base branch on Upstream ```bash -git log origin/main..HEAD --oneline --no-decorate +# First, get the actual owner/repo string for the upstream remote +UPSTREAM_REPO=$(git remote get-url upstream | sed 's/.*github.com[\/:]//;s/\.git$//') + +# Then use that string to get the default branch +gh repo view "$UPSTREAM_REPO" --json defaultBranchRef -q .defaultBranchRef.name +``` + +### 4. Analyze recent commits relevant to this PR from the Upstream + +```bash +git log upstream/main..HEAD --oneline --no-decorate ``` Review these commits to understand: @@ -70,10 +80,10 @@ Review these commits to understand: - The scope of the PR (single feature/fix or multiple changes) - Whether commits should be squashed or reorganized -### 4. Review the diff +### 5. Review the diff ```bash -git diff origin/main..HEAD --stat +git diff upstream/main..HEAD --stat ``` This shows which files changed and helps identify the type of change. @@ -113,8 +123,8 @@ Before creating the PR, consider these best practices: 1. **Rebase on latest main** (if needed): ```bash - git fetch origin - git rebase origin/main + git fetch upstream + git rebase upstream/main ``` 2. **Squash if appropriate**: If there are many small "WIP" commits, consider interactive rebase: @@ -137,7 +147,7 @@ git push origin HEAD --force-with-lease ## Create the Pull Request -**IMPORTANT**: Read and use the PR template at `.github/pull_request_template.md`. The PR body format must **strictly match** the template structure. Do not deviate from the template format. +**IMPORTANT**: Read and use the PR template at `.github/PULL_REQUEST_TEMPLATE`. The PR body format must **strictly match** the template structure. Do not deviate from the template format. When filling out the template: - Replace `#XXXX` with the actual issue number, or keep as `#XXXX` if no issue exists (for small fixes) @@ -148,7 +158,7 @@ When filling out the template: ### Create PR with gh CLI ```bash -gh pr create --title "PR_TITLE" --body "PR_BODY" --base main +gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" ``` Alternatively, create as draft if the user wants review before marking ready: From 6b5fd9a7661d9d6ed435ee54481ceca356703738 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 13:07:12 +0800 Subject: [PATCH 03/23] Add credit to original author & modifications made --- .github/skills/create-pull-request/SKILL.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index e2c90b2a20..c2001836fc 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -1,6 +1,9 @@ --- name: create-pull-request description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. +Credit: This skill was adapted from the original `create-pull-request` skill developed by the **[Cline](https://github.com/cline/cline)** team. +- **Original Source**: [cline/cline/.cline/skills/create-pull-request](https://github.com/cline/cline/blob/main/.cline/skills/create-pull-request/SKILL.md) +Modification: Modified to support **Fork-to-Upstream** workflows and automated upstream remote detection. --- # Create Pull Request (Fork-to-Upstream Version) From a2d386eb43410f89e60d1468d06ddf3fa9e67932 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 15:23:31 +0800 Subject: [PATCH 04/23] Improve specificity of PR drafting --- .github/skills/create-pull-request/SKILL.md | 37 +++++++++++++++------ 1 file changed, 26 insertions(+), 11 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index c2001836fc..3039ccdf33 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -130,12 +130,6 @@ Before creating the PR, consider these best practices: git rebase upstream/main ``` -2. **Squash if appropriate**: If there are many small "WIP" commits, consider interactive rebase: - ```bash - git rebase -i origin/main - ``` - Only suggest this if commits appear messy and the user is comfortable with rebasing. - ### Push Changes Ensure all commits are pushed: @@ -150,13 +144,34 @@ git push origin HEAD --force-with-lease ## Create the Pull Request -**IMPORTANT**: Read and use the PR template at `.github/PULL_REQUEST_TEMPLATE`. The PR body format must **strictly match** the template structure. Do not deviate from the template format. +**IMPORTANT**: Read and use the PR template at `.github/PULL_REQUEST_TEMPLATE`. The PR body format must **strictly match** the template structure. Do not deviate from the template format. + +- Notify the user if the PR template missing before asking if they would like to proceed. When filling out the template: -- Replace `#XXXX` with the actual issue number, or keep as `#XXXX` if no issue exists (for small fixes) -- Fill in all sections with relevant information gathered from commits and context -- Mark the appropriate "Type of Change" checkbox(es) -- Complete the "Pre-flight Checklist" items that apply +1. **Purpose Checklist**: Based on the file changes detected (e.g., `.md` for Documentation, `test/` for Features), check the relevant boxes under **"What is the purpose of this pull request?"**. If it doesn't fit the main categories, use the "Others" box and provide a 1-sentence explanation. + - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. + +2. **Overview of changes**: Provide a high-level, 1-2 sentence summary of what this PR achieves. + +3. **Highlight/Discuss**: Elaborate on the technical implementation. Explain *how* you changed the code or documentation and point out any specific logic or layout choices you want the reviewer to notice. + +4. **Testing instructions**: Identify any manual testing steps. + - *Example: "Run `markbind serve`, navigate to /docs/plugin, and verify the new warning component renders correctly."* + - If no special steps are needed beyond automated tests, leave this blank or state "No special instructions." + +5. **Proposed commit message**: Generate a high-quality commit message: + - **Title**: Maximum 50 characters. + - **Body**: Wrap lines at 72 characters. + - Follow the [SE-Education standards](https://se-education.org/guides/conventions/git.html) referenced in the template. + +6. **Checklist**: Analyze the changes to check the appropriate boxes: + - Check "Updated documentation" if `.md` files in the docs folder were modified. + - Check "Added tests" if files in `test` or `spec` files were add or modified. + - Check "Linked all related issues" if you identified an issue number. + - Check "No unrelated changes" after verifying the diff doesn't contain stray edits. + +7. **Reviewer Section**: Leave the **Reviewer checklist** and **SEMVER** sections **unchecked** and unmodified. These are for the maintainers to fill out during review. ### Create PR with gh CLI From 99a92cd3ff5dbe806341293e9012cffa1cb83ed2 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 15:34:04 +0800 Subject: [PATCH 05/23] Add note to specify that PR was generated using skill --- .github/skills/create-pull-request/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 3039ccdf33..c2ec558cf1 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -153,6 +153,7 @@ When filling out the template: - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. 2. **Overview of changes**: Provide a high-level, 1-2 sentence summary of what this PR achieves. + - **Mandatory Note**: Append this exact line to the end of this section: This PR was generated using the `create-pull-request` skill. 3. **Highlight/Discuss**: Elaborate on the technical implementation. Explain *how* you changed the code or documentation and point out any specific logic or layout choices you want the reviewer to notice. From e2f2bc285169f4819d0acc0a96593fa6497f5335 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 15:39:28 +0800 Subject: [PATCH 06/23] Add PR body content for create-pull-request skill --- pr-body-content.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 pr-body-content.md diff --git a/pr-body-content.md b/pr-body-content.md new file mode 100644 index 0000000000..b09006e466 --- /dev/null +++ b/pr-body-content.md @@ -0,0 +1,89 @@ +**What is the purpose of this pull request?** + +- [x] Documentation update +- [ ] Bug fix +- [x] Feature addition or enhancement +- [ ] Code maintenance +- [ ] DevOps +- [x] Improve developer experience +- [ ] Others, please explain: + + + +**Overview of changes:** + +Add a new GitHub skill for creating pull requests that follows MarkBind project conventions and supports fork-to-upstream workflows. + +**Anything you'd like to highlight/discuss:** + +This skill was adapted from Cline's original create-pull-request skill with modifications to support fork-to-upstream workflows and automated upstream remote detection. The skill provides comprehensive guidance for PR creation including prerequisite checks, context gathering, git best practices, and template-based PR generation. + +**Testing instructions:** + +Test the skill by running it on a feature branch with changes. Verify that it correctly: +- Detects gh CLI installation and authentication +- Identifies upstream remotes and base branches +- Analyzes commits and diffs +- Generates PR descriptions following the MarkBind template +- Handles common error scenarios + +**Proposed commit message: (wrap lines at 72 characters)** + + + +Add create-pull-request GitHub skill + +Add a comprehensive GitHub skill for creating pull requests that follows +MarkBind project conventions. The skill supports fork-to-upstream workflows, +automated upstream remote detection, and template-based PR generation. +Adapted from Cline's original skill with MarkBind-specific modifications. + +--- + +**Checklist:** :ballot_box_with_check: + + + +- [x] Updated the documentation for feature additions and enhancements +- [ ] Added tests for bug fixes or features +- [ ] Linked all related issues +- [x] No unrelated changes + + + +--- + +**Reviewer checklist:** + +Indicate the [SEMVER](https://semver.org/) impact of the PR: +- [ ] Major (when you make incompatible API changes) +- [ ] Minor (when you add functionality in a backward compatible manner) +- [ ] Patch (when you make backward compatible bug fixes) + +At the end of the review, please label the PR with the appropriate label: `r.Major`, `r.Minor`, `r.Patch`. + +Breaking change release note preparation (if applicable): +- To be included in the release note for any feature that is made obsolete/breaking + +> Give a brief explanation note about: +> - what was the old feature that was made obsolete +> - any replacement feature (if any), and +> - how the author should modify his website to migrate from the old feature to the replacement feature (if possible). \ No newline at end of file From 97887e2eeeb55aec1c99064189a2aeae4777d438 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 15:43:26 +0800 Subject: [PATCH 07/23] Revert "Add PR body content for create-pull-request skill" This reverts commit e2f2bc285169f4819d0acc0a96593fa6497f5335. --- pr-body-content.md | 89 ---------------------------------------------- 1 file changed, 89 deletions(-) delete mode 100644 pr-body-content.md diff --git a/pr-body-content.md b/pr-body-content.md deleted file mode 100644 index b09006e466..0000000000 --- a/pr-body-content.md +++ /dev/null @@ -1,89 +0,0 @@ -**What is the purpose of this pull request?** - -- [x] Documentation update -- [ ] Bug fix -- [x] Feature addition or enhancement -- [ ] Code maintenance -- [ ] DevOps -- [x] Improve developer experience -- [ ] Others, please explain: - - - -**Overview of changes:** - -Add a new GitHub skill for creating pull requests that follows MarkBind project conventions and supports fork-to-upstream workflows. - -**Anything you'd like to highlight/discuss:** - -This skill was adapted from Cline's original create-pull-request skill with modifications to support fork-to-upstream workflows and automated upstream remote detection. The skill provides comprehensive guidance for PR creation including prerequisite checks, context gathering, git best practices, and template-based PR generation. - -**Testing instructions:** - -Test the skill by running it on a feature branch with changes. Verify that it correctly: -- Detects gh CLI installation and authentication -- Identifies upstream remotes and base branches -- Analyzes commits and diffs -- Generates PR descriptions following the MarkBind template -- Handles common error scenarios - -**Proposed commit message: (wrap lines at 72 characters)** - - - -Add create-pull-request GitHub skill - -Add a comprehensive GitHub skill for creating pull requests that follows -MarkBind project conventions. The skill supports fork-to-upstream workflows, -automated upstream remote detection, and template-based PR generation. -Adapted from Cline's original skill with MarkBind-specific modifications. - ---- - -**Checklist:** :ballot_box_with_check: - - - -- [x] Updated the documentation for feature additions and enhancements -- [ ] Added tests for bug fixes or features -- [ ] Linked all related issues -- [x] No unrelated changes - - - ---- - -**Reviewer checklist:** - -Indicate the [SEMVER](https://semver.org/) impact of the PR: -- [ ] Major (when you make incompatible API changes) -- [ ] Minor (when you add functionality in a backward compatible manner) -- [ ] Patch (when you make backward compatible bug fixes) - -At the end of the review, please label the PR with the appropriate label: `r.Major`, `r.Minor`, `r.Patch`. - -Breaking change release note preparation (if applicable): -- To be included in the release note for any feature that is made obsolete/breaking - -> Give a brief explanation note about: -> - what was the old feature that was made obsolete -> - any replacement feature (if any), and -> - how the author should modify his website to migrate from the old feature to the replacement feature (if possible). \ No newline at end of file From 4801c313a1413bf447bcfa44e18446abd616221a Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Tue, 27 Jan 2026 16:00:01 +0800 Subject: [PATCH 08/23] Add more specifics when filling template --- .github/skills/create-pull-request/SKILL.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index c2ec558cf1..9d7b266c66 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -149,7 +149,11 @@ git push origin HEAD --force-with-lease - Notify the user if the PR template missing before asking if they would like to proceed. When filling out the template: -1. **Purpose Checklist**: Based on the file changes detected (e.g., `.md` for Documentation, `test/` for Features), check the relevant boxes under **"What is the purpose of this pull request?"**. If it doesn't fit the main categories, use the "Others" box and provide a 1-sentence explanation. +1. **Purpose Checklist**: Based on the file changes detected check the relevant boxes under **"What is the purpose of this pull request?"**. + - Check **Documentation update** ONLY if files within the `docs/` directory were modified. + - Check **Feature addition or enhancement** if new logic is added to `src/` or core components. + - Check **Bug fix** if the commit messages or code diff indicate a correction. + - If it doesn't fit the main categories, use the "Others" box and provide a 1-sentence explanation. - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. 2. **Overview of changes**: Provide a high-level, 1-2 sentence summary of what this PR achieves. @@ -167,7 +171,7 @@ When filling out the template: - Follow the [SE-Education standards](https://se-education.org/guides/conventions/git.html) referenced in the template. 6. **Checklist**: Analyze the changes to check the appropriate boxes: - - Check "Updated documentation" if `.md` files in the docs folder were modified. + - Check "Updated documentation" ONLY if changes are detected in the `docs/` folder. - Check "Added tests" if files in `test` or `spec` files were add or modified. - Check "Linked all related issues" if you identified an issue number. - Check "No unrelated changes" after verifying the diff doesn't contain stray edits. From 55570c59311cd104d5ef0263cee5954361e1842d Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Wed, 28 Jan 2026 21:07:24 +0800 Subject: [PATCH 09/23] Add more specifics to diff analysis & create pr --- .github/skills/create-pull-request/SKILL.md | 25 ++++++++++++++++----- 1 file changed, 19 insertions(+), 6 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 9d7b266c66..2bbabeeb2a 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -43,6 +43,7 @@ If there are uncommitted changes, ask the user whether to: - Commit them as part of this PR - Stash them temporarily - Discard them (with caution) +- **Important** Do not stage any uncomitted changes without explict request/reply by the user ## Gather Context @@ -89,7 +90,13 @@ Review these commits to understand: git diff upstream/main..HEAD --stat ``` -This shows which files changed and helps identify the type of change. +This shows which files changed and helps identify the type of change. Use this to perform a **Deep Diff Analysis** which will be crucial in understanding how to classify these changes when creating the PR.: +- Impact Surface Area: + - Identify which directory the changes were made (e.g. `packages/`, `docs/`). + - Note any changes to `package.json` or lockfiles (e.g., `package-lock.json`). +- Logic: + - Distinguish between actual logic changes in `.js`, `.ts` files versus configuration changes (`.yml`, `.json`, etc). + - Understand the context of these changes and if or how they link to one another. ## Information Gathering @@ -98,7 +105,7 @@ Before creating the PR, you need the following information. Check if it can be i - Branch name (e.g., `fix/issue-123`, `feature/new-login`) - Changed files and their content -If any critical information is missing, use `ask_followup_question` to ask the user: +If any critical information is missing, ask the user clarifying questions: ### Required Information @@ -151,8 +158,15 @@ git push origin HEAD --force-with-lease When filling out the template: 1. **Purpose Checklist**: Based on the file changes detected check the relevant boxes under **"What is the purpose of this pull request?"**. - Check **Documentation update** ONLY if files within the `docs/` directory were modified. - - Check **Feature addition or enhancement** if new logic is added to `src/` or core components. - - Check **Bug fix** if the commit messages or code diff indicate a correction. + - Check **Feature addition or enhancement** ONLY if + - **Code Diff Profile**: + - Creation of new logic is added to files within the `packages/` directory (specifically NOT refactored or fixed logic refer to bug fixes section below). + - Addition of new exported functions or classes. + - Check **Bug fix** ONLY if the commit messages or code diff in the `packages/` directory indicate a correction. + - **Logic Indicators**: Look for "Fix", "Patch", "Hotfix", "Close", or "Resolve" in commit messages. + - Check **Developer Experience** ONLY if + - Changes in the `packages/` directory focus on code quality (e.g., commit messages include "refactor", "improve", "cleanup", or "optimize"). + - The changes are indirect tools or scripts specifically designed to improve the development workflow (e.g., CI/CD improvements, linting rules, or internal dev-tooling). - If it doesn't fit the main categories, use the "Others" box and provide a 1-sentence explanation. - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. @@ -186,7 +200,7 @@ gh pr create --repo upstream_owner/repo_name --base main --head your_username:yo Alternatively, create as draft if the user wants review before marking ready: ```bash -gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft +gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --draft ``` ## Post-Creation @@ -221,7 +235,6 @@ After creating the PR: Before finalizing, ensure: - [ ] `gh` CLI is installed and authenticated - [ ] Working directory is clean -- [ ] All commits are pushed - [ ] Branch is up-to-date with base branch - [ ] Related issue number is identified, or placeholder is used - [ ] PR description follows the template exactly From 40339473207e2759c9bd5e0f9a2d5213851559f5 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Wed, 28 Jan 2026 21:14:53 +0800 Subject: [PATCH 10/23] Move skill to .opencode directory --- {.github => .opencode}/skills/create-pull-request/SKILL.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename {.github => .opencode}/skills/create-pull-request/SKILL.md (98%) diff --git a/.github/skills/create-pull-request/SKILL.md b/.opencode/skills/create-pull-request/SKILL.md similarity index 98% rename from .github/skills/create-pull-request/SKILL.md rename to .opencode/skills/create-pull-request/SKILL.md index 2bbabeeb2a..9ec6e21aab 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.opencode/skills/create-pull-request/SKILL.md @@ -43,7 +43,7 @@ If there are uncommitted changes, ask the user whether to: - Commit them as part of this PR - Stash them temporarily - Discard them (with caution) -- **Important** Do not stage any uncomitted changes without explict request/reply by the user +- **Important** Do not stage any uncommitted changes without explict request/reply by the user ## Gather Context @@ -168,7 +168,7 @@ When filling out the template: - Changes in the `packages/` directory focus on code quality (e.g., commit messages include "refactor", "improve", "cleanup", or "optimize"). - The changes are indirect tools or scripts specifically designed to improve the development workflow (e.g., CI/CD improvements, linting rules, or internal dev-tooling). - If it doesn't fit the main categories, use the "Others" box and provide a 1-sentence explanation. - - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. + - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. Skip if missing or if user replies "N/A". 2. **Overview of changes**: Provide a high-level, 1-2 sentence summary of what this PR achieves. - **Mandatory Note**: Append this exact line to the end of this section: This PR was generated using the `create-pull-request` skill. From 85ce686794914dc1462dd8913caa902e4bb57714 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Wed, 28 Jan 2026 21:31:18 +0800 Subject: [PATCH 11/23] Add dry run option for local PR creation --- .opencode/skills/create-pull-request/SKILL.md | 20 ++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/.opencode/skills/create-pull-request/SKILL.md b/.opencode/skills/create-pull-request/SKILL.md index 9ec6e21aab..abc3d4151b 100644 --- a/.opencode/skills/create-pull-request/SKILL.md +++ b/.opencode/skills/create-pull-request/SKILL.md @@ -9,6 +9,7 @@ Modification: Modified to support **Fork-to-Upstream** workflows and automated u # Create Pull Request (Fork-to-Upstream Version) This skill guides you through creating a well-structured GitHub pull request that follows project conventions and best practices. +**Important**: Follow each step closely. Do not default to a more direct approach. ## Prerequisites Check @@ -194,15 +195,20 @@ When filling out the template: ### Create PR with gh CLI -```bash -gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" -``` +**Standard PR**: + ```bash + gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" + ``` -Alternatively, create as draft if the user wants review before marking ready: -```bash -gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --draft -``` +**Draft PR (For early feedback)**: + ```bash + gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --draft + ``` +**Dry Run (To preview the PR locally without creating it)**: + ```bash + gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --dry-run + ``` ## Post-Creation After creating the PR: From d14888b7340060d3b8f2768152dae1eba3bfc897 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Wed, 28 Jan 2026 22:17:49 +0800 Subject: [PATCH 12/23] Add opencode.json and more explicit steps in skill --- .opencode/skills/create-pull-request/SKILL.md | 7 +++++-- opencode.json | 5 +++++ 2 files changed, 10 insertions(+), 2 deletions(-) create mode 100644 opencode.json diff --git a/.opencode/skills/create-pull-request/SKILL.md b/.opencode/skills/create-pull-request/SKILL.md index abc3d4151b..8e05127c3a 100644 --- a/.opencode/skills/create-pull-request/SKILL.md +++ b/.opencode/skills/create-pull-request/SKILL.md @@ -1,9 +1,10 @@ --- name: create-pull-request description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. -Credit: This skill was adapted from the original `create-pull-request` skill developed by the **[Cline](https://github.com/cline/cline)** team. +compatibility: opencode +credit: This skill was adapted from the original `create-pull-request` skill developed by the **[Cline](https://github.com/cline/cline)** team. - **Original Source**: [cline/cline/.cline/skills/create-pull-request](https://github.com/cline/cline/blob/main/.cline/skills/create-pull-request/SKILL.md) -Modification: Modified to support **Fork-to-Upstream** workflows and automated upstream remote detection. +modification: Modified to support **Fork-to-Upstream** workflows and automated upstream remote detection. --- # Create Pull Request (Fork-to-Upstream Version) @@ -195,6 +196,8 @@ When filling out the template: ### Create PR with gh CLI +**Important**: If the user did not specify one of the following options in their request, ask the user which they would like before proceeding. Do not assume which option without explicit confirmation from the user. + **Standard PR**: ```bash gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" diff --git a/opencode.json b/opencode.json new file mode 100644 index 0000000000..1378daa246 --- /dev/null +++ b/opencode.json @@ -0,0 +1,5 @@ +{ + "permission": { + "skill": "allow" + } +} \ No newline at end of file From 37e0d4c316253967216fcd08c454c33082df10f6 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 1 Feb 2026 17:27:38 +0800 Subject: [PATCH 13/23] Update opencode.json --- opencode.json | 1 + 1 file changed, 1 insertion(+) diff --git a/opencode.json b/opencode.json index 1378daa246..a363131a27 100644 --- a/opencode.json +++ b/opencode.json @@ -1,4 +1,5 @@ { + "$schema": "https://opencode.ai/config.json", "permission": { "skill": "allow" } From 6618f85003d7b89342fd7cbc8e58f407cf3f5097 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Thu, 5 Feb 2026 11:41:44 +0800 Subject: [PATCH 14/23] Move Skill back to .github directory --- {.opencode => .github}/skills/create-pull-request/SKILL.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename {.opencode => .github}/skills/create-pull-request/SKILL.md (100%) diff --git a/.opencode/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md similarity index 100% rename from .opencode/skills/create-pull-request/SKILL.md rename to .github/skills/create-pull-request/SKILL.md From 6f07382e93aff643bf07ae3f777f8518c4f4c545 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Thu, 5 Feb 2026 11:48:01 +0800 Subject: [PATCH 15/23] Remove ability to directly create a reviewable PR This ensures that the user can only create either a draft or a dry-run to view the generated PR. This aims to encourage the author to personally review the generated PR and make the required changes or additions before setting as ready for review. --- .github/skills/create-pull-request/SKILL.md | 5 ----- .gitignore | 5 ++++- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 8e05127c3a..61e93aba21 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -198,11 +198,6 @@ When filling out the template: **Important**: If the user did not specify one of the following options in their request, ask the user which they would like before proceeding. Do not assume which option without explicit confirmation from the user. -**Standard PR**: - ```bash - gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" - ``` - **Draft PR (For early feedback)**: ```bash gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --draft diff --git a/.gitignore b/.gitignore index 354522f152..7c2d30886b 100644 --- a/.gitignore +++ b/.gitignore @@ -109,4 +109,7 @@ packages/core/src/lib/progress/*.js # Nx for Lerna .nx/cache -.nx/workspace-data \ No newline at end of file +.nx/workspace-data + +# AI tool-specific configuration +.opencode \ No newline at end of file From c4d80c3ab54f8f4d2a878c5aa5217ed65085e755 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 17:32:24 +0800 Subject: [PATCH 16/23] Fix frontmatter issue causing failed detection of skill --- .github/skills/create-pull-request/SKILL.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 61e93aba21..4da8dfe8f6 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -2,8 +2,9 @@ name: create-pull-request description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. compatibility: opencode -credit: This skill was adapted from the original `create-pull-request` skill developed by the **[Cline](https://github.com/cline/cline)** team. -- **Original Source**: [cline/cline/.cline/skills/create-pull-request](https://github.com/cline/cline/blob/main/.cline/skills/create-pull-request/SKILL.md) +credit: | + This skill was adapted from the original `create-pull-request` skill developed by the **[Cline](https://github.com/cline/cline)** team. + - **Original Source**: [cline/cline/.cline/skills/create-pull-request](https://github.com/cline/cline/blob/main/.cline/skills/create-pull-request/SKILL.md) modification: Modified to support **Fork-to-Upstream** workflows and automated upstream remote detection. --- From f597716f13af884992810b539482cb13c93f6fac Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 21:54:25 +0800 Subject: [PATCH 17/23] Add helpers scripts and additional resources --- .../create-pull-request/ANALYSIS_GUIDE.md | 11 + .../create-pull-request/PR_STANDARDS.md | 15 + .../skills/create-pull-request/RESOURCES.md | 16 + .github/skills/create-pull-request/SKILL.md | 332 ++++++++---------- .../helpers/check_git_hygiene.sh | 21 ++ .../helpers/check_prereqs.sh | 0 .../helpers/gather_context.sh | 33 ++ .../helpers/prepare_pr_bundle.sh | 22 ++ .../helpers/validate_mode.sh | 14 + opencode.json | 6 - 10 files changed, 273 insertions(+), 197 deletions(-) create mode 100644 .github/skills/create-pull-request/ANALYSIS_GUIDE.md create mode 100644 .github/skills/create-pull-request/PR_STANDARDS.md create mode 100644 .github/skills/create-pull-request/RESOURCES.md create mode 100644 .github/skills/create-pull-request/helpers/check_git_hygiene.sh create mode 100644 .github/skills/create-pull-request/helpers/check_prereqs.sh create mode 100644 .github/skills/create-pull-request/helpers/gather_context.sh create mode 100644 .github/skills/create-pull-request/helpers/prepare_pr_bundle.sh create mode 100644 .github/skills/create-pull-request/helpers/validate_mode.sh delete mode 100644 opencode.json diff --git a/.github/skills/create-pull-request/ANALYSIS_GUIDE.md b/.github/skills/create-pull-request/ANALYSIS_GUIDE.md new file mode 100644 index 0000000000..acc1f673b7 --- /dev/null +++ b/.github/skills/create-pull-request/ANALYSIS_GUIDE.md @@ -0,0 +1,11 @@ +# Deep Diff Analysis Rubric + +## 1. File Linkage Patterns +- **Package Logic**: Changes in `packages/*/src` should usually be paired with changes in `packages/*/test`. +- **Documentation**: Logic changes that affect user-facing features **must** have corresponding updates in `docs/` or `_markbind/`. +- **Dependency Changes**: Changes to `package.json` require a review of `package-lock.json` and a check for unused imports in `.js/.ts` files. + +## 2. Change Classification +- **Bug Fix**: Look for evidence of error handling, edge case management, or logic correction. +- **Feature**: Look for new exported constants, classes, or public methods. +- **Refactor**: Changes that modify structure/readability without changing external behavior. \ No newline at end of file diff --git a/.github/skills/create-pull-request/PR_STANDARDS.md b/.github/skills/create-pull-request/PR_STANDARDS.md new file mode 100644 index 0000000000..5cfeb337d0 --- /dev/null +++ b/.github/skills/create-pull-request/PR_STANDARDS.md @@ -0,0 +1,15 @@ +# Markbind PR Classification Rules + +## Purpose Checklist Rules +- **Documentation update**: Check ONLY if `docs/` folder contains diffs. +- **Feature Addition**: Check ONLY if the **Deep Diff Analysis** & **Information Gathering** corresponds to one of the following. + - Creation of new logic is added to files within the `packages/` directory (specifically **NOT refactored or fixed logic.**). +- **Bug fix**: Check ONLY if the **Deep Diff Analysis** & **Information Gathering** suggest that changes in the `packages/` logic suggests a correction and more robust logic handling. +- **Developer Experience**: Check ONLY if changes are refactors improving code quality, CI/CD, or internal dev-tooling. +- If it doesn't fit the main categories, use the **Others** box and provide a 1-sentence explanation. + +## Final Checklist Section +- **Updated documentation**: Check if `docs/` is modified. +- **Added tests**: Check if `test/` or `spec/` files are modified. +- **Linked issues**: Check if an Issue ID was found and linked in the body. +- **No unrelated changes**: Check after verifying the diff doesn't contain stray edits. \ No newline at end of file diff --git a/.github/skills/create-pull-request/RESOURCES.md b/.github/skills/create-pull-request/RESOURCES.md new file mode 100644 index 0000000000..19709e0550 --- /dev/null +++ b/.github/skills/create-pull-request/RESOURCES.md @@ -0,0 +1,16 @@ +# Troubleshooting & Resources + +## Installation: gh CLI +- **macOS**: `brew install gh` +- **Windows**: `winget install --id GitHub.cli` +- **Linux**: See [cli.github.com](https://cli.github.com/) + +## Authentication +Run `gh auth login` and follow the interactive prompts to authenticate with your GitHub account. + +## Working Directory +If there are uncommitted changes, ask the user whether to: +1. `git add . && git commit -m "your message"` +2. `git stash` +3. `git checkout -- .` (Warning: Discards changes) +**Important** Do not stage any uncommitted changes without explict request/reply by the user \ No newline at end of file diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 4da8dfe8f6..66e6a06635 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -11,204 +11,154 @@ modification: Modified to support **Fork-to-Upstream** workflows and automated u # Create Pull Request (Fork-to-Upstream Version) This skill guides you through creating a well-structured GitHub pull request that follows project conventions and best practices. -**Important**: Follow each step closely. Do not default to a more direct approach. - -## Prerequisites Check - -Before proceeding, verify the following: - -### 1. Check if `gh` CLI is installed - -```bash -gh --version -``` - -If not installed, inform the user: -> The GitHub CLI (`gh`) is required but not installed. Please install it: -> - macOS: `brew install gh` -> - Other: https://cli.github.com/ - -### 2. Check if authenticated with GitHub - -```bash -gh auth status -``` - -If not authenticated, guide the user to run `gh auth login`. - -### 3. Verify clean working directory - -```bash -git status -``` - -If there are uncommitted changes, ask the user whether to: -- Commit them as part of this PR -- Stash them temporarily -- Discard them (with caution) -- **Important** Do not stage any uncommitted changes without explict request/reply by the user - -## Gather Context - -### 1. Identify the current branch - -```bash -git branch --show-current -``` - -Ensure you're not on `main` or `master`. If so, ask the user to create or switch to a feature branch. - -### 2. Identify the Upstream Remote - -```bash -git remote -v -``` - -If 'upstream' is missing, instruct the user to add it: git remote add upstream `https://github.com/ORIGINAL_OWNER/REPO_NAME.git` - -### 3. Find the base branch on Upstream - -```bash -# First, get the actual owner/repo string for the upstream remote -UPSTREAM_REPO=$(git remote get-url upstream | sed 's/.*github.com[\/:]//;s/\.git$//') - -# Then use that string to get the default branch -gh repo view "$UPSTREAM_REPO" --json defaultBranchRef -q .defaultBranchRef.name -``` - -### 4. Analyze recent commits relevant to this PR from the Upstream - -```bash -git log upstream/main..HEAD --oneline --no-decorate -``` - -Review these commits to understand: -- What changes are being introduced -- The scope of the PR (single feature/fix or multiple changes) -- Whether commits should be squashed or reorganized - -### 5. Review the diff - -```bash -git diff upstream/main..HEAD --stat -``` - -This shows which files changed and helps identify the type of change. Use this to perform a **Deep Diff Analysis** which will be crucial in understanding how to classify these changes when creating the PR.: -- Impact Surface Area: - - Identify which directory the changes were made (e.g. `packages/`, `docs/`). - - Note any changes to `package.json` or lockfiles (e.g., `package-lock.json`). -- Logic: - - Distinguish between actual logic changes in `.js`, `.ts` files versus configuration changes (`.yml`, `.json`, etc). - - Understand the context of these changes and if or how they link to one another. - -## Information Gathering - -Before creating the PR, you need the following information. Check if it can be inferred from: -- Commit messages -- Branch name (e.g., `fix/issue-123`, `feature/new-login`) -- Changed files and their content - -If any critical information is missing, ask the user clarifying questions: - -### Required Information - -1. **Related Issue Number**: Look for patterns like `#123`, `fixes #123`, or `closes #123` in commit messages -2. **Description**: What problem does this solve? Why were these changes made? -3. **Type of Change**: Bug fix, new feature, breaking change, refactor, cosmetic, documentation, or workflow -4. **Test Procedure**: How was this tested? What could break? - -### Example clarifying question - -If the issue number is not found: -> I couldn't find a related issue number in the commit messages or branch name. What GitHub issue does this PR address? (Enter the issue number, e.g., "123" or "N/A" for small fixes) - -## Git Best Practices - -Before creating the PR, consider these best practices: - -### Commit Hygiene - -1. **Atomic commits**: Each commit should represent a single logical change -2. **Clear commit messages**: Follow conventional commit format when possible -3. **No merge commits**: Prefer rebasing over merging to keep history clean - -### Branch Management - -1. **Rebase on latest main** (if needed): - ```bash - git fetch upstream - git rebase upstream/main - ``` - -### Push Changes - -Ensure all commits are pushed: -```bash -git push origin HEAD -``` - -If the branch was rebased, you may need: -```bash -git push origin HEAD --force-with-lease -``` - -## Create the Pull Request - -**IMPORTANT**: Read and use the PR template at `.github/PULL_REQUEST_TEMPLATE`. The PR body format must **strictly match** the template structure. Do not deviate from the template format. - -- Notify the user if the PR template missing before asking if they would like to proceed. - -When filling out the template: -1. **Purpose Checklist**: Based on the file changes detected check the relevant boxes under **"What is the purpose of this pull request?"**. - - Check **Documentation update** ONLY if files within the `docs/` directory were modified. - - Check **Feature addition or enhancement** ONLY if - - **Code Diff Profile**: - - Creation of new logic is added to files within the `packages/` directory (specifically NOT refactored or fixed logic refer to bug fixes section below). - - Addition of new exported functions or classes. - - Check **Bug fix** ONLY if the commit messages or code diff in the `packages/` directory indicate a correction. - - **Logic Indicators**: Look for "Fix", "Patch", "Hotfix", "Close", or "Resolve" in commit messages. - - Check **Developer Experience** ONLY if - - Changes in the `packages/` directory focus on code quality (e.g., commit messages include "refactor", "improve", "cleanup", or "optimize"). - - The changes are indirect tools or scripts specifically designed to improve the development workflow (e.g., CI/CD improvements, linting rules, or internal dev-tooling). - - If it doesn't fit the main categories, use the "Others" box and provide a 1-sentence explanation. - - **Linking Issues**: Search for issue numbers in your commits. If found, use keywords like "Fixes #123" or "Resolves #123" in the comment block provided. Skip if missing or if user replies "N/A". - -2. **Overview of changes**: Provide a high-level, 1-2 sentence summary of what this PR achieves. - - **Mandatory Note**: Append this exact line to the end of this section: This PR was generated using the `create-pull-request` skill. - -3. **Highlight/Discuss**: Elaborate on the technical implementation. Explain *how* you changed the code or documentation and point out any specific logic or layout choices you want the reviewer to notice. - -4. **Testing instructions**: Identify any manual testing steps. - - *Example: "Run `markbind serve`, navigate to /docs/plugin, and verify the new warning component renders correctly."* - - If no special steps are needed beyond automated tests, leave this blank or state "No special instructions." - -5. **Proposed commit message**: Generate a high-quality commit message: - - **Title**: Maximum 50 characters. - - **Body**: Wrap lines at 72 characters. - - Follow the [SE-Education standards](https://se-education.org/guides/conventions/git.html) referenced in the template. - -6. **Checklist**: Analyze the changes to check the appropriate boxes: - - Check "Updated documentation" ONLY if changes are detected in the `docs/` folder. - - Check "Added tests" if files in `test` or `spec` files were add or modified. - - Check "Linked all related issues" if you identified an issue number. - - Check "No unrelated changes" after verifying the diff doesn't contain stray edits. - -7. **Reviewer Section**: Leave the **Reviewer checklist** and **SEMVER** sections **unchecked** and unmodified. These are for the maintainers to fill out during review. - -### Create PR with gh CLI - -**Important**: If the user did not specify one of the following options in their request, ask the user which they would like before proceeding. Do not assume which option without explicit confirmation from the user. - -**Draft PR (For early feedback)**: +**Important**: Follow each step closely. Do not default to a more direct approach. For each section, you **must** follow these each step number incrementally (**DO NOT SKIP ANY STEPS**). + +## Step 1. Mode Validation (Mandatory Start) + +**Strict Requirement**: You must determine the PR mode from the user's initial request before executing any other commands. + +## Step 1.1. **Check Mode**: Run `bash helpers/validate_mode.sh "{{user_message}}"`. + +## Step 1.2. **Evaluate**: + - **If `MODE: UNDEFINED`**: + - **TERMINATE IMMEDIATELY**. Do not check prerequisites. Do not gather context. Do not proceed with the skill. + - **Response to User**: + > "To create a pull request, I need to know the intended mode. Please specify if you would like a **Standard PR**, a **Draft PR** (for early feedback), or a **Dry Run** (to preview the PR locally)." + - **If `MODE: DRAFT` or `DRY_RUN`**: + - Record the mode and proceed to **## Step 2. Prerequisites Check**. + +## Step 2. Prerequisites Check + +**Strict Requirement**: You must verify the environment before any other actions. Do not proceed if any check fails. + +### Step 2.1. **Execute Checks**: Run `bash helpers/check_prereqs.sh`. + +### Step 2.2. **Handle Results**: + - **If `gh_not_installed`**: Output the installation instructions found in `RESOURCES.md` and stop. + - **If `gh_not_authenticated`**: Instruct the user to run `gh auth login` as detailed in `RESOURCES.md` and stop. + - **If `dirty_working_dir`**: + - **STOP** and display the current `git status`. + - Explicitly ask the user: "Would you like to commit these changes, stash them, or discard them?" as detailed in `RESOURCES.md` + - **Important**: Do not stage any uncommitted changes without explicit confirmation. + - **If `all_systems_go`**: Proceed to "Gather Context." + +## Step 3. Gather Context + +**Strict Requirement**: You must analyze the delta between your local branch and `origin` while ensuring an `upstream` target is configured. + +**Strict Requirement**: You **must** follow these 4 steps incrementally (**DO NOT SKIP ANY STEPS**) + +### Step 3.1. **Execute Discovery**: Run `bash helpers/gather_context.sh`. + +### Step 3.2. **Upstream Verification**: + - Check the `UPSTREAM_STATUS`. + - **If `MISSING`**: + - **STOP**. Inform the user that the `upstream` remote is required for the Fork-to-Upstream workflow. + - Provide the command: `git remote add upstream `. + - **If `EXISTS`**: Proceed. + +### Step 3.3. **Branch & Commit Validation**: + - Ensure `CURRENT_BRANCH` is not `main` or `master`. + - Review the commits in the `AHEAD_BY` count to understand scope and intent. + +### Step 3.4. **Deep Diff Analysis (Three-Step Process)**: + + **Step A: Structural Mapping** + - Use the `DIFF_SUMMARY` to identify all affected directories. + - Identify the **Primary Impact Zone** (where the most significant logic resides). + + **Step B: Detailed Investigation** + - For every file in the Primary Impact Zone, run `git diff origin/master..HEAD -- [file_path]`. + - **Requirement**: Do not just skim. Read the logic to understand *how* the implementation achieves the intent found in the commits. + - Cross-reference with `ANALYSIS_GUIDE.md` to identify missing linkages (e.g., "Logic changed, but no tests found in `DIFF_SUMMARY`"). + + **Step C: Synthesis** + - Mentally map how these files interact. + - *Example: "The logic change in `packages/core` necessitates the configuration update seen in `opencode.json`."* + +## Step 4. Information Gathering + +### Step 4.1. **Validate & Infer**: + - **Type of Change (Nature & Purpose Analysis)**: Do not rely solely on keywords. Use your **Deep Diff Analysis** to classify the changes based on its architectural impact. + - **Description**: Do not provide a generic summary. Construct a "Technical Summary" that covers: + - **The "What"**: Document the specific mechanical changes. + - **The "Why"**: Based on the code context, infer the technical necessity. Why was this specific approach taken over another? + - **The "Context"**: Describe how this change flows through the system. + - **The "Conclusion"**: State the expected final state of the system once this PR is merged. + - **Test Procedure**: Review the `DIFF_SUMMARY`. If no new tests were added, you **must** ask: *"How should this change be manually tested, and what are the potential breaking points?"*. + +### Step 4.2. **User Confirmation**: + - Present your gathered "PR Profile" to the user: + - **Type**: [Type] + - **Description**: [Summary] + - **Tests**: [Procedure] + - Ask: *"Does this profile look correct, or should I adjust anything before I check Git Best Practices?"* + +## Step 5. Git Best Practices + +**Strict Requirement**: You must audit the branch history and ensure it is "PR-ready" according to project standards. + +### Step 5.1. **Run Hygiene Audit**: Execute `bash helpers/check_git_hygiene.sh`. + +### Step 5.2. **Address Commit Hygiene**: + - **Atomic Commits**: If `LARGE_COMMITS` are detected, ask: *"I noticed commit [hash] touches many files. Should we squash or split these to maintain atomic commit history?"* + - **Conventional Commits**: Verify if existing messages follow the [SE-Education standards](https://se-education.org/guides/conventions/git.html). If not, suggest: `git commit --amend` for the most recent one. + - **Merge Commits**: If `MERGE_COMMITS_FOUND` is not "None", inform the user: *"I detected merge commits. Project policy prefers a clean history via rebasing."* + +### Step 5.3. **Branch Management (Rebase Flow)**: + - Check `BEHIND_UPSTREAM_MAIN`. + - **If > 0**: You **must** recommend a rebase to ensure no conflicts occur after PR creation: + ```bash + git fetch upstream + git rebase upstream/main + ``` + - **Warning**: If a rebase occurs, explicitly notify the user that the next push will require `--force-with-lease`. + +### Step 5.4. **Final Synchronization**: + - Ensure all local work is reflected on the remote fork: + ```bash + git push origin HEAD + ``` + - If a rebase was performed: `git push origin HEAD --force-with-lease`. + - **Verification**: Confirm the push was successful before moving to "Create the Pull Request." + +## Step 6. Create the Pull Request + +**Strict Requirement**: You must use the project's PR template and follow the Fork-to-Upstream execution flow. + +### Step 6.1. Template Preparation + - **Check Template**: Run `bash helpers/prepare_pr_bundle.sh`. + - **If `TEMPLATE_MISSING`**: Notify the user and ask: *"The .github/PULL_REQUEST_TEMPLATE is missing. Should I proceed with a standard format?"* + - **Formatting**: Populate the template. Your PR body **must** strictly match the template's Markdown structure. + +### Step 6.2. Content Generation Logic (based on the Template fill in each section accordingly) + - **What is the purpose of this pull request?**: Apply rules from **Purpose Checklist Rules** in `PR_STANDARDS.md`. + - **Overview of changes**: Write 1-2 sentences. **Mandatory**: Append "This PR was generated using the `create-pull-request` skill." + - **Anything you'd like to highlight/discuss**: Explain the *how* and *why* of specific technical choices. **Important**: This section should go in depth based on the **Deep Diff Analysis** & **Information Gathering** findings. You **must** avoid buzzwords at all costs to keep the writing natural. + - **Testing instructions**: Detail manual steps (e.g., `markbind serve`). If none, leave the section blank. + - **Proposed commit message: (wrap lines at 72 characters)**: Title < 50 chars, Body wrapped at 72. Follow [SE-Education standards](https://se-education.org/guides/conventions/git.html) referenced in the template. + - **Checklist**: Apply rules from **Final Checklist Section** in `PR_STANDARDS.md`. + - **Reviewer checklist**: Leave the **Reviewer checklist** and **SEMVER** sections **unchecked** and unmodified. These are for the maintainers to fill out during review. + +### Step 6.3. Final Execution Choice +- **STOP**: You must ask the user which type of PR to create before running the command: + 1. **Draft PR**: For early feedback. + 2. **Dry Run**: Preview the PR locally. + +### Step 6.4. CLI Execution +Execute the command based on the choice: + +- **Draft PR**: ```bash gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --draft ``` -**Dry Run (To preview the PR locally without creating it)**: +- **Dry Run**: ```bash gh pr create --repo upstream_owner/repo_name --base main --head your_username:your_branch --title "PR_TITLE" --body "PR_BODY" --dry-run ``` -## Post-Creation + +## Step 7. Post-Creation After creating the PR: diff --git a/.github/skills/create-pull-request/helpers/check_git_hygiene.sh b/.github/skills/create-pull-request/helpers/check_git_hygiene.sh new file mode 100644 index 0000000000..3ccbb51a57 --- /dev/null +++ b/.github/skills/create-pull-request/helpers/check_git_hygiene.sh @@ -0,0 +1,21 @@ +#!/bin/bash + +# 1. Check for Merge Commits +MERGE_COMMITS=$(git rev-list --merges origin/master..HEAD) + +# 2. Check for Atomic Commit potential (Size check) +# Flags commits that touch more than 10 files as potentially non-atomic +LARGE_COMMITS=$(git log origin/master..HEAD --pretty=format:"%H" | while read hash; do + count=$(git diff-tree --no-commit-id --name-only -r $hash | wc -l) + if [ "$count" -gt 10 ]; then echo "$hash ($count files)"; fi +done) + +# 3. Check if Local is behind Upstream Main +git fetch upstream main --quiet +BEHIND_COUNT=$(git rev-list --count HEAD..upstream/main) + +echo "---HYGIENE_START---" +echo "MERGE_COMMITS_FOUND: ${MERGE_COMMITS:-None}" +echo "LARGE_COMMITS: ${LARGE_COMMITS:-None}" +echo "BEHIND_UPSTREAM_MAIN: $BEHIND_COUNT" +echo "---HYGIENE_END---" \ No newline at end of file diff --git a/.github/skills/create-pull-request/helpers/check_prereqs.sh b/.github/skills/create-pull-request/helpers/check_prereqs.sh new file mode 100644 index 0000000000..e69de29bb2 diff --git a/.github/skills/create-pull-request/helpers/gather_context.sh b/.github/skills/create-pull-request/helpers/gather_context.sh new file mode 100644 index 0000000000..18022f4bdc --- /dev/null +++ b/.github/skills/create-pull-request/helpers/gather_context.sh @@ -0,0 +1,33 @@ +#!/bin/bash + +# 1. Get current branch name +CURRENT_BRANCH=$(git branch --show-current) +REMOTE_NAME="origin" +DEFAULT_BRANCH=$(git remote show $REMOTE_NAME | grep 'HEAD branch' | cut -d' ' -f5) + +# 2. Upstream Verification +# Checks if a remote named 'upstream' exists +UPSTREAM_URL=$(git remote get-url upstream 2>/dev/null) +if [ -z "$UPSTREAM_URL" ]; then + UPSTREAM_STATUS="MISSING" +else + UPSTREAM_STATUS="EXISTS" +fi + +# 3. Fetch latest from origin to ensure analysis is current +git fetch $REMOTE_NAME $DEFAULT_BRANCH --quiet + +# 4. Generate Analysis Data +COMMIT_COUNT=$(git rev-list --count $REMOTE_NAME/$DEFAULT_BRANCH..HEAD) +DIFF_STAT=$(git diff $REMOTE_NAME/$DEFAULT_BRANCH..HEAD --stat) + +echo "---CONTEXT_DATA---" +echo "CURRENT_BRANCH: $CURRENT_BRANCH" +echo "BASE_REMOTE: $REMOTE_NAME" +echo "BASE_BRANCH: $DEFAULT_BRANCH" +echo "UPSTREAM_STATUS: $UPSTREAM_STATUS" +echo "UPSTREAM_URL: $UPSTREAM_URL" +echo "AHEAD_BY: $COMMIT_COUNT" +echo "DIFF_SUMMARY:" +echo "$DIFF_STAT" +echo "---END_CONTEXT_DATA---" \ No newline at end of file diff --git a/.github/skills/create-pull-request/helpers/prepare_pr_bundle.sh b/.github/skills/create-pull-request/helpers/prepare_pr_bundle.sh new file mode 100644 index 0000000000..5f7de09485 --- /dev/null +++ b/.github/skills/create-pull-request/helpers/prepare_pr_bundle.sh @@ -0,0 +1,22 @@ +#!/bin/bash + +# 1. Get Upstream Details +UPSTREAM_REPO=$(git remote get-url upstream | sed 's/.*github.com[\/:]//;s/\.git$//') +UPSTREAM_OWNER=$(echo "$UPSTREAM_REPO" | cut -d'/' -f1) + +# 2. Get Head Details (Your Fork) +MY_USERNAME=$(gh api user -q .login) +CURRENT_BRANCH=$(git branch --show-current) + +# 3. Read Template (if exists) +TEMPLATE_PATH=".github/PULL_REQUEST_TEMPLATE" +if [ ! -f "$TEMPLATE_PATH" ]; then + echo "STATUS: TEMPLATE_MISSING" +else + echo "STATUS: TEMPLATE_FOUND" +fi + +echo "---PR_BUNDLE_START---" +echo "UPSTREAM: $UPSTREAM_REPO" +echo "HEAD_STRING: $MY_USERNAME:$CURRENT_BRANCH" +echo "---PR_BUNDLE_END---" \ No newline at end of file diff --git a/.github/skills/create-pull-request/helpers/validate_mode.sh b/.github/skills/create-pull-request/helpers/validate_mode.sh new file mode 100644 index 0000000000..05f6c1ddf1 --- /dev/null +++ b/.github/skills/create-pull-request/helpers/validate_mode.sh @@ -0,0 +1,14 @@ +#!/bin/bash + +# The first argument to this script should be the full user prompt/request +USER_MESSAGE=$(echo "$1" | tr '[:upper:]' '[:lower:]') + +if [[ "$USER_MESSAGE" == *"draft"* ]]; then + echo "MODE: DRAFT" +elif [[ "$USER_MESSAGE" == *"dry run"* ]] || [[ "$USER_MESSAGE" == *"dry-run"* ]]; then + echo "MODE: DRY_RUN" +elif [[ "$USER_MESSAGE" == *"standard"* ]] || [[ "$USER_MESSAGE" == *"normal"* ]]; then + echo "MODE: STANDARD" +else + echo "MODE: UNDEFINED" +fi \ No newline at end of file diff --git a/opencode.json b/opencode.json deleted file mode 100644 index a363131a27..0000000000 --- a/opencode.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "$schema": "https://opencode.ai/config.json", - "permission": { - "skill": "allow" - } -} \ No newline at end of file From 5686ace34bd11f17d34a6e8372fa31852f73df6e Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 21:58:14 +0800 Subject: [PATCH 18/23] Remove standard mode --- .github/skills/create-pull-request/helpers/validate_mode.sh | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/skills/create-pull-request/helpers/validate_mode.sh b/.github/skills/create-pull-request/helpers/validate_mode.sh index 05f6c1ddf1..e429d8c814 100644 --- a/.github/skills/create-pull-request/helpers/validate_mode.sh +++ b/.github/skills/create-pull-request/helpers/validate_mode.sh @@ -7,8 +7,6 @@ if [[ "$USER_MESSAGE" == *"draft"* ]]; then echo "MODE: DRAFT" elif [[ "$USER_MESSAGE" == *"dry run"* ]] || [[ "$USER_MESSAGE" == *"dry-run"* ]]; then echo "MODE: DRY_RUN" -elif [[ "$USER_MESSAGE" == *"standard"* ]] || [[ "$USER_MESSAGE" == *"normal"* ]]; then - echo "MODE: STANDARD" else echo "MODE: UNDEFINED" fi \ No newline at end of file From 54189ff2acda5f18e95b4b4e2628e5c54633876f Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 22:00:07 +0800 Subject: [PATCH 19/23] Remove standard mode note in skill --- .github/skills/create-pull-request/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 66e6a06635..7e311f609a 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -23,7 +23,7 @@ This skill guides you through creating a well-structured GitHub pull request tha - **If `MODE: UNDEFINED`**: - **TERMINATE IMMEDIATELY**. Do not check prerequisites. Do not gather context. Do not proceed with the skill. - **Response to User**: - > "To create a pull request, I need to know the intended mode. Please specify if you would like a **Standard PR**, a **Draft PR** (for early feedback), or a **Dry Run** (to preview the PR locally)." + > "To create a pull request, I need to know the intended mode. Please specify if you would like a **Draft PR** (for early feedback), or a **Dry Run** (to preview the PR locally)." - **If `MODE: DRAFT` or `DRY_RUN`**: - Record the mode and proceed to **## Step 2. Prerequisites Check**. From ceb024faf2a1423e2429f871e6b482e3d519eb21 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 22:06:03 +0800 Subject: [PATCH 20/23] Update description to include 2 modes supported --- .github/skills/create-pull-request/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 7e311f609a..40ca953156 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -1,6 +1,6 @@ --- name: create-pull-request -description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. +description: Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, and PR creation using the gh CLI tool. Please specify if you would like a Draft PR (for early feedback), or a Dry Run (to preview the PR locally). compatibility: opencode credit: | This skill was adapted from the original `create-pull-request` skill developed by the **[Cline](https://github.com/cline/cline)** team. From 7df252c964d44d328fb308b99c17231913ba871e Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 22:36:46 +0800 Subject: [PATCH 21/23] Remove old redundant empty script --- .github/skills/create-pull-request/helpers/check_prereqs.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 .github/skills/create-pull-request/helpers/check_prereqs.sh diff --git a/.github/skills/create-pull-request/helpers/check_prereqs.sh b/.github/skills/create-pull-request/helpers/check_prereqs.sh deleted file mode 100644 index e69de29bb2..0000000000 From b93227fece957e09bb0c354a7ae1e9510b0cba20 Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 22:44:42 +0800 Subject: [PATCH 22/23] Update gather context to get diff on master --- .github/skills/create-pull-request/SKILL.md | 2 +- .../helpers/gather_context.sh | 23 ++++++++++--------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 40ca953156..78d762cbb8 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -68,7 +68,7 @@ This skill guides you through creating a well-structured GitHub pull request tha - Identify the **Primary Impact Zone** (where the most significant logic resides). **Step B: Detailed Investigation** - - For every file in the Primary Impact Zone, run `git diff origin/master..HEAD -- [file_path]`. + - For every file in the Primary Impact Zone, run `git diff master..HEAD -- [file_path]`. (Use `main` if `COMPARISON_BASE` was `main`). - **Requirement**: Do not just skim. Read the logic to understand *how* the implementation achieves the intent found in the commits. - Cross-reference with `ANALYSIS_GUIDE.md` to identify missing linkages (e.g., "Logic changed, but no tests found in `DIFF_SUMMARY`"). diff --git a/.github/skills/create-pull-request/helpers/gather_context.sh b/.github/skills/create-pull-request/helpers/gather_context.sh index 18022f4bdc..4b2c6763eb 100644 --- a/.github/skills/create-pull-request/helpers/gather_context.sh +++ b/.github/skills/create-pull-request/helpers/gather_context.sh @@ -2,11 +2,15 @@ # 1. Get current branch name CURRENT_BRANCH=$(git branch --show-current) -REMOTE_NAME="origin" -DEFAULT_BRANCH=$(git remote show $REMOTE_NAME | grep 'HEAD branch' | cut -d' ' -f5) +LOCAL_MASTER="master" + +# Verify local master exists (fall back to main if necessary) +if ! git rev-parse --verify "$LOCAL_MASTER" &>/dev/null; then + LOCAL_MASTER="main" +fi # 2. Upstream Verification -# Checks if a remote named 'upstream' exists +# Check if 'upstream' remote exists UPSTREAM_URL=$(git remote get-url upstream 2>/dev/null) if [ -z "$UPSTREAM_URL" ]; then UPSTREAM_STATUS="MISSING" @@ -14,17 +18,14 @@ else UPSTREAM_STATUS="EXISTS" fi -# 3. Fetch latest from origin to ensure analysis is current -git fetch $REMOTE_NAME $DEFAULT_BRANCH --quiet - -# 4. Generate Analysis Data -COMMIT_COUNT=$(git rev-list --count $REMOTE_NAME/$DEFAULT_BRANCH..HEAD) -DIFF_STAT=$(git diff $REMOTE_NAME/$DEFAULT_BRANCH..HEAD --stat) +# 3. Generate Analysis Data +# We compare HEAD (current branch) against the LOCAL_MASTER identified in step 1 +COMMIT_COUNT=$(git rev-list --count $LOCAL_MASTER..HEAD) +DIFF_STAT=$(git diff $LOCAL_MASTER..HEAD --stat) echo "---CONTEXT_DATA---" echo "CURRENT_BRANCH: $CURRENT_BRANCH" -echo "BASE_REMOTE: $REMOTE_NAME" -echo "BASE_BRANCH: $DEFAULT_BRANCH" +echo "COMPARISON_BASE: $LOCAL_MASTER" echo "UPSTREAM_STATUS: $UPSTREAM_STATUS" echo "UPSTREAM_URL: $UPSTREAM_URL" echo "AHEAD_BY: $COMMIT_COUNT" From fa0ab10cfcf995d69d15aa1c97885d3d90089d0f Mon Sep 17 00:00:00 2001 From: Thaddaeus Chua Date: Sun, 8 Feb 2026 23:08:19 +0800 Subject: [PATCH 23/23] Fix accidental references to main instead of master --- .github/skills/create-pull-request/SKILL.md | 2 +- .../helpers/check_git_hygiene.sh | 23 ++++++++++++------- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/.github/skills/create-pull-request/SKILL.md b/.github/skills/create-pull-request/SKILL.md index 78d762cbb8..33ad30036d 100644 --- a/.github/skills/create-pull-request/SKILL.md +++ b/.github/skills/create-pull-request/SKILL.md @@ -106,7 +106,7 @@ This skill guides you through creating a well-structured GitHub pull request tha - **Merge Commits**: If `MERGE_COMMITS_FOUND` is not "None", inform the user: *"I detected merge commits. Project policy prefers a clean history via rebasing."* ### Step 5.3. **Branch Management (Rebase Flow)**: - - Check `BEHIND_UPSTREAM_MAIN`. + - Check `BEHIND_UPSTREAM`. - **If > 0**: You **must** recommend a rebase to ensure no conflicts occur after PR creation: ```bash git fetch upstream diff --git a/.github/skills/create-pull-request/helpers/check_git_hygiene.sh b/.github/skills/create-pull-request/helpers/check_git_hygiene.sh index 3ccbb51a57..c5418d54e2 100644 --- a/.github/skills/create-pull-request/helpers/check_git_hygiene.sh +++ b/.github/skills/create-pull-request/helpers/check_git_hygiene.sh @@ -1,21 +1,28 @@ #!/bin/bash -# 1. Check for Merge Commits -MERGE_COMMITS=$(git rev-list --merges origin/master..HEAD) +# 1. Determine the correct base branch (master vs main) +BASE_BRANCH="master" +if ! git rev-parse --verify "$BASE_BRANCH" &>/dev/null; then + BASE_BRANCH="main" +fi -# 2. Check for Atomic Commit potential (Size check) +# 2. Check for Merge Commits +MERGE_COMMITS=$(git rev-list --merges "$BASE_BRANCH"..HEAD) + +# 3. Check for Atomic Commit potential (Size check) # Flags commits that touch more than 10 files as potentially non-atomic -LARGE_COMMITS=$(git log origin/master..HEAD --pretty=format:"%H" | while read hash; do +LARGE_COMMITS=$(git log "$BASE_BRANCH"..HEAD --pretty=format:"%H" | while read hash; do count=$(git diff-tree --no-commit-id --name-only -r $hash | wc -l) if [ "$count" -gt 10 ]; then echo "$hash ($count files)"; fi done) -# 3. Check if Local is behind Upstream Main -git fetch upstream main --quiet -BEHIND_COUNT=$(git rev-list --count HEAD..upstream/main) +# 4. Check if Local is behind Upstream Main +git fetch upstream "$BASE_BRANCH" --quiet +BEHIND_COUNT=$(git rev-list --count HEAD..upstream/$BASE_BRANCH) echo "---HYGIENE_START---" echo "MERGE_COMMITS_FOUND: ${MERGE_COMMITS:-None}" echo "LARGE_COMMITS: ${LARGE_COMMITS:-None}" -echo "BEHIND_UPSTREAM_MAIN: $BEHIND_COUNT" +echo "BEHIND_UPSTREAM: $BEHIND_COUNT" +echo "BASE_BRANCH_USED: $BASE_BRANCH" echo "---HYGIENE_END---" \ No newline at end of file