From ab99fc88d261883aec17be7e12fdae6ae960b8e7 Mon Sep 17 00:00:00 2001
From: sloane <git@sloanelybutsurely.com>
Date: Wed, 5 Nov 2025 07:37:32 -0500
Subject: [PATCH] docs: add simplify-parents command and workflow guidelines

Add jj simplify-parents command documentation to the Essential Commands section, explaining how to remove redundant parents from changes.

Add critical workflow guidelines for ending with empty changes after multi-change operations, including detailed examples for splitting changes, creating parallel changes, and organizing history. This ensures users maintain a clean working copy following jujutsu's design philosophy.
---
 SKILL.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/SKILL.md b/SKILL.md
index f17368a..b67e822 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -54,6 +54,8 @@ jj new                       # Create new commit on top of current
 jj new <base>                # Create new commit on specified base
 jj edit <commit>             # Edit an existing commit
 jj abandon <commit>          # Abandon a commit (preserve children)
+jj simplify-parents          # Remove redundant parents from current change
+jj simplify-parents -r <commit>  # Remove redundant parents from specific change
 ```
 
 ### Moving Changes
@@ -372,5 +374,58 @@ When helping users with jujutsu:
 6. **Reference supplemental docs** - Point to revsets.md, filesets.md, templating.md for details
 7. **Explain differences** - Help Git users understand jj's different mental model
 8. **Encourage experimentation** - Everything is recoverable via operation log
+9. **Always end with new empty change** - After performing operations that create or modify changes, create a new empty working copy change as the final step
+
+### Critical Workflow Rule: End with Empty Change
+
+**IMPORTANT**: When performing operations that create or modify changes, ALWAYS end by creating a new empty change. This ensures the working copy is ready for new work.
+
+#### When to Create New Empty Change
+- After splitting a change into multiple commits
+- After creating multiple parallel changes
+- After rebasing or moving changes
+- After any operation that leaves you on a non-empty change
+- When organizing or restructuring commit history
+
+#### How to Create New Empty Change
+```bash
+# After any multi-change operation, end with:
+jj new                       # Create new empty change on current commit
+# Or for parallel changes:
+jj new <change1> <change2>   # Create new empty merge commit above multiple changes
+jj simplify-parents          # Simplify if merge has redundant parents
+```
+
+**Note on Redundant Parents**: When creating merge commits with `jj new <change1> <change2>`, if one change is an ancestor of another, use `jj simplify-parents` to remove redundant parents and create a cleaner history.
+
+#### Examples
+
+**Splitting changes:**
+```bash
+# User asks: "Split my current change into tests and implementation"
+jj split                     # Split into two changes
+jj new                       # Create new empty change above both
+```
+
+**Creating parallel changes:**
+```bash
+# User asks: "Create separate changes for feature A and feature B"
+jj new -r base_commit
+jj describe -m "feat: add feature A"
+# Make changes for A
+jj new -r base_commit
+jj describe -m "feat: add feature B"
+# Make changes for B
+jj new <changeA> <changeB>   # Create new empty merge change above both features
+jj simplify-parents          # Remove redundant parents if any
+```
+
+**After organizing history:**
+```bash
+# After rebasing, squashing, or other history operations
+jj new                       # Always end with fresh empty change
+```
+
+This ensures users always have a clean working copy ready for new work, following jujutsu's design philosophy of treating the working copy as a first-class commit.
 
 Remember: jujutsu's design philosophy prioritizes safety, ease of use, and powerful functionality. Help users leverage these strengths.