---
tags: ["workflow", "collaboration", "documentation"]
description: "Add timestamped work log entries to track manual changes and communicate with AI"
argument-hint: "\"your comment text\""
allowed-tools: ["Read", "Write", "Edit", "Grep", "Glob"]
model: claude-sonnet-4-5
references_guidelines:
  - docs/development/workflows/worklog-format.md  # WORKLOG format and work documentation standards
---

# /worklog Command

**WHAT**: Add timestamped work log entries to track manual changes and communicate with AI.

**WHY**: Enable AI to understand manual work, avoid duplicating human effort, and maintain shared context.

**HOW**: See worklog-format.md for format standards. AI timestamps entry, finds WORKLOG, prepends in reverse chronological order.

## Usage

```bash
/worklog "Added login button to header"
/worklog "Fixed dark mode - using --color-grey-dark (#2d2d2d)"
/worklog "Don't use jsonwebtoken - jose has better TS support"
```

## How It Works

AI executes this workflow:

1. **Get timestamp**: Run `date '+%Y-%m-%d %H:%M'` (NEVER guess/estimate)
2. **Get username**: Run `git config user.name`
3. **Find WORKLOG**: Locate current task's WORKLOG.md in `pm/issues/TASK-###-*/`
4. **Prepend entry** (reverse chronological):
   ```markdown
   ## 2025-10-22 15:30 - @username
   Added login button to header
   ```
5. **Analyze impact**: Read TASK.md and check if comment relates to existing phases
6. **Offer update** (interactive): Ask if task plan needs updating based on comment
7. **Update if confirmed**: Modify TASK.md and log the change in WORKLOG.md

## When to Use

✅ **Use when:**
- Making manual code changes outside `/implement`
- Documenting gotchas or lessons learned
- Communicating constraints to AI ("must use library X")

❌ **Don't use when:**
- AI agents did the work (they auto-log)
- No changes made (just reading code)
- Already documented in commit message

## WORKLOG Format

```markdown
# Work Log - TASK-001: User Authentication

## 2025-10-22 15:30 - @taylor
Added login button with dark mode support.
Files: src/components/Header.tsx

## 2025-10-22 14:30 - backend-specialist
Implemented JWT middleware with refresh logic.
Gotcha: Token expiry configurable via TOKEN_EXPIRY_HOURS.
Files: src/middleware/auth.js
```

**Reverse chronological** (newest first) for quick context scanning.

## Interactive Plan Updates

After adding comment, AI analyzes task plan:

```
Your comment mentions login button. This might relate to:
- [ ] 2.1 Implement login UI components

Update task plan?
  1. Mark phase 2.1 complete
  2. Add new phase for login work
  3. No update needed

Choose (1/2/3): _
```

## Examples

**Styling work:**
```bash
/worklog "Tweaked button padding to 12px/24px for mobile"
# → Added to WORKLOG, no plan updates needed
```

**Feature addition:**
```bash
/worklog "Added email validation to login form"
# → Added to WORKLOG, AI asks: "Mark phase 1.3 complete? (y/n)"
```

**Gotcha documentation:**
```bash
/worklog "Don't use setTimeout for token refresh - use setInterval"
# → Added to WORKLOG, documented for future reference
```

**API change:**
```bash
/worklog "API changed - login endpoint now /api/v2/auth/login"
# → Added to WORKLOG, AI asks: "Update phase 3.1 description? (y/n)"
```

## Error Handling

**No active task**: AI lists available tasks and asks which one to associate comment with

**No WORKLOG.md**: AI creates it automatically with proper header

## Benefits

**For AI**: Understands manual changes, avoids duplicating human work, respects decisions
**For Humans**: Quick documentation, no context switching, AI keeps plan synchronized
**For Teams**: Shared history, captured gotchas, implementation timeline

## Philosophy

Human-AI collaboration through shared work log:
- Humans add comments for manual work
- AI agents add entries for automated work
- Both contribute to narrative history
- Result: AI remembers context, avoids breaking existing features