printserver/.opencode/skills/jujutsu/references/NEW_CHANGE.md

Starting a New Change

The jj workflow is: describe first, then code, then refine. The working copy is always a commit (@), so you're already in one when you start. The question is whether to reuse it or start fresh.

The opening sequence

# 1. Check what @ currently looks like
jj st

If @ is empty (no changes, no description set, or description is fine to discard):

• Reuse it. Just describe and start.

If @ has changes you want to keep (it's someone else's WIP, or work you haven't finished):

• Start fresh with jj new — this creates a new empty commit on top of @.

# 2. Describe before coding (only with -m; never editor-based)
jj desc -m "feat: Add user authentication to login endpoint"

# 3. Make changes — they snapshot to @ automatically on the next jj command
#    (no `jj add`, no `jj commit` needed)

# 4. Verify
jj st

Why describe first

Setting the message up front:

• Forces you to articulate the change as one logical unit before writing code (atomic commits)
• Means there's never a phase where @ says "(no description set)"
• Makes the change navigable in jj log while it's still being built

See references/COMMIT_MSG.md for the message format conventions.

After the change is done

Do NOT run jj new to "close" the change. In jj, the working copy is always a commit — there's no separate commit step. Leave @ as-is; the next task's step 1 (jj st → reuse or jj new) handles transition.

If refinement is needed (split, squash, absorb, abandon), see references/REFINE_COMMIT.md.

Anti-patterns

• ❌ jj commit — doesn't exist; the working copy is already a commit
• ❌ jj desc without -m — opens an editor; will hang in non-interactive agent environments
• ❌ Running jj new at the end of a task — leaves an empty @ for the next agent to clean up
• ❌ Starting code before describing — you'll forget to describe, or describe vaguely after the fact