name	jj-atomic-workflow
description	Guide for atomic change workflow with jj and single-phrase test

jj Atomic Workflow

See core-commands skill for prohibited commands and temp file pattern.

Prerequisites

Before using this skill:

1. core-commands skill must be loaded
2. jj-github-integration must have been run
3. An issue number MUST exist (check .usr file or ask user)

Atomic Change Workflow

1. Check working copy: jj status

   • Empty: proceed directly
   • Not empty: run jj new

2. Verify issue number: Ensure issue number exists (required for commit message)

3. Make changes (edit files)

4. Verify atomicity: Ask "Can this change be summed up in a single short phrase?"

   • NO → Split into independent changes
   • YES → Proceed

5. Review: jj diff --git and jj status

6. After approval, describe:

   • Simple message: jj describe -m "line1" -m "line2"
   • Complex message: See core-commands skill for temp file pattern

Important Notes

• jj new creates a new change on top of the current one
• Changes are automatically tracked; no separate staging area
• The working copy is always the newest change
• Describe commits only after review/approval
• Never use jj describe before changes are ready
• Skip jj new if working copy is already empty with no description
• Always prompt the user before pushing to remote
• Never push without explicit user confirmation
• .usr file provides username for bookmark naming
• Only use plain jj new without any arguments
• Never use jj edit - it moves working copy to existing changes
• Use jj diff --git for clear, parseable output

What is an Atomic Change?

One micro task = one change. Period.

Atomic:

• Add validation to a single field
• Fix a specific bug
• Update one configuration file
• Add one test case

NOT Atomic:

• Implement entire feature + tests + docs in one change
• Fix bug + refactor related code + update dependencies

Key principle: If you can't describe it in one sentence, it's probably not atomic.

Single-Phrase Test

Before any edit, ask: "Can this be summed up in one short phrase?"

Atomic examples:

• "Add email validation to signup form"
• "Fix null pointer in user service"
• "Update database connection timeout"

Not atomic:

• "Add authentication and update tests and fix lint" → Split into 3 commits
• "Refactor API layer and add new endpoints" → Split into refactor + feature commits

Micro-Commit Guidelines

A micro-commit is the smallest unit of meaningful change:

• Passes the single-phrase test - Can be described in one short phrase
• Reviewable in under 30 seconds - Quick to understand and verify
• Single purpose/impact - Does one thing well
• Multiple files OK - If all changes serve the same single purpose

Remember: Smaller is better. When in doubt, split it out.

Common Commands

Action	Command
Create new change	jj new
View status	jj status
View diff	jj diff --git
Describe change (simple)	jj describe -m "line1" -m "line2"
Describe change (complex)	See core-commands skill
Set bookmark	jj bookmark set <name>
Push bookmark	jj git push --bookmark <name> (ask user first)

Note: Navigation commands (jj prev, jj next) are prohibited. Always ask the user when you need to move to another working copy.