/iterating

name: iterating
description: Multi-conversation methodology for iterative stateful work with context accumulation. Use when users request work that spans multiple sessions (research, debugging, refactoring, feature development), need to build on past progress, explicitly mention iterative work, work logs, project knowledge, or cross-conversation learning.
metadata:
  version: 1.2.0

Iterating

Maintain context across multiple sessions by persisting state in Work Logs.

Environment Detection

Detect environment and load appropriate reference:

if [ "$CLAUDE_CODE_REMOTE" = "true" ]; then
  # Claude Code on the Web (CCotw) - writes to GitHub
  # Read: references/ccotw-environment.md
elif [ -n "$CLAUDE_CODE_REMOTE" ]; then
  # Claude Code CLI - writes to local filesystem
  # Read: references/codecli-environment.md
elif [ -x "$(command -v osascript)" ] && [ -d "/Applications/Claude.app" ]; then
  # Claude Desktop - may write to disk OR output for download
  # Read: references/desktop-environment.md
else
  # Claude.ai (web/chat/native app) - outputs for download
  # Read: references/chat-environment.md
fi

See environment-specific reference for persistence and retrieval details.

Checkpoint Pattern

The iterating skill enforces a checkpoint-and-save pattern to prevent work loss:

1. **Create/Update WorkLog** → Output for user → **STOP** 2. User saves WorkLog to project knowledge (survives conversation limits) 3. User says "continue" (same or new conversation) 4. **Make incremental progress** on ONE item → Update WorkLog → **STOP** 5. Repeat

This matters because separate conversations don't share context automatically: skipping the STOP step ("full waterfall") produces work the user hasn't seen or been able to redirect, and risks losing everything mid-task if the conversation ends before a checkpoint lands.

WorkLog Format

---
version: v1
status: in_progress
---

# [Project Name] Work Log

## v1 | YYYY-MM-DD HH:MM | Title

**Prev:** [previous context OR "Starting new work"]
**Now:** [current goal]

**Progress:** [X% complete OR milestone status]

**Files:**
- `path/to/file.ext` (Why this file matters)
  - L45-67: [What to examine/change here]
  - L123-145: [Another area, specific issue]

**Work:**
+: [additions with file:line]
~: [changes with file:line]
!: [fixes with file:line]

**Decisions:**
- [what]: [why] (vs [alternatives])

**Works:** [effective approaches]
**Fails:** [ineffective approaches, why]

**Blockers:** [None OR specific blocker with owner/ETA]

**Next:**
- [HIGH] [Critical action item]
- [MED] [Important but not urgent]
- [LOW] [Nice to have]

**Open:** [questions needing answers]

Core Workflow

**Starting new work:** 1. Detect environment 2. Create WorkLog v1 with task objective, decisions, file references, next steps 3. Persist using environment-specific method 4. **STOP - Present WorkLog to user**

• Explain what's planned
• Tell user to save WorkLog to project knowledge
• Wait for user to say "continue" before starting work

**Continuing work:** 1. Detect environment 2. Retrieve WorkLog using environment-specific method OR recognize pasted WorkLog 3. Parse latest version and status 4. Acknowledge: "From WorkLog vN, status: [status]. Progress: [X%]. Working on: [specific HIGH item]" 5. **Execute ONE HIGH priority item.** 6. Update WorkLog, increment version 7. Persist using environment-specific method 8. **STOP - Present updated WorkLog to user**

• Summarize what was completed
• Tell user to save updated WorkLog
• Wait for user to say "continue" before next item

**Recognizing pasted WorkLog:** If user pastes content with WorkLog frontmatter at conversation start: 1. Parse version and status from YAML 2. Acknowledge: "From WorkLog vN, status: [status]. Task: [objective]. Next: [HIGH item]" 3. Continue workflow from step 5 above

Version Management

• Simple incremental: v1 → v2 → v3
• Frontmatter: `version: vN` (required)
• Filename: `WorkLog vN.md` (optional)
• Multiple files: Use highest version number

Status States

• **in_progress**: Active work continuing
• **blocked**: Waiting on external dependency/decision
• **needs_review**: Ready for human inspection
• **completed**: Task finished

Priority System

**Next steps must be prioritized:**

• **[HIGH]**: Critical items blocking other work
• **[MED]**: Important but not urgent
• **[LOW]**: Nice-to-have improvements

Claude works on one HIGH priority item per iteration (see Core Workflow above) unless told otherwise — this keeps each checkpoint reviewable instead of bundling several changes into one WorkLog update.

File References

Use relative paths from project root with line ranges:

**Files:**
- `src/auth/oauth.ts` (OAuth implementation needs refactoring)
  - L45-67: Current token validation logic
  - L123-145: Refresh token handling (race condition on L134)

**Critical:** Use relative paths, NOT absolute `/home/claude/` paths (fresh compute each session).

Progress Tracking

**Always include progress indicators** (token/quota constraints may prevent completing full plan):

**Progress:** 60% complete

Or for longer projects:

**Progress:** Phase 2/3 | Auth ✅ | Payments 50% 🔄 | UI ⏳

What to Document

**Include:**

• Key decisions with rationale and alternatives
• Effective and ineffective approaches
• Important discoveries
• File references with line ranges
• Next steps with priorities
• Progress indicators
• Blockers with owner/ETA

**Don't include:**

• Minor code changes (use git)
• Obvious information
• Raw data dumps
• Implementation details (use code comments)

User Communication

**After creating WorkLog:**

• "Created WorkLog v1. Please save this to project knowledge."
• "Ready to start when you say 'continue'."

**After completing an item:**

• "Completed [item]. Updated WorkLog to vN."
• "Please save updated WorkLog to project knowledge."
• "Ready for next item when you say