Prepare PR

Prepare Pull Request

Prepare all work before creating a pull request. If an issue number is provided in $ARGUMENTS, use it. If no issue is provided, continue without requiring one.

Workflow

Follow these steps:

1. Check current git status and branch information

   • Run git status and git branch to understand the current state

2. Create branch if needed

   • If no branch name is provided and we are on the main branch, create a branch based on the code changes
   • If working on a worktree, create a branch based on the worktree branch, don't change the name
   • Otherwise, work on the current branch

3. Review commit history and code differences

   • Run git log and git diff main...HEAD to understand all changes from the main branch

4. Add changeset record if necessary

   • Manually add a file in .changeset/ directory following changeset convention

   • The package name is always @read-frog/extension. This is a single-package workspace and changesets matches the header against the name in the root package.json; a bare read-frog is not a workspace package and makes the release plan fail.

   • File shape — fill in the bump level and the summary, leave the package name as written:

     ---
     "@read-frog/extension": patch
     ---
     
     fix(subtitles): follow YouTube's own default caption track

   • Changeset summary should use conventional commit style and should match the descriptive PR title

   • Versioning rules:

     • patch (0.0.x) — Users barely notice
       • Bug fixes
       • Small feature enhancements (e.g., drag-and-drop reordering)
       • UI tweaks, performance optimizations
       • Refactors, code cleanup
       • i18n additions
       • Adding a single config toggle
     • minor (0.x.0) — Users can clearly perceive "something new"
       • Independent, complete new features (e.g., subtitle translation, TTS)
       • New AI provider support
       • Major UI overhaul (new pages/panels)
       • New user-facing configuration system (not just a single toggle)
     • major (x.0.0) — Users need to pay attention / adapt. Almost never use. Must ask user for explicit approval before using.
       • Config format incompatibility (cannot auto-migrate)
       • Removal of existing features
       • API/storage structure breaking changes
       • Fundamental migrations (e.g., Manifest V2 → V3)

   • Verify the changeset before committing: pnpm exec changeset status must list the expected bump under @read-frog/extension. A non-zero exit means the changeset is malformed and the release plan will not generate.

5. Ensure all changes are committed

   • Stage and commit any uncommitted changes
   • Do not commit the PR description markdown created under docs/; it is for local copy/paste only
   • If a docs/pr-*.md file was accidentally staged, remove it from the index before committing while keeping the local file
   • Branch should be ready for PR

6. Push the branch to remote

   • Run git push -u origin <branch-name> if needed

7. Record a demo for user-visible frontend changes

   • Same rule as /create-pr step 4: a demo is required when the diff changes user-visible behavior, and not required for implementation-only changes.
   • When one is required, invoke the record-extension-demo skill, keep the recording in the scratchpad, and upload it with gh image "<file>" --repo mengxi-ream/read-frog before writing the description. When none is required, skip straight to the next step — there is nothing to record or upload.

8. Create Markdown for PR Description

   • Create a markdown file in docs/ folder which only contains the description of the PR and for me later to copy paste:
     • Comprehensive PR description following the template at .github/PULL_REQUEST_TEMPLATE.md
     • If an issue number was provided, include it in the PR description using Closes #<issue-number>
     • If no issue number was provided, search for a relevant issue only if it is easy to identify; otherwise leave the issue field empty instead of blocking the workflow
     • Leave the file uncommitted; it should stay local even after the branch is pushed
     • Put the uploaded user-attachments URL and the demonstrated scenes in the ## Screenshots section between <!-- read-frog-pr-demo:start --> and <!-- read-frog-pr-demo:end -->, or write Not applicable — no user-visible change.