| name | checkout |
| description | Start work on a new issue or feature by creating a jj change on the up-to-date default branch with an optional named bookmark. |
Checkout: Start a New Change for an Issue
Arguments
$ARGUMENTS
Pre-computed Context
Working copy: !`jj log -r @ --no-graph -T 'change_id.shortest() ++ " " ++ if(description, description.first_line(), "(no description)")' 2>/dev/null`
Working copy empty: !`jj diff --stat 2>/dev/null | head -1`
Log: !`jj log -r 'ancestors(@, 5)' --no-graph -T 'change_id.shortest() ++ " " ++ bookmarks ++ " " ++ if(description, description.first_line(), "(empty)") ++ "\n"' 2>/dev/null`
Constraints
- Do not abandon changes or discard work without user confirmation.
Instructions
1. Parse Arguments
Determine what $ARGUMENTS contains:
| Pattern | Action |
|---|
#123 or issue URL | Fetch issue title, derive bookmark name |
Bookmark name (e.g., feat/dark-mode) | Use directly |
| Empty | Ask what to work on |
2. Derive Bookmark Name (from issue)
If $ARGUMENTS is an issue reference:
- Fetch:
gh issue view <number> --json number,title,labels
- Derive bookmark name from issue metadata:
- Check labels for conventional commit type hints (bug/fix labels →
fix/, feature labels → feat/, chore/maintenance labels → chore/, default → feat/)
- Format:
<prefix><number>-<kebab-case-title> (e.g., feat/123-add-dark-mode)
- Truncate to 60 characters max
3. Handle Existing Work
Check pre-computed context for the current working copy state.
In jj, the working copy @ is always a change being edited. Before starting new work, assess:
| Situation | Action |
|---|
| Working copy is empty (no diff) | Safe to proceed — jj new will leave an empty change behind (auto-abandoned) |
| Working copy has changes with a description | Suggest jj commit first to finalize, then proceed |
| Working copy has changes without a description | Suggest jj commit -m "..." or jj describe -m "..." first |
Conflicts exist (jj st shows conflicts) | Inform user and wait for guidance |
Do not silently abandon or squash work.
4. Create the Change
jj git fetch — ensure we have latest from remote- Create a new change on top of main:
jj new main -m "<issue title or description>"
- Create a named bookmark on the new change (for later pushing/PR):
jj bookmark create <bookmark-name> -r @
5. Report and Continue
Report the change ID, bookmark name, and parent (e.g., Created change xyz on bookmark feat/123-add-dark-mode from main), then immediately mark this task complete and execute the next task in the workflow.
