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.
Critical: Checkpoint Pattern
The iterating skill enforces a checkpoint-and-save pattern to prevent work loss:
- Create/Update WorkLog → Output for user → STOP
- User saves WorkLog to project knowledge (survives conversation limits)
- User says "continue" (same or new conversation)
- Make incremental progress on ONE item → Update WorkLog → STOP
- Repeat
Why this matters:
- Prevents token exhaustion mid-task
- Survives 5-hour conversation limits
- Allows user to review progress before continuing
- Creates natural save points
- Enables work across multiple conversations
NEVER skip the STOP step - going "full waterfall" defeats the entire purpose of iterating.
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:
- Detect environment
- Create WorkLog v1 with task objective, decisions, file references, next steps
- Persist using environment-specific method
- STOP - Present WorkLog to user
- Explain what's planned
- Tell user to save WorkLog to project knowledge
- Wait for user to say "continue" before doing ANY work
Continuing work:
- Detect environment
- Retrieve WorkLog using environment-specific method OR recognize pasted WorkLog
- Parse latest version and status
- Acknowledge: "From WorkLog vN, status: [status]. Progress: [X%]. Working on: [specific HIGH item]"
- Execute ONE HIGH priority item (not all of them!)
- Update WorkLog, increment version
- Persist using environment-specific method
- 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:
- Parse version and status from YAML
- Acknowledge: "From WorkLog vN, status: [status]. Task: [objective]. Next: [HIGH item]"
- 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 unless told otherwise.
Incremental progress pattern:
- Pick ONE HIGH item from WorkLog
- Complete that specific item
- Update WorkLog with progress
- STOP for user to save
- User says "continue" → Pick next HIGH item
- Repeat
This prevents token exhaustion and enables natural checkpoints.
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 'continue'."
When continuing:
- "From WorkLog vN, status: [status]. Progress: [X%]."
- "Working on: [specific HIGH item]"
Status changes:
- "Updated WorkLog status to [new_status]: [reason]"
- "Please save updated WorkLog."
NEVER say: "Now I'll continue with the next item..." - Always STOP and wait for user.
Advanced Patterns
Read references/advanced-patterns.md when:
- Working on projects spanning 5+ sessions
- User mentions "debugging strategy", "hypothesis tracking", or "decision evolution"
- Managing multiple concurrent workstreams
- User asks about long-running project patterns
- Blocked on complex issues requiring systematic approach
Otherwise skip - basic workflow above is sufficient for most cases.
Reference Documentation
- references/chat-environment.md - Claude.ai (web/chat/native app)
- references/desktop-environment.md - Claude Desktop
- references/codecli-environment.md - Claude Code CLI
- references/ccotw-environment.md - Claude Code on the Web