Document Work Workflow

When to use: After completing significant features, at end of work sessions, when new patterns emerge, before context handoffs

When to Use

Trigger	Action
Completed major feature	Document patterns + decision
End of work session	Update state.md
New pattern identified	Add to patterns.md
Architecture decision made	Create memory file
Before vacation/handoff	Full documentation pass

Prerequisites

Git repository with recent commits to analyze
.claude/ directory exists in project
Understanding of what work was done (or access to git history)

Process Overview

1. Analyze Recent Changes
   └── git log, git diff, file changes
         ↓
2. Identify Documentation Needs
   └── Patterns? Decisions? State updates?
         ↓
3. Generate Documentation
   └── patterns.md, memory/, state.md, project.md
         ↓
4. Verify Completeness
   └── Checklist validation

Phase 1: Analyze Recent Work

AI Will Review

Recent git commits (last N commits or since date)
Files changed and their purpose
Code patterns introduced or refined
Decisions made during implementation
Current work status and next steps

Discovery Commands

# View recent commits
git log --oneline -20

# View commits since a date
git log --since="2025-01-01" --oneline

# View files changed in recent commits
git log --oneline --name-only -10

# View detailed diff of recent work
git diff HEAD~5..HEAD --stat

Questions AI May Ask

What date range or commits should I analyze?
Are there specific decisions you want documented?
Any patterns you noticed that should be captured?
Who might need context from this work?
Is there work in progress that should be captured in state.md?

Phase 2: Identify Documentation Needs

Pattern Detection Criteria

Document as a pattern when:

Same code structure used 3+ times
New API contract established
Error handling approach standardized
Testing approach that should be reused
Configuration pattern worth preserving
Component structure that became a convention

Decision Documentation Criteria

Create a memory file when:

Chose between multiple valid approaches
Made tradeoff that affects future work
Established precedent for the codebase
Something future developers should understand
Rejected an approach for specific reasons
External constraints influenced the decision

State Update Criteria

Update state.md when:

Work in progress that spans sessions
Blockers encountered
Next steps identified
Dependencies on external factors
Context needed for next session

Project Update Criteria

Update project.md when:

New technology added to stack
Architecture significantly changed
New integration added
Major dependency introduced

Phase 3: Generate Documentation

Output File Formats

patterns.md Entry

## [Pattern Name]

**When to use**: [Context where this pattern applies]

**Example**:

```[language]
// Pattern implementation code

Why: [Rationale for this approach]

See also: [Related patterns or files]


#### memory/YYYY-MM-DD-topic.md

```markdown
# [Decision Title]

**Date**: YYYY-MM-DD
**Status**: Decided | In Progress | Deprecated
**Affects**: [List of affected areas/files]

## Context

[What was the situation? What problem were we solving?]

## Options Considered

### Option A: [Name]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]

### Option B: [Name]
- **Pros**: [Benefits]
- **Cons**: [Drawbacks]

## Decision

[What was chosen and why]

## Consequences

- [What this means going forward]
- [Any technical debt incurred]
- [Future work enabled or blocked]

## References

- [Related PRs, issues, or documentation]

state.md

# Current Work Status

**Last Updated**: YYYY-MM-DD
**Author**: [Name or AI]

## In Progress

- [ ] [Task description with context]
- [ ] [Another task]

## Recently Completed

- [x] [Completed task] (YYYY-MM-DD)
- [x] [Another completed task] (YYYY-MM-DD)

## Blockers

- **[Blocker name]**: [Description and what's needed to unblock]

## Next Steps

1. [Immediate next action]
2. [Following action]
3. [Future consideration]

## Context for Next Session

[Key context to preserve - what state is the code in, what was the last thing worked on, any gotchas to be aware of]

## Notes

[Any other relevant information]

project.md Updates

When updating project.md, add to relevant sections:

## Recent Changes

### [Date] - [Change Category]
- Added [technology/pattern/integration]
- Reason: [Why this was added]
- Impact: [What this affects]

Phase 4: Verification

Documentation Checklist

All significant patterns documented in patterns.md
Key decisions have memory files with full context
state.md reflects current work status (if applicable)
project.md updated if architecture changed
Documentation is searchable/findable
No sensitive information in docs (credentials, PII)
Examples are accurate and runnable
Cross-references between related docs

Quality Checks

Pattern examples compile/run
Decision rationale is clear to someone unfamiliar
State.md has enough context for cold start
Memory files are dated correctly
No duplicate patterns documented

Usage Examples

Example 1: End of Feature Session

User Request:

@.claude/skills/document-work/SKILL.md

Document the work from today's session on the authentication feature.
We made some decisions about JWT vs sessions and established a new
error handling pattern.

AI Will:

Review git commits from today
Identify the JWT vs sessions decision → Create memory file
Extract error handling pattern → Add to patterns.md
Update state.md with current progress

Output:

.claude/memory/2025-01-14-auth-token-strategy.md
Updated CLAUDE.md with error handling section
Updated CLAUDE.md with auth feature progress

Example 2: Pattern Discovery

User Request:

@.claude/skills/document-work/SKILL.md

I noticed we've been using the same API response format across
multiple endpoints. Let's document this as a pattern.

AI Will:

Search codebase for API response patterns
Identify the common structure
Document as pattern with examples

Output:

Updated CLAUDE.md with API response format section

Example 3: Full Documentation Pass (Handoff)

User Request:

@.claude/skills/document-work/SKILL.md

I'm handing off this project next week. Please review all recent
work (last 2 weeks) and ensure comprehensive documentation for
the next developer.

AI Will:

Review git log for last 2 weeks
Identify all significant changes
Create memory files for major decisions
Document any undocumented patterns
Create comprehensive state.md
Update project.md with recent architecture changes

Output:

Multiple memory files for decisions
Updated patterns.md
Comprehensive state.md for handoff
Updated project.md

Example 4: Quick State Update

User Request:

@.claude/skills/document-work/SKILL.md

Just update state.md - I'm stopping for today and want to capture
where I left off on the payment integration.

AI Will:

Ask about current progress
Update state.md with in-progress work and next steps

Output:

Updated CLAUDE.md

Tips for Effective Documentation

For Patterns

Include both good and bad examples
Explain the "why" not just the "what"
Link to real implementations in codebase
Note any exceptions to the pattern

For Decisions

Be explicit about rejected options
Document constraints that influenced the decision
Include links to relevant discussions/PRs
Note if decision is reversible

For State

Write for your future self (or replacement)
Include enough context to resume without memory
List specific files that were being modified
Note any temporary workarounds in place

Related Workflows

Workflow	Relationship
create-prd.md	For planning new work (before implementation)
cleanup-project.md	For archiving old documentation
generate-tasks.md	For breaking down documented requirements
update-framework.md	For updating Samuel itself

Automation Suggestions

Consider using this workflow:

After each PR merge: Quick pattern + decision check
End of sprint: Full documentation pass
Before vacation: Comprehensive state capture
Quarterly: Review and consolidate memory files