oaustegard/iterating

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:

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

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:

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 doing ANY 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 (not all of them!)
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 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