jjj 0.4.1

Distributed project management and code review for Jujutsu
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178

---
title: Cookbook
description: Step-by-step recipes for common jjj and Jujutsu workflows.
---

# Cookbook

This guide provides practical "recipes" for common scenarios you'll encounter while using `jjj` with Jujutsu.

## 1. Handling Merge Conflicts
When two solutions modify the same lines, Jujutsu will create a conflict. Here's how to handle it in a `jjj` context.

1.  **Identify the conflict**: `jj status` will show conflicted files.
2.  **Fix the code**: Edit the files and resolve the conflicts using standard `jj` patterns.
3.  **Update the solution**: If the fix was for a solution like "Use connection pooling", your change is already attached.
4.  **Critique the collision**: If the conflict revealed a deeper architectural issue, add a **Critique** to one or both solutions.
    ```bash
    jjj critique new "connection pooling" "This approach conflicts with the caching solution's logic." --severity medium
    ```

## 2. Decomposing a Large Feature
Large features should be broken down into manageable problems.

1.  **Create the parent problem**:
    ```bash
    jjj problem new "Build new search infrastructure"
    ```
2.  **Decompose into sub-problems**:
    ```bash
    jjj problem new "Implement elasticsearch indexing" --parent "search infrastructure"
    jjj problem new "Create search API endpoint" --parent "search infrastructure"
    ```
3.  **Solve independently**: Team members can now propose solutions for "elasticsearch indexing" and "search API endpoint" in parallel.

## 3. Self-Review and Draft Critiques
You can use `jjj` to document your own thought process before presenting code for review.

1.  **Propose your solution**: `jjj solution new "Optimistic UI update" --problem "flaky network"`
2.  **Critique your own work**: Document edge cases you're worried about.
    ```bash
    jjj critique new "Optimistic UI" "What happens if the network is flaky?" --severity low
    ```
3.  **Address it**: Link your subsequent commits to addressing this critique.
4.  **Signal readiness**: When you request a review, the reviewer can see what you've already considered.

## 4. Switching Between Competing Solutions
If you're trying two different approaches for the same problem:

1.  **Propose both**:
    ```bash
    jjj solution new "Approach A: GraphQL" --problem "API redesign"
    jjj solution new "Approach B: REST" --problem "API redesign"
    ```
2.  **Toggle with `jjj resume`**:
    ```bash
    jjj solution resume "GraphQL"  # Switches your jj workspace to this solution's change
    # ... work on GraphQL approach ...
    jjj solution resume "REST"     # Switches your jj workspace to this solution's change
    ```
3.  **Withdraw the loser**: Once one approach is proven better, withdraw the other with a rationale.
    ```bash
    jjj solution withdraw "GraphQL" --rationale "GraphQL introduced too much complexity for this use case."
    ```

## 5. Preparing for Code Review

Before requesting a review, use jjj to document your thinking so reviewers have context:

1.  **Submit for review** to signal it's ready for criticism:
    ```bash
    jjj solution submit "Add search index"
    ```
2.  **Add self-critiques** for known concerns you haven't fully resolved:
    ```bash
    jjj critique new "Add search index" "Index rebuild time on large datasets unknown" --severity medium
    ```
3.  **Assign a reviewer** via a review critique:
    ```bash
    jjj critique new "Add search index" "Review requested" --reviewer @alice
    ```
4.  **Ask Alice to review**: she runs `jjj status` and sees your solution in the REVIEW queue. When she raises a critique, you'll see it in BLOCKED. When all critiques are resolved, she signs off with `jjj solution lgtm "Add search index"`, and you can approve.

## 6. Tracking a Milestone

When planning a release, use milestones to group problems and track progress:

1.  **Create the milestone**:
    ```bash
    jjj milestone new "v1.0 Launch" --date 2025-09-01
    ```
2.  **Tag problems to the milestone**:
    ```bash
    jjj problem edit "Search is slow" --milestone "v1.0"
    jjj problem edit "Auth missing" --milestone "v1.0"
    ```
3.  **Check progress**:
    ```bash
    jjj milestone roadmap
    ```
    This shows which problems are open, in-progress, and solved for each milestone, so you can assess scope and schedule risk.

## 7. Handling an Abandoned Solution

If a team member leaves or a solution goes stale, you can cleanly hand it off or close it:

1.  **Check the current state**:
    ```bash
    jjj solution show "Old approach"
    ```
2.  **Reassign to yourself** to pick it up:
    ```bash
    jjj solution assign "Old approach"
    jjj solution resume "Old approach"  # Switch your workspace to this change
    ```
3.  **Or withdraw it** with a rationale if the approach is no longer viable:
    ```bash
    jjj solution withdraw "Old approach" --rationale "Superseded by the new caching architecture."
    ```

## 8. Detecting File Overlaps Early

When multiple solutions modify the same files, merge conflicts are likely. Detect them before they happen:

```bash
# Check for overlapping files
jjj overlaps
```

If overlaps exist, you have several options:
1. **Coordinate**: Talk to the other solution's author and agree on an approach.
2. **Sequence**: Withdraw one solution, approve the other first, then rebase.
3. **Critique**: Raise a critique on one of the solutions noting the conflict risk.
   ```bash
   jjj critique new "connection pooling" "Overlaps with caching solution on src/db/pool.rs" --severity medium
   ```

The `jjj status` command also shows overlap warnings automatically.

## 9. Claiming Work Items

Use `jjj next --claim` to atomically find the highest-priority item and assign it to yourself:

```bash
# Grab the top item
jjj next --claim

# See what you claimed in JSON
jjj next --claim --json
```

This is useful in team settings where multiple people may be looking for work at the same time. The claim is idempotent — running it again on an already-assigned item is a no-op.

## 10. Reviewing Project Health

Use `jjj insights` to get aggregate statistics about your project:

```bash
jjj insights
```

This shows approval rates, average time to solve problems, critique resolution times, and top contributors. Use `--json` for structured output that can feed into dashboards or reports.

## 11. Using Search to Find Context

Use full-text or semantic search to find related work before starting something new:

```bash
# Full-text search across all entities
jjj search "authentication"

# Search finds related entities even without exact match
jjj search "login security"

# Filter by type
jjj search "token" --type solution
```

This helps avoid duplicating work and surfaces critiques from previous related efforts.