Writing plans execute with Claude as partner. Checkpoints formalize interaction points where human verification or decisions are needed.
**Core principle:** Claude assists with writing. Checkpoints are for verification and decisions about content direction.
**Visual formatting:** See @ui-brand.md for checkpoint box rendering, status symbols, and stage banners.
## checkpoint:human-verify (90% of checkpoints)
**When:** Claude completed a writing task, human confirms it captures their intent.
**Use for:** Argument accuracy, voice consistency, factual correctness, citation appropriateness, logical flow.
**Structure:**
```xml
[What Claude drafted]
[Numbered list of what to check — argument, tone, accuracy]
Type "approved" or describe issues
```
**Rendered output:**
```
════════════════════════════════════════
CHECKPOINT: human-verify
════════════════════════════════════════
Task {X} of {Y}: {Name}
What was written:
{description of drafted content}
How to verify:
1. {Check item 1}
2. {Check item 2}
3. {Check item 3}
Type "approved" or describe what to change.
════════════════════════════════════════
```
**Example:**
```xml
Draft introduction hookWrite opening paragraph establishing the problem~150 words, establishes tensionIntroduction opening paragraph (~150 words)
1. Captures the problem accurately
2. Tone matches your voice
3. Hook is compelling
Type "approved" or describe what to change
```
## checkpoint:decision (9% of checkpoints)
**When:** Human must make choice that affects content direction.
**Use for:** Argument framing, evidence selection, structure choices, emphasis decisions.
**Structure:**
```xml
[What's being decided][Why this matters for the paper][How to indicate choice]
```
**Rendered output:**
```
════════════════════════════════════════
CHECKPOINT: decision
════════════════════════════════════════
Task {X} of {Y}: {Name}
Decision needed:
{What is being decided}
Options:
[a] {Name} — {pros}; tradeoff: {cons}
[b] {Name} — {pros}; tradeoff: {cons}
Select: a or b
════════════════════════════════════════
```
**Example:**
```xml
Framing of methodology sectionTwo valid ways to present your method. Choice affects reader perception.Select: novel or extension
```
## checkpoint:human-action (1% - rare)
**When:** Action requires human input that Claude cannot provide.
**Use ONLY for:** Providing specific data points, recalling personal observations, supplying unpublished results, clarifying domain-specific terminology.
**Do NOT use for:** Writing tasks Claude can draft, formatting, citation formatting.
**Structure:**
```xml
[What is needed from the human]
[Specific description of what to provide]
[Format of expected input]
```
**Rendered output:**
```
════════════════════════════════════════
CHECKPOINT: human-action
════════════════════════════════════════
Task {X} of {Y}: {Name}
What is needed:
{Description of what the author must provide}
Provide: {expected format}
════════════════════════════════════════
```
**Example:**
```xml
Provide specific experimental result
I need the exact p-value and effect size from your analysis
to complete this sentence accurately.
Provide: p-value and effect size
```
## Typed Checkpoint XML Format
All checkpoints in plan files use this XML structure. The `type` attribute determines rendering and behavior. The `gate` attribute controls blocking behavior.
### Attributes
| Attribute | Values | Description |
|-----------|--------|-------------|
| `type` | `checkpoint:human-verify`, `checkpoint:decision`, `checkpoint:human-action` | Checkpoint category |
| `gate` | `blocking` (default), `non-blocking` | Whether execution pauses. Non-blocking checkpoints log for later review. |
### human-verify XML
```xml
[What Claude drafted]
[Numbered list of what to check]
Type "approved" or describe issues
```
### decision XML
```xml
[What's being decided][Why this matters]Select: {option-ids}
```
### human-action XML
```xml
[What is needed][Specific details]Provide: {expected format}
```
When Claude encounters `type="checkpoint:*"`:
1. **Stop immediately** - do not proceed to next task
2. **Display checkpoint** using the branded box format from @ui-brand.md:
```
════════════════════════════════════════
CHECKPOINT: {type}
════════════════════════════════════════
Task {X} of {Y}: {Name}
{Checkpoint-specific content}
{Resume signal instruction}
════════════════════════════════════════
```
3. **Wait for user response** - do not hallucinate completion
4. **Incorporate feedback** - adjust content as directed
5. **Resume execution** - continue only after confirmation
Different writing modes have different checkpoint patterns:
**Co-Author Mode:**
- Checkpoint after significant drafts
- Verify voice, accuracy, intent
- Fewer checkpoints (Claude has more latitude)
**Scaffold Mode:**
- Checkpoint after outline creation
- User fills in prose between checkpoints
- Checkpoint to review user's additions
**Reviewer Mode:**
- User writes first
- Claude's critique IS the checkpoint content
- User decides what feedback to incorporate
**DO:**
- Use checkpoints after substantive content (not after every paragraph)
- Be specific about what to verify
- Give clear options for decisions
- Make feedback incorporation easy
**DON'T:**
- Checkpoint every task (checkpoint fatigue)
- Make vague verification requests
- Force binary yes/no when nuance exists
- Checkpoint mechanical tasks (formatting, citations)
**Placement:**
- After completing a logical unit (subsection, argument)
- Before dependent content (need decision to continue)
- At voice-critical moments (abstract, intro hook)
- After significant revisions
**BAD: Too many checkpoints**
```xml
Write sentence 1Check sentence 1Write sentence 2Check sentence 2
```
Why bad: Disrupts flow. Combine into one checkpoint after a paragraph/section.
**BAD: Vague verification**
```xml
Methods sectionCheck if it's good
```
Why bad: "Good" is meaningless. Specify: accuracy, completeness, tone.
**GOOD: Substantive checkpoint**
```xml
Methods section draft (800 words)
1. Procedure accurately described?
2. Enough detail to replicate?
3. Analysis approach clear?
```
**Checkpoint priority:**
1. **checkpoint:human-verify** (90%) - Claude wrote, human confirms intent captured
2. **checkpoint:decision** (9%) - Human chooses content direction
3. **checkpoint:human-action** (1%) - Human provides information Claude can't know
**When NOT to use checkpoints:**
- Mechanical tasks (formatting, citations)
- Every paragraph (consolidate)
- When Claude can verify programmatically (word count, structure)
## Gate Integration
Checkpoints respect gate settings from `.planning/config.json`. This allows authors to control how much confirmation they want during execution.
### Gate Behavior
| Gate Key | Affects | When `false` |
|----------|---------|-------------|
| `gates.confirm_write` | `checkpoint:human-verify` during writing | Auto-approved — execution continues without pausing |
| `gates.confirm_review` | `checkpoint:human-verify` during review | Auto-approved |
| `gates.confirm_plan` | `checkpoint:human-verify` during planning | Auto-approved |
| `gates.confirm_outline` | `checkpoint:human-verify` during outlining | Auto-approved |
### Mode Override
When `mode: "yolo"`, all non-safety gates are treated as `false`. Checkpoints are auto-approved and execution proceeds without pausing.
### Always-Confirm Checkpoints
Some checkpoints are never skipped regardless of gate settings or mode:
- **`checkpoint:decision`** — Always pauses. Decisions require human input by definition.
- **`checkpoint:human-action`** — Always pauses. Agent cannot fabricate human input.
- **Safety-gated checkpoints** — When `safety.always_confirm_destructive` is `true`, any checkpoint before a destructive operation (deleting content, resetting progress) always pauses.
### Resolution Order
1. Is this a `checkpoint:decision` or `checkpoint:human-action`? → Always pause.
2. Is `safety.always_confirm_destructive` relevant? → Always pause.
3. Is `mode: "yolo"`? → Auto-approve.
4. Is the relevant gate `false`? → Auto-approve.
5. Otherwise → Pause and wait for user.