163 lines
4.6 KiB
Markdown
163 lines
4.6 KiB
Markdown
---
|
|
tags: ["workflow", "manual-changes", "planning"]
|
|
description: "Sync project state after manual changes via git diff analysis"
|
|
argument-hint: ""
|
|
allowed-tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep", "TodoWrite"]
|
|
model: claude-sonnet-4-5
|
|
references_guidelines:
|
|
- docs/development/workflows/pm-workflows.md # Plan structure and phase management
|
|
- docs/development/workflows/worklog-format.md # WORKLOG entry formats
|
|
- docs/development/workflows/git-workflow.md # Git diff analysis
|
|
---
|
|
|
|
# /sync-progress Command
|
|
|
|
**WHAT**: Automatically sync project state when user makes manual changes.
|
|
|
|
**WHY**: Analyzes git diff, updates plan to reflect progress, and documents changes in WORKLOG without manual explanation.
|
|
|
|
**HOW**: See pm-guide.md for plan/phase management, worklog-format.md for entry structure, git-workflow.md for git analysis.
|
|
|
|
---
|
|
|
|
## Workflow
|
|
|
|
### 1. Analyze Changes
|
|
|
|
Run these commands to understand what changed:
|
|
|
|
```bash
|
|
# Check for uncommitted changes
|
|
git diff
|
|
|
|
# Check staged changes
|
|
git diff --staged
|
|
|
|
# Get summary of changed files
|
|
git status --short
|
|
```
|
|
|
|
### 2. Read Current State
|
|
|
|
Read the following files if they exist:
|
|
- `pm/active/PLAN.md` - Current task plan
|
|
- `pm/active/WORKLOG.md` - Work history
|
|
- `pm/active/spec.md` - Feature specification (if applicable)
|
|
|
|
### 3. Analyze and Update
|
|
|
|
**For each changed file in git diff**:
|
|
|
|
1. **Determine intent** - What was the user trying to accomplish?
|
|
- New feature implementation
|
|
- Bug fix
|
|
- Refactoring
|
|
- Configuration change
|
|
- Documentation update
|
|
|
|
2. **Compare to PLAN.md**:
|
|
- Which phase/task does this relate to?
|
|
- Is this planned work or new direction?
|
|
- Should any phases be marked complete?
|
|
- Are there new tasks to add?
|
|
|
|
3. **Update PLAN.md**:
|
|
- If there is ANY ambiguity clarify with user
|
|
- Mark completed phases as `[x] COMPLETED`
|
|
- Update phase descriptions if approach changed
|
|
- Add new phases if user took different direction
|
|
- Add notes about implementation decisions made
|
|
|
|
### 4. Document in WORKLOG
|
|
|
|
Write a WORKLOG entry with:
|
|
|
|
```markdown
|
|
## YYYY-MM-DD HH:MM - Manual Changes Synced
|
|
|
|
**Files Changed**: [list of changed files]
|
|
|
|
**Changes Made**:
|
|
- [Brief description of each major change]
|
|
- [Why it was done - inferred from code]
|
|
- [Any patterns or decisions observed]
|
|
|
|
**Plan Updates**:
|
|
- [Which phases marked complete]
|
|
- [Any new phases added]
|
|
- [Any direction changes noted]
|
|
|
|
**Status**: [Current project state after these changes]
|
|
|
|
**Next Steps**: [Suggested next actions based on plan]
|
|
```
|
|
|
|
### 5. Summary Report
|
|
|
|
Provide user with:
|
|
- **Changes detected**: Count and summary of modified files
|
|
- **Plan updates**: Which phases completed, which added
|
|
- **WORKLOG entry**: Confirmation of documentation
|
|
- **Next suggested action**: Based on remaining plan items
|
|
|
|
---
|
|
|
|
## Key Principles
|
|
|
|
1. **Infer intent from code** - Don't ask user to explain, analyze the diff
|
|
2. **Be accurate** - Only mark phases complete if truly done
|
|
3. **Preserve context** - Keep plan structure, don't overwrite unnecessarily
|
|
4. **Document decisions** - Note any technical choices made in code
|
|
5. **Suggest next steps** - Help user know what to work on next
|
|
|
|
---
|
|
|
|
## Example Usage
|
|
|
|
**Scenario**: User manually implemented authentication while AI was offline
|
|
|
|
**Command**: `/sync-progress`
|
|
|
|
**AI Actions**:
|
|
1. Runs `git diff` - sees new files: `auth/login.ts`, `auth/middleware.ts`, `db/users.sql`
|
|
2. Reads `pm/active/PLAN.md` - finds Phase 2: "Implement authentication system"
|
|
3. Updates PLAN.md:
|
|
- Marks Phase 2 as `[x] COMPLETED`
|
|
- Adds notes: "Used JWT tokens, bcrypt for passwords, PostgreSQL for users table"
|
|
4. Writes WORKLOG entry documenting authentication implementation
|
|
5. Reports: "Detected authentication implementation complete. Phase 2 marked done. Next: Phase 3 - API endpoint protection"
|
|
|
|
---
|
|
|
|
## Edge Cases
|
|
|
|
**No PLAN.md exists**:
|
|
- Create one based on git changes
|
|
- Infer project structure and goals
|
|
- Add phases for observed work
|
|
|
|
**Changes conflict with plan**:
|
|
- Note the deviation in WORKLOG
|
|
- Ask user if plan should be updated or reverted
|
|
- Suggest reconciliation approach
|
|
|
|
**Changes are exploratory/experimental**:
|
|
- Don't mark plan phases complete
|
|
- Add note to PLAN.md: "Exploration: [description]"
|
|
- Document in WORKLOG as research/spike
|
|
|
|
**Multiple unrelated changes**:
|
|
- Group by functional area
|
|
- Update multiple plan phases if applicable
|
|
- Create clear sections in WORKLOG entry
|
|
|
|
---
|
|
|
|
## Success Criteria
|
|
|
|
✅ All git changes analyzed and understood
|
|
✅ PLAN.md accurately reflects current state
|
|
✅ Completed work properly marked
|
|
✅ WORKLOG entry is clear and comprehensive
|
|
✅ User knows what to do next
|