jj-todo-workflow

What this skill does

# JJ TODO Workflow

The core idea is to use a DAG of empty revisions as TODO markers, representing tasks to be done,
and then come back later to edit these revisions to actually do the tasks. This enables structured development with clear milestones.
Revision descriptions (i.e. commit messages) act as specifications for what to implement.
JJ makes it easy to create such a structure, and then to fill each revision afterwards.

**For more information on JJ basics, see the `working-with-jj` skill. We reuse scripts from that skill here.**

This skill talks about two roles: **Planners** (who lay out the empty revisions and their specs) and **Workers** (who implement them).
Depending on the situation, you may be acting as just Planner, just Worker, or both.
It is better to have a good idea of the whole process, but section titles make it explicit which role is most concerned by each section.

## Quick Start (Planners & Workers)

Here's a complete cycle from planning to completion (**full paths to helper scripts not written**):

```bash
# 1. Plan: Create a simple TODO chain
jj-todo-create @ "Add user validation" "Check email format and password strength"
# Created: abc123 (stays on current @)

jj-todo-create abc123 "Add validation tests" "Test valid/invalid emails and passwords"
# Created: def456 (@ still hasn't moved)

# 2. Start working on first TODO
jj edit abc123
jj-flag-update @ wip   # Now [task:wip]

# ... implement validation ...

# 3. Verify ALL acceptance criteria met
make test  # Or equivalent in your project

# 4. Ask to move to next task
jj-todo-next
### ... review current specs (to ensure compliance) and next possible TODOs ...

# 5. Once we're sure everything is properly done, move to next TODO
jj-todo-next --mark-as done def456   # Marks abc123 as [task:done], starts def456 as [task:wip]
```

**That's it!** Empty commits as specs, edit to work on them, `jj-todo-next --mark-as done <next-step>` when FULLY complete.

## Status Flags (Planners & Workers)

We use description prefixes to track status at a glance. The `[task:*]` namespace makes them greppable and avoids conflicts with other conventions.

Here are the ONLY allowed status flags:

| Flag              | Meaning                                                                              |
| ----------------- | ------------------------------------------------------------------------------------ |
| `[task:draft]`    | Placeholder created, needs full specification                                        |
| `[task:todo]`     | Not started, empty revision with complete specs                                      |
| `[task:wip]`      | Work in progress                                                                     |
| `[task:blocked]`  | Waiting on external dependency                                                       |
| `[task:standby]`  | Awaits some decision (broken and hard to fix, usefulness called into question, etc.) |
| `[task:untested]` | Implementation done, but not tested enough to be validated                           |
| `[task:review]`   | Needs review (tricky code, design choice)                                            |
| `[task:done]`     | Complete, all acceptance criteria met                                                |

This order is **indicative**: not every task has to go through all these steps, and not necessarily in the order above.

NOTE: In previous versions of this Skill, `standby` was called "broken". It got renamed to make this status more broadly applicable.

### When to Use `draft` vs `todo` (Planners)

**Use `[task:draft]`** when:

- Creating placeholder tasks to establish the DAG structure
- The task title/concept is clear but details aren't worked out yet
- You want to defer writing full acceptance criteria
- Planning at a high level before diving into specifics

**Use `[task:todo]`** when:

- The task has complete specifications (context, requirements, acceptance criteria)
- A Worker could pick it up and implement it without clarification
- All dependencies and approach are clearly documented

### Updating Flags (Workers & Planners)

```bash
jj-flag-update @ draft     # Mark as needing specification (Planners)
jj-flag-update @ todo      # Mark as ready to work on (Planners)
jj-flag-update @ wip       # Start work (Workers)
jj-flag-update @ untested  # Implementation done, tests missing (Workers)
jj-flag-update @ done      # Complete (Workers)
```

### Finding Flagged Revisions (Planners & Workers)

```bash
jj-find-flagged                     # All tasks
jj-find-flagged draft               # Only [task:draft]
jj-find-flagged todo                # Only [task:todo]
jj-find-flagged wip                 # Only [task:wip]
jj-find-flagged done                # Only [task:done]

# Manual - all tasks
jj log -r 'description(substring:"[task:")'

# Incomplete tasks only (excludes done)
jj log -r 'description(substring:"[task:") & ~description(substring:"[task:done]")'
```

## Basic Workflow (Planners & Workers)

### 1. Plan: Create TODO Chain (Planners)

```bash
# Create linear chain of tasks
jj-todo-create @ "Task 1: Setup data model" "...details..."
jj-todo-create <T1-id> "Task 2: Implement core logic" "..."
jj-todo-create <T2-id> "Task 3: Add API endpoints" "..."
jj-todo-create <T3-id> "Task 4: Write tests" "..."
```

### 2. Work: Edit Each TODO (Workers)

```bash
# Read the specs
jj-show-desc <task-id>    # BEWARE: Script from the `working-with-jj` skill
 
# Start working on it
jj edit <task-id>
jj-flag-update @ wip

# ... implement ...

# Mark progress
jj-flag-update @ untested
```

### 3. Complete and Move to Next (Workers)

`jj-todo-next` script is there to smooth out the "transition to next task" process.

#### Without args

- Print out current task's description so you can review and make sure everything is implemented as planned
- Print out next possible task(s)

```bash
# Review current specs and see what's next
jj-todo-next
# Shows:
#   📋 Current task specs for review:
#   ─────────────────────
#   ...
#   ─────────────────────
#
#   Current task status: [task:wip]
#   Mark as [task:done] only if FULLY COMPLIANT with specs above.
#
#   ✅ Available next tasks:
#     abc123  [task:todo] Feature B
#     def456  [task:todo] Feature C
#
#   ⚠️ Child tasks with unmet dependencies:
#     xyz789  [task:todo] Integration
#             Blocked by: abc123
```

#### With args

- Update the flag of current task
- Move (`jj edit`) to the next task
- Update new task's flag to `[task:wip]`

```bash
# Actually mark current done and start editing next:
jj-todo-next --mark-as done abc123
# Does the `jj edit abc123` and shows its description
```

## Planning Parallel Tasks (DAG) (Planners)

Create branches that can be worked independently. Example:

```bash
# Linear foundation
jj-todo-create @ "Task 1: Core infrastructure"
jj-todo-create <T1-id> "Task 2: Base components"

# Parallel branches from Task 2
jj-parallel-todos <T2-id> "Widget A" "Widget B" "Widget C"

# ... edit their descriptions to add more details ...

# Merge point (all three parents must complete first)
jj new --no-edit <A-id> <B-id> <C-id> -m "[task:todo] Integration of widgets\n\n..."
```

**Result:**

```
          Integration
       /      |        \
   Widget A  Widget B  Widget C
       \      |        /
          Task 2: Base
              |
          Task 1: Core
```

No rebasing needed - parents specified directly!

## Writing Good TODO Descriptions (Planners)

### Structure

```
Short title (< 50 chars)

## Context
Why this task exists, what problem it solves.

## Requirements
- Specific requirement 1
- Specific requirement 2

## Implementation notes
Any hints, constraints, or approaches to consider.

## Acceptance criteria
How to know when this is FULLY DONE (not just "good enough"):
- Criterion 1
- Criterion 2
```

**Important:** Acceptance criteria define when you can mark as `[task:done]`. Be specific and testable.

**The description should overall be as self-sufficient as