Initial commit

commands/worklog.md

@@ -0,0 +1,132 @@
+---
+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