---
name: prepare-pr
description: Prepare all work before creating a pull request, optionally for the issue provided as argument
metadata:
  author: read-frog
  version: "1.0.0"
---

# 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:

     ```markdown
     ---
     "@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.`

## Commit Convention

Follow these commit types:

- `feat`: New features
- `fix`: Bug fixes
- `docs`: Documentation changes
- `style`: Code style changes
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
- `build`: Build system changes
- `ci`: CI/CD changes
- `perf`: Performance improvements
- `revert`: Reverting previous commits
- `i18n`: Internationalization changes
- `ai`: AI-related features

Format: `type(scope): description`

## References

- PR Template: `.github/PULL_REQUEST_TEMPLATE.md`
- Project Guidelines: `CLAUDE.md`