tendril/docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md

# Phase Documentation Sync Prompt

**Purpose:** Ensure phase documentation (blueprint.md, tasks.md, decisions.md, changelog.md) is synchronized and consistent across all documents for a specified phase.

**How to Use:** Drag this entire document into a Cursor chat session, then provide the phase name or path. The AI assistant will read all phase documents, identify discrepancies, and update them to ensure consistency.

---

## CRITICAL: Information Gathering

### Required Information (You should provide this)

Before starting, **ASK THE USER** for the following information if not already provided:

1. **Phase name or path** (REQUIRED)
   - Format: `phase-XX-name` or full path `tendril/phases/phase-XX-name/`
   - Examples: 
     - `phase-01-foundation`
     - `phase-02-kb-system`
     - `tendril/phases/phase-03-workflows/`
   - Why it's needed: Identifies which phase to synchronize

2. **Sync scope** (OPTIONAL)
   - Format: "all" or specific documents (comma-separated)
   - Examples: `"all"`, `"tasks,changelog"`, `"decisions"`
   - Default: "all" (sync all documents)
   - Why it's needed: Allows syncing specific documents if desired

### If Information is Missing

**ALWAYS ASK** for missing required information before proceeding. Do not make assumptions about:
- Which phase to sync
- Phase directory location
- Document names or structure

---

## Step-by-Step Process

### Phase 1: Read All Phase Documents

1. **Read blueprint.md:**
   - Path: `tendril/phases/phase-XX-name/blueprint.md`
   - Extract: Project name, phase status, deliverables, milestones, definition of done

2. **Read tasks.md:**
   - Path: `tendril/phases/phase-XX-name/tasks.md`
   - Extract: Task list, completion status, phase status line

3. **Read decisions.md:**
   - Path: `tendril/phases/phase-XX-name/decisions.md`
   - Extract: ADR entries, decision dates, decision summaries

4. **Read changelog.md:**
   - Path: `tendril/phases/phase-XX-name/changelog.md`
   - Extract: Recent entries, change dates, change descriptions

5. **Validation:**
   - All four documents exist
   - All documents are readable
   - Key information extracted from each

### Phase 2: Compare and Identify Discrepancies

1. **Compare project name:**
   - Check project name in blueprint
   - Compare with project name in tasks, decisions, changelog
   - List any mismatches

2. **Compare phase status:**
   - Extract status from blueprint (✅ Complete, 🔄 In Progress, ⏳ Planned)
   - Compare with status in tasks.md
   - Compare with status indicators in other documents
   - List any mismatches

3. **Compare deliverables:**
   - Extract deliverables from blueprint "Phase Deliverables" section
   - Compare with tasks in tasks.md
   - Check if all deliverables have corresponding tasks
   - List missing or extra tasks

4. **Compare definition of done:**
   - Extract "Definition of Done" items from blueprint
   - Compare with task checkboxes in tasks.md
   - Verify all DoD items are represented as tasks
   - List missing or extra tasks

5. **Check ADR consistency:**
   - Review decisions mentioned in blueprint
   - Verify corresponding ADRs exist in decisions.md
   - List missing ADRs

6. **Check changelog completeness:**
   - Verify recent blueprint changes are in changelog
   - Check changelog format is correct
   - List missing changelog entries

7. **Validation:**
   - All comparisons completed
   - All discrepancies identified
   - Discrepancy list is complete

### Phase 3: Update Documents

1. **Update tasks.md:**
   - Sync task list with blueprint deliverables
   - Sync task checkboxes with blueprint "Definition of Done"
   - Update phase status line to match blueprint
   - Ensure project name matches blueprint

2. **Update changelog.md:**
   - Add entry for sync operation (if needed)
   - Format: `## [YYYY-MM-DD] Documentation Synchronization`
   - Note: "Synchronized all phase documents for consistency"
   - Use today's date

3. **Update decisions.md:**
   - Add missing ADRs mentioned in blueprint (if any)
   - Ensure ADR format matches existing entries
   - Verify project name matches blueprint

4. **Verify consistency:**
   - Re-read all documents after updates
   - Verify project name matches across all
   - Verify status matches across all
   - Verify deliverables/tasks are aligned

5. **Validation:**
   - All documents updated
   - Consistency verified
   - No discrepancies remain

### Phase 4: Report Sync Results

1. **Summarize changes made:**
   - List documents updated
   - Describe what was synchronized
   - Note any issues encountered

2. **Report remaining issues** (if any):
   - List any discrepancies that couldn't be resolved
   - Explain why they couldn't be fixed
   - Suggest manual review if needed

3. **Validation:**
   - Report is complete
   - All changes documented
   - Issues clearly explained

---

## Error Handling

### Common Issues

#### Phase Directory Not Found
- **Error message**: "Directory not found: tendril/phases/phase-XX-name/"
- **Fix**: 
  1. Verify phase name/path is correct
  2. Check if phase directory exists
  3. List available phases to help user
- **Prevention**: Validate phase path before reading files

#### Missing Document File
- **Error message**: "File not found: [document].md"
- **Fix**:
  1. Check if file exists in phase directory
  2. Verify file name is correct (case-sensitive)
  3. Create missing file if it's a new phase (use templates)
  4. Note missing file in report
- **Prevention**: Check all required files exist before syncing

#### Invalid Document Format
- **Error message**: "Invalid format in [document].md"
- **Fix**:
  1. Review document structure
  2. Check for missing required sections
  3. Fix format issues
  4. Re-read document
- **Prevention**: Validate document structure before processing

#### Project Name Mismatch
- **Error message**: "Project name mismatch across documents"
- **Fix**:
  1. Use blueprint.md as source of truth
  2. Update all other documents to match blueprint
  3. Verify consistency after updates
- **Prevention**: Always use blueprint as authoritative source

#### Status Indicator Mismatch
- **Error message**: "Status mismatch between blueprint and tasks"
- **Fix**:
  1. Use blueprint status as source of truth
  2. Update tasks.md status line
  3. Verify status format is correct (✅, 🔄, ⏳)
- **Prevention**: Always sync status from blueprint to tasks

#### Unresolvable Discrepancies
- **Error message**: "Cannot automatically resolve discrepancy"
- **Fix**:
  1. Report discrepancy to user
  2. Explain why it can't be auto-resolved
  3. Suggest manual review
  4. Continue with other sync operations
- **Prevention**: Document limitations clearly

---

## Validation Checklist

Before completing, verify:

- [ ] All four phase documents read successfully
- [ ] All discrepancies identified
- [ ] tasks.md synced with blueprint deliverables
- [ ] tasks.md synced with blueprint "Definition of Done"
- [ ] tasks.md status matches blueprint status
- [ ] changelog.md updated with sync entry
- [ ] decisions.md reviewed for missing ADRs
- [ ] Project name consistent across all documents
- [ ] Status consistent across all documents
- [ ] Deliverables/tasks aligned
- [ ] All changes verified
- [ ] Sync report provided

---

## Important Notes for AI Assistant

1. **Blueprint is authoritative**: Always use blueprint.md as the source of truth for syncing
2. **Preserve existing content**: Don't delete existing content unless it conflicts with blueprint
3. **Add, don't replace**: When syncing tasks, add missing items rather than replacing entire lists
4. **Use correct date format**: Use YYYY-MM-DD format for changelog entries
5. **Maintain document structure**: Preserve existing document structure and formatting
6. **Handle missing files**: If a document is missing, note it but continue with available documents
7. **Report all changes**: Document what was changed in the sync report
8. **Use Tendril terminology**: Reference "Tendril" project consistently
9. **Follow Cursor rules**: Adhere to phase documentation synchronization rules in `.cursorrules`
10. **Verify after updates**: Always re-read documents after updates to verify consistency

---

**Location**: `docs/PROMPTS/02-Phase-Documentation-Sync-Prompt.md`  
**Related**: 
- `tendril/phases/phase-XX-name/` - Phase directories
- `.cursorrules` - Phase documentation synchronization rules
- `docs/PROMPTS/LLM-Usage-Guide.md` - LLM execution guidelines
- `kb/_guides/PROJECT-SETUP-GUIDE/PHASE-1-PLAN.md` - Phase documentation system