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