shipkit-work-memory

Purpose: Capture structured session progress — milestones, blockers, decisions, and resume state — by inferring from conversation and git. User confirms, Claude does the work.

Note: Claude Code's auto-memory (v2.1.59+) automatically saves basic session context. This skill is for structured progress tracking that auto-memory doesn't capture: explicit milestones, decision rationale, blocker status, and handoff state for session continuity.

Output: .shipkit/progress.json — A timeline graph artifact ideal for session history visualization.

---

When to Invoke

User triggers:

• "End session"
• "Log progress"
• "Save checkpoint"
• "What did we do?"
• "Save session"

Suggested after:

• Long implementation sessions
• Before context gets full
• Before switching tasks
• End of work session

---

Prerequisites

None required - Can start fresh.

Uses if available:

• .shipkit/progress.json - Merge with existing sessions
• Git - For modified files detection

---

JSON Schema (Quick Reference)

This skill outputs .shipkit/progress.json using the Shipkit JSON Artifact Convention.

{
  "$schema": "shipkit-artifact",
  "type": "work-memory",
  "version": "1.0",
  "lastUpdated": "2025-01-15T10:00:00Z",
  "source": "shipkit-work-memory",
  "summary": { "totalSessions", "currentPhase", "lastSessionDate", "activeWorkstream", "blockers", "momentum" },
  "sessions": [{ "id", "date", "duration", "workstream", "phase", "accomplished", "filesModified", "decisions", "gotchas", "blockers", "nextSteps", "status" }],
  "workstreams": [{ "id", "name", "status", "startDate", "sessions", "completionEstimate" }],
  "resumePoint": { "lastSession", "immediateNextStep", "context", "openFiles", "relatedArtifacts" },
  "timeline": [{ "date", "event", "type" }]
}

Full schema and field reference: See references/output-schema.md

Realistic example: See references/example.json

Completion Tracking

Create tasks:

• TaskCreate: "Analyze session (scan conversation + git status)"
• TaskCreate: "Present summary for user confirmation"
• TaskCreate: "Write progress.json (all 10 sub-fields)"
• TaskCreate: "Auto-archive sessions older than 48 hours"

TaskUpdate each task to in_progress when starting it, completed when done.

The progress.json write is NOT done until summary fields are recalculated and workstreams updated. The auto-archive step runs AFTER the main write — do not skip it.

---

Process

Step 1: Analyze Session (Inference)

Scan conversation for tool calls:

Look for Edit/Write/Read calls → files touched
Most recent Edit/Write → likely resume point

Extract from discussion:

• What was being built/fixed → current task
• Problems/errors encountered → gotchas
• "Next we should..." or "TODO" mentions → next steps
• Choices made with rationale → decisions

Run git status:

git status --porcelain

→ Modified/added files = files changed this session

---

Step 2: Generate Summary

Build summary from inference:

Task: [Inferred from conversation topic]
Status: [in-progress | complete | blocked]
Last file: [Most recent Edit/Write target]
Modified: [Count from git status]
Next: [Extracted from "next" mentions or inferred]
Gotchas: [Errors hit, surprises discovered]
Decisions: [Choices made with rationale]

---

Step 3: Present for Confirmation

Show user what was captured:

Session Summary (inferred)

Task: Auth implementation
Status: in-progress
Last file: src/api/auth/login.ts
Modified: 4 files
Next: Add JWT generation
Gotcha: Prisma must import from @/lib/prisma

Completed:
- User schema added
- Password hashing utils
- Login endpoint started

Save to progress.json? [y/n]

If user says no or wants changes:

• Ask what to adjust
• Update and re-confirm

If user says yes:

• Proceed to Step 4

---

Step 4: Update progress.json

Artifact strategy: append — Adds new entries to the existing file, preserving previous content. When the file exceeds approximately 500 lines or 50 entries, archive the oldest entries to .shipkit/archive/progress.{ISO-date}.json and continue appending to the trimmed file.

Write strategy:

1. Read existing .shipkit/progress.json (if exists)
2. Parse existing JSON (or initialize empty structure with artifact envelope)
3. Generate a new session ID by incrementing the highest existing session ID
4. Append new session object to sessions array
5. Update or create workstreams entry for the current workstream
6. OVERWRITE resumePoint with current session's resume context
7. Append new timeline events (milestones, decisions from this session)
8. Recalculate summary fields (totalSessions, lastSessionDate, blockers, momentum, etc.)
9. Set lastUpdated to current ISO datetime
10. Write the complete JSON to .shipkit/progress.json

Initialization (first session):

When no progress.json exists, create the full structure:

{
  "$schema": "shipkit-artifact",
  "type": "work-memory",
  "version": "1.0",
  "lastUpdated": "<current ISO datetime>",
  "source": "shipkit-work-memory",
  "summary": {
    "totalSessions": 1,
    "currentPhase": "<inferred>",
    "lastSessionDate": "<today>",
    "activeWorkstream": "<inferred>",
    "blockers": 0,
    "momentum": "high"
  },
  "sessions": [ "<new session object>" ],
  "workstreams": [ "<new workstream object>" ],
  "resumePoint": { "<current resume state>" },
  "timeline": [ "<initial events>" ]
}

Subsequent sessions:

• Read and parse existing JSON
• Append to sessions, update workstreams, overwrite resumePoint
• Append to timeline
• Recalculate summary

---

Step 5: Confirm Save

Progress saved to .shipkit/progress.json

Resume Point: src/api/auth/login.ts
Next: Add JWT generation

To resume next session, I'll read progress.json and pick up where we left off.

---

Step 6: Auto-Archive (48-Hour Window)

After saving, archive old session entries:

1. Find session entries older than 48 hours
2. Move them to .shipkit/archives/progress-archive-YYYY-MM.json (same artifact envelope format)
3. Remove archived sessions from progress.json to keep it focused on recent work
4. Update summary.totalSessions to reflect only active sessions
5. Keep timeline entries intact (they are lightweight and useful for visualization)

Archive file structure:

{
  "$schema": "shipkit-artifact",
  "type": "work-memory-archive",
  "version": "1.0",
  "lastUpdated": "<archive date>",
  "source": "shipkit-work-memory",
  "summary": {
    "totalSessions": 3,
    "dateRange": "2025-01-01 to 2025-01-13"
  },
  "sessions": [ "<archived session objects>" ]
}

Notify:

Archived 3 old sessions to archives/progress-archive-2025-01.json

---

Inference Patterns

Detecting Current Task

Look for patterns in conversation:

• "Let's work on [X]" → task is X
• "Implementing [X]" → task is X
• Most discussed topic → likely the task
• Spec/plan being followed → task from spec name

Detecting Resume Point

Priority order:

1. Last Edit tool call → that file
2. Last Write tool call → that file
3. Most discussed file → likely resume point
4. Git: most recently modified → fallback

Detecting Next Steps

Look for:

• "Next we need to..."
• "TODO: ..."
• "After this, we should..."
• "Still need to..."
• Incomplete items from plan

Detecting Gotchas

Look for:

• Errors encountered and resolved
• "Turns out..." or "Actually..."
• Surprising behavior discovered
• Workarounds implemented
• Import path corrections

Detecting Decisions

Look for:

• "Let's use X instead of Y"
• "Going with X because..."
• Trade-off discussions
• Architecture choices

Detecting Workstream

Look for:

• Recurring topic across multiple sessions
• Feature name or epic name mentioned
• Related files being modified together
• If unclear, use the primary task name as the workstream name

---

Session Start Integration

When session starts and progress.json exists:

Claude (via master or session hook) should:

1. Read and parse .shipkit/progress.json
2. Extract resumePoint object
3. Surface it to user:

Resume Point from last session:

Task: Auth implementation (workstream: Authentication flow)
Last file: src/middleware/auth.ts
Next: Add rate limiting to auth endpoints
Context: JWT auth is working, need to harden before deployment

Continue from here?

---

What Makes This Effective

Claude does the work:

• Infers from conversation (no user questions)
• Parses git status (no manual file listing)
• Extracts gotchas from errors hit
• Finds next steps from discussion

User just confirms:

• Review summary
• Say yes or adjust
• Done

Next session is easy:

• resumePoint in progress.json has everything needed
• Claude reads it, surfaces context
• Seamless continuation

Dashboard-ready data:

• summary object powers dashboard cards at a glance
• timeline array enables visual session history graphs
• workstreams track feature-level progress across sessions

---

Context Files This Skill Reads

| File | Purpose | |------|---------| | .shipkit/progress.json | Existing progress (if any) | | Conversation history | Tool calls, discussion | | Git status | Modified files |

---

Context Files This Skill Writes

| File | Strategy | Description | |------|----------|-------------| | .shipkit/progress.json | Overwrite resumePoint, append to sessions/timeline, recalculate summary | Primary work memory artifact | | .shipkit/archives/progress-archive-YYYY-MM.json | Create/append | Archived sessions older than 48 hours |

---

When This Skill Integrates with Others

Before This Skill

Any development work:

• Implementation sessions
• Debugging sessions
• Feature building

After This Skill

• End session with clear state
• Next session reads resumePoint from progress.json
• Seamless continuation

---

<!-- SECTION:after-completion -->

After Completion

Guardrails Check: Before moving to next task, verify:

1. Persistence - Has important context been saved to .shipkit/?
2. Prerequisites - Does the next action need a spec or plan first?
3. Session length - Long session? Consider /shipkit-work-memory for continuity.

Natural capabilities (no skill needed): Implementation, debugging, testing, refactoring, code documentation.

Suggest skill when: User needs to make decisions, create persistence, or check project status.

<!-- /SECTION:after-completion -->

---

<!-- SECTION:success-criteria -->

Success Criteria

• [ ] Task inferred from conversation
• [ ] Last file detected from tool calls
• [ ] Modified files from git status
• [ ] Next steps extracted from discussion
• [ ] Gotchas captured from errors/surprises
• [ ] Decisions captured with rationale
• [ ] progress.json written with valid artifact envelope ($schema, type, version, lastUpdated, source, summary)
• [ ] Session entry appended to sessions array
• [ ] resumePoint overwritten with current state
• [ ] timeline updated with session events
• [ ] workstreams updated or created
• [ ] summary recalculated
• [ ] User only needed to confirm

<!-- /SECTION:success-criteria -->