sync-docs

name	sync-docs
description	Strategic documentation sync - review docs before implementation (pull context) OR export learnings after implementation (push to living docs). NOT bidirectional - two separate one-way operations at different phases.

Sync Documentation

You are executing the SpecWeave strategic documentation sync command. This handles phase-based documentation synchronization:

• Review mode: Pull strategic docs for pre-implementation context
• Update mode: Push implementation learnings to living docs

Note: This is NOT bidirectional sync (simultaneous two-way). It's two separate one-way operations at different project phases.

---

STEP 1: Parse Arguments and Detect Mode

Arguments provided: [user's arguments]

Parse the input:

• Check for explicit mode: review, update, or none (auto-detect)
• Check for increment ID: 0001, 0002, etc., or none (sync all - NEW DEFAULT)
• Check for --all flag (explicit sync all)

DEFAULT BEHAVIOR:

• No arguments → Sync all increments with spec.md (batch mode)
• Specific increment ID → Sync that increment only
• --all flag → Sync all increments (explicit)

Auto-detect logic:

1. If no increment ID provided (NEW DEFAULT):

   # Sync ALL increments with spec.md
   echo "🔄 Syncing all increments..."
   npx specweave sync-specs
   # This will sync all non-archived increments
   

2. If increment ID provided:

   # Read the increment's spec.md to check status
   INCREMENT_PATH=".specweave/increments/{increment_id}"
   STATUS=$(grep "^status:" "$INCREMENT_PATH/spec.md" | cut -d: -f2 | tr -d ' ')
   

3. Determine mode:

   If no increment ID → BATCH SYNC MODE (sync all)
   
   If increment ID provided:
     If status = "planned" → REVIEW MODE
     If status = "in-progress" → UPDATE MODE
     If status = "completed" → UPDATE MODE
     If status = "closed" → UPDATE MODE
   
   If explicit mode provided → Use that mode
   

Output (Batch Mode):

🔄 Syncing all increments...

📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
   ✅ Synced 3 tasks to US-001
✅ Synced 0040 → FS-040

📚 Syncing 0041-living-docs-test-fixes → FS-041...
   ✅ Synced 2 tasks to US-001
✅ Synced 0041 → FS-041

✅ Sync complete: 15 increments synced, 0 failed

Output (Single Mode):

🔍 Detected increment: {increment_id}
📊 Status: {status}
🎯 Mode: {REVIEW or UPDATE}

Proceeding with {mode} mode...

---

STEP 2A: REVIEW MODE (Pre-Implementation)

Execute this if mode = REVIEW

Review Mode Purpose

Present strategic documentation to user for approval before implementation starts.

Execution Steps:

1. Locate increment folder:

   INCREMENT_DIR=".specweave/increments/{increment_id}"
   

2. Read all strategic documentation:

   # Required files
   SPEC_MD="$INCREMENT_DIR/spec.md"
   
   # Optional files
   PM_ANALYSIS="$INCREMENT_DIR/pm-analysis.md"
   ARCHITECTURE="$INCREMENT_DIR/architecture.md"
   INFRASTRUCTURE="$INCREMENT_DIR/infrastructure.md"
   SECURITY="$INCREMENT_DIR/security.md"
   TEST_STRATEGY="$INCREMENT_DIR/test-strategy.md"
   PLAN="$INCREMENT_DIR/plan.md"
   

3. Read related ADRs:

   # Check for ADRs referenced in plan.md or architecture.md
   ADR_DIR=".specweave/docs/internal/architecture/adr"
   

4. Present comprehensive summary:

═══════════════════════════════════════════════════════
📋 STRATEGIC DOCUMENTATION REVIEW
═══════════════════════════════════════════════════════

Increment: {increment_id}
Title: {title from spec.md}
Priority: {priority from spec.md}
Status: {status from spec.md}

───────────────────────────────────────────────────────
✅ PRODUCT SPECIFICATION (spec.md)
───────────────────────────────────────────────────────

[Summarize spec.md content - user stories, requirements, acceptance criteria]

{If pm-analysis.md exists:}
───────────────────────────────────────────────────────
✅ PRODUCT STRATEGY (pm-analysis.md)
───────────────────────────────────────────────────────

User Personas:
[List personas with needs and pain points]

Business Model:
[Revenue model, target metrics]

Feature Prioritization:
[P1/P2/P3 breakdown]

Success Metrics:
[Key metrics to track]

{If architecture.md exists:}
───────────────────────────────────────────────────────
✅ SYSTEM ARCHITECTURE (architecture.md)
───────────────────────────────────────────────────────

Tech Stack:
[List detected or specified tech stack]

System Design:
[Show Mermaid diagram if present, or describe architecture]

Data Models:
[List key entities and relationships]

API Design:
[List key endpoints or interfaces]

Scalability Considerations:
[Performance targets, scaling strategy]

{If ADRs referenced:}
───────────────────────────────────────────────────────
✅ ARCHITECTURE DECISIONS (ADRs)
───────────────────────────────────────────────────────

[For each ADR mentioned in plan.md:]
ADR {number}: {title}
  - Decision: {what was decided}
  - Rationale: {why}
  - Trade-offs: {consequences}

{If infrastructure.md exists:}
───────────────────────────────────────────────────────
✅ INFRASTRUCTURE (infrastructure.md)
───────────────────────────────────────────────────────

Platform: {platform choice}
Resources: {compute, storage, database specs}
Deployment: {deployment strategy}
Monitoring: {monitoring tools}
Cost Estimate: {monthly cost breakdown}

{If security.md exists:}
───────────────────────────────────────────────────────
✅ SECURITY (security.md)
───────────────────────────────────────────────────────

Authentication: {auth strategy}
Authorization: {authz strategy}
Data Protection: {encryption, GDPR compliance}
Security Testing: {security test plan}

{If test-strategy.md exists:}
───────────────────────────────────────────────────────
✅ TEST STRATEGY (test-strategy.md)
───────────────────────────────────────────────────────

Test Pyramid:
[E2E, Integration, Unit test breakdown]

Coverage Target: {target %}

Critical Paths:
[List critical user journeys to test]

{If plan.md exists:}
───────────────────────────────────────────────────────
⏱️  IMPLEMENTATION PLAN (plan.md)
───────────────────────────────────────────────────────

Total Tasks: {count}
Estimated Time: {estimate}

Phases:
[List implementation phases with task ranges]

───────────────────────────────────────────────────────
💰 COST & TIMELINE SUMMARY
───────────────────────────────────────────────────────

Infrastructure: ${monthly cost}/month
External Services: ${services cost}/month
Total Monthly: ${total}/month

Development Time: {weeks} weeks
Launch Target: {date estimate}

═══════════════════════════════════════════════════════

❓ Do you approve this plan?

Options:
  ✅ Type "approve" - Proceed with implementation
  ⚠️  Type "changes" - Request specific updates
  📋 Type "questions" - Ask clarifying questions
  🔄 Type "regenerate" - Regenerate strategic analysis

───────────────────────────────────────────────────────

5. Wait for user response:
   • If "approve" → Say: "✅ Strategic documentation approved. Ready to proceed with /do command."
   • If "changes" → Ask: "What would you like to change? (architecture/features/security/infrastructure/other)"
   • If "questions" → Ask: "What questions do you have?"
   • If "regenerate" → Ask: "Which section should I regenerate?"

STOP HERE for review mode - Do not proceed to update mode.

---

STEP 2B: UPDATE MODE (Post-Implementation)

Execute this if mode = UPDATE

Update Mode Purpose

Synchronize living documentation in .specweave/docs/ with learnings and decisions from completed or in-progress increment.

Execution Steps:

0. 🔄 SYNC LIVING SPECS (User Stories, ACs, Tasks) - CRITICAL FIRST STEP

🚨 MANDATORY: This MUST run FIRST before syncing strategic docs!

Execute the living specs sync using the TypeScript CLI:

import { syncSpecs } from './dist/src/cli/commands/sync-specs.js';

console.log('═══════════════════════════════════════════════════════');
console.log('📋 STEP 0: SYNCING LIVING SPECS');
console.log('═══════════════════════════════════════════════════════\n');
console.log('🔄 Syncing user stories, acceptance criteria, and tasks...\n');

// Call sync-specs to sync living docs structure
await syncSpecs(['{increment_id}']);

console.log('\n✅ Living specs synced successfully!');
console.log('   - User stories created/updated in .specweave/docs/internal/specs/');
console.log('   - Acceptance criteria synchronized with completion status');
console.log('   - Tasks linked to user stories\n');

What this step does:

• ✅ Parses increment spec.md and extracts user stories with ACs
• ✅ Syncs AC completion status from spec.md to user story files
• ✅ Updates task mappings in user story files
• ✅ Creates/updates feature files and README
• ✅ Ensures living specs are in sync BEFORE strategic docs

Output:

🎯 Target increment: {increment_id}
📁 Increment path: .specweave/increments/{increment_id}
🔄 Mode: Specs-only sync (Universal Hierarchy)

Processing...
📚 Syncing {increment_id} → {FS-XXX}...
   ✅ Synced 3 tasks to US-001
   ✅ Synced 2 tasks to US-002

✅ Synced {increment_id} → {FS-XXX}
   Created: 5 files

═══════════════════════════════════════════════════════

CRITICAL: If this step fails, STOP and report error. Do not proceed to strategic docs sync.

---

1. Analyze Increment Artifacts

INCREMENT_DIR=".specweave/increments/{increment_id}"

# Read all increment files
SPEC="$INCREMENT_DIR/spec.md"
PLAN="$INCREMENT_DIR/plan.md"
ARCHITECTURE="$INCREMENT_DIR/architecture.md"
SECURITY="$INCREMENT_DIR/security.md"
INFRASTRUCTURE="$INCREMENT_DIR/infrastructure.md"
REPORTS_DIR="$INCREMENT_DIR/reports"

# List all report files
REPORTS=$(ls -1 "$REPORTS_DIR"/*.md 2>/dev/null)

Extract documentation updates:

Reading increment {increment_id}...

📄 Files found:
  ✓ spec.md
  {✓ or ✗ for each optional file}
  ✓ {count} reports in reports/

🔍 Analyzing for documentation updates...

2. Identify Documentation Targets

Map increment content to living docs locations:

# Mapping rules:
spec.md (new features):
  → .specweave/docs/public/overview/features.md
  → .specweave/docs/public/guides/ (if guides section present)

spec.md (API changes):
  → .specweave/docs/public/api/ (if exists)

plan.md (architecture decisions):
  → .specweave/docs/internal/architecture/adr/NNNN-decision-name.md (create new ADR)

plan.md (tech stack changes):
  → .specweave/docs/internal/architecture/README.md

architecture.md:
  → .specweave/docs/internal/architecture/diagrams/ (extract diagrams)
  → .specweave/docs/internal/architecture/system-design.md

security.md:
  → .specweave/docs/internal/security/

infrastructure.md:
  → .specweave/docs/internal/operations/deployment.md
  → .specweave/docs/internal/operations/infrastructure.md

reports/*.md (learnings):
  → .specweave/docs/internal/delivery/guides/
  → .specweave/docs/internal/architecture/ (if architectural learnings)

test-strategy.md:
   

Output:

📊 Documentation updates identified:

1. New ADR needed: {decision from plan.md}
   Target: .specweave/docs/internal/architecture/adr/NNNN-{slug}.md

2. Feature list update: {feature from spec.md}
   Target: .specweave/docs/public/overview/features.md

3. Architecture diagram update: {diagram from architecture.md}
   Target: .specweave/docs/internal/architecture/diagrams/{name}.md

{... list all updates}

Total: {count} documentation updates

3. Detect Conflicts

For each target file that already exists:

1. Read existing content
2. Read new content from increment
3. Compare and detect conflicts:

function detectConflict(existingContent, newContent, section) {
  // Types of conflicts:

  // 1. Addition (no conflict)
  if (!existingContent.includes(section) && newContent.includes(section)) {
    return { type: 'addition', conflict: false };
  }

  // 2. Enhancement (minor conflict - check if contradictory)
  if (existingContent.includes(section) && newContent.includes(section)) {
    // Check if new content contradicts existing
    if (isContradictory(existingContent, newContent)) {
      return { type: 'contradiction', conflict: true };
    } else {
      return { type: 'enhancement', conflict: false };
    }
  }

  // 3. Removal (conflict)
  if (existingContent.includes(section) && !newContent.includes(section)) {
    return { type: 'removal', conflict: true };
  }

  return { type: 'no_change', conflict: false };
}

Conflict detection heuristics:

• Keywords that indicate contradiction: "instead of", "rather than", "changed from", "no longer", "deprecated"
• Architecture decisions with different choices (PostgreSQL vs MongoDB)
• Security policies with different rules
• API endpoints with different signatures

Output:

🔍 Conflict detection results:

✅ No conflict: {count} additions/enhancements
⚠️  Conflicts found: {count} contradictions/removals

{If conflicts found, list them}

4. Resolve Conflicts (If Any)

For each conflict, present to user:

═══════════════════════════════════════════════════════
⚠️  CONFLICT #{n}/{total}
═══════════════════════════════════════════════════════

File: {target_file_path}
Section: {section_name}
Conflict Type: {contradiction/removal}

───────────────────────────────────────────────────────
📄 EXISTING CONTENT
───────────────────────────────────────────────────────
{show existing content with context - 5 lines before/after}

───────────────────────────────────────────────────────
🆕 NEW CONTENT (from increment {increment_id})
───────────────────────────────────────────────────────
{show new content with context}

───────────────────────────────────────────────────────
❓ How should I resolve this?
───────────────────────────────────────────────────────

A) Keep existing only
B) Replace with new only
C) Merge both (document the evolution)
D) Show me more context
E) Skip this update

{If architecture decision:}
💡 Recommendation: Option C - Create new ADR documenting the change

Your choice (A/B/C/D/E):

Wait for user input, then record decision

5. Apply Updates

For each update (non-conflicting + resolved conflicts):

1. If creating new file:

   TARGET_FILE="{path}"
   mkdir -p "$(dirname "$TARGET_FILE")"
   cat > "$TARGET_FILE" <<EOF
   {content}
   EOF
   

   Output: ✅ Created: {file_path}

2. If updating existing file:

   # Backup first
   cp "$TARGET_FILE" "$TARGET_FILE.backup"
   
   # Apply update (append, replace section, or merge)
   {update logic based on user choice}
   

   Output: ✅ Updated: {file_path}

3. If creating new ADR:

   # Get next ADR number
   NEXT_ADR=$(ls -1 .specweave/docs/internal/architecture/adr/ | grep -E '^[0-9]{4}' | sort -r | head -1 | cut -d- -f1)
   NEXT_ADR=$((NEXT_ADR + 1))
   NEXT_ADR=$(printf "%04d" $NEXT_ADR)
   
   ADR_FILE=".specweave/docs/internal/architecture/adr/${NEXT_ADR}-{slug}.md"
   

   ADR Template:

   # ADR-{number}: {Title}
   
   **Status**: Accepted
   **Date**: {current_date}
   **Deciders**: {team}
   **Supersedes**: {previous_adr if applicable}
   
   ## Context
   
   {describe the problem/decision point from increment}
   
   ## Decision
   
   {what was decided during implementation}
   
   
   
   {why this decision was made - from plan.md or reports/}
   
   
   
   
   {benefits}
   
   
   {trade-offs or limitations}
   
   
   
   {how it was implemented - reference increment {incrementid}
    {other related ADRs}
   

6. Summary Report

═══════════════════════════════════════════════════════
✅ DOCUMENTATION SYNC COMPLETE
═══════════════════════════════════════════════════════

Increment: {increment_id} ({title})
Status: {status} → Documentation Updated

───────────────────────────────────────────────────────
📋 LIVING SPECS SYNCED (Step 0)
───────────────────────────────────────────────────────

✅ User Stories: {count} created/updated in .specweave/docs/internal/specs/
✅ Acceptance Criteria: Synchronized with completion status from spec.md
✅ Tasks: Linked to user stories with completion tracking
✅ Feature Files: Created/updated in .specweave/docs/internal/specs/{project}/

───────────────────────────────────────────────────────
📊 STRATEGIC DOCS CHANGES (Steps 1-5)
───────────────────────────────────────────────────────

Created:
  {list of new files with paths}
  Total: {count} files

Updated:
  {list of updated files with paths}
  Total: {count} files

ADRs Generated:
  {list of new ADRs}
  Total: {count} ADRs

Skipped:
  {list of skipped updates due to user choice}
  Total: {count} updates

───────────────────────────────────────────────────────
💾 BACKUPS
───────────────────────────────────────────────────────

{If any files were updated:}
Backup files created: {count}
Location: {original_file}.backup

To restore: cp {file}.backup {file}

───────────────────────────────────────────────────────
🎯 NEXT STEPS
───────────────────────────────────────────────────────

1. Review updated documentation:
   - Living specs: .specweave/docs/internal/specs/
   - Public docs: .specweave/docs/public/
   - Internal docs: .specweave/docs/internal/
   - New ADRs: .specweave/docs/internal/architecture/adr/

2. Verify living specs sync:
   - Check user story files for updated AC checkboxes
   - Verify tasks are linked correctly
   - Confirm feature files are up to date

3. (Optional) Generate Docusaurus site:
   - Use 'docusaurus' skill to publish updated docs

4. Commit changes:
   git add .specweave/docs/
   git commit -m "docs: sync from increment {increment_id}"

═══════════════════════════════════════════════════════

ALL documentation is now in sync with increment {increment_id}! 🎉
(Living specs + Strategic docs)

---

STEP 3: Configuration Support

Check for user configuration (optional):

If config exists, respect it. If not, use defaults shown above.

---

ERROR HANDLING

Error: Increment Not Found

❌ Error: Increment '{increment_id}' not found

Available increments:
  {list .specweave/increments/*/}

Usage: /sw:sync-docs [review|update] [increment_id]

Error: No Increment Files

❌ Error: Increment '{increment_id}' has no spec.md

This increment may be incomplete. Expected files:
  - spec.md (required)
  - plan.md (optional)
  - architecture.md (optional)

Cannot proceed with sync.

Error: Invalid Mode

❌ Error: Invalid mode '{mode}'

Valid modes:
  - review (pre-implementation doc review)
  - update (post-implementation doc sync)
  - [none] (auto-detect based on status)

Usage: /sw:sync-docs [review|update] [increment_id]

---

EXAMPLES

Example 1: Sync all increments (NEW DEFAULT)

User: /sw:sync-docs

Output:
🔄 Syncing all increments...

📚 Syncing 0040-vitest-living-docs-mock-fixes → FS-040...
   ✅ Synced 3 tasks to US-001
✅ Synced 0040 → FS-040

📚 Syncing 0041-living-docs-test-fixes → FS-041...
   ✅ Synced 2 tasks to US-001
✅ Synced 0041 → FS-041

📚 Syncing 0042-test-infrastructure-cleanup → FS-042...
   ✅ Synced 5 tasks to US-002
✅ Synced 0042 → FS-042

✅ Sync complete: 15 increments synced, 0 failed

Example 2: Sync specific increment

User: /sw:sync-docs 0042

Output:
🔍 Detected increment: 0042
📊 Status: completed
🎯 Mode: UPDATE

Proceeding with UPDATE mode...
{... executes update mode for 0042 only}

Example 3: Explicit review mode

User: /sw:sync-docs review 0003

Output:
🔍 Increment: 0003
📊 Status: planned
🎯 Mode: REVIEW

{... shows strategic documentation summary}

Example 4: Explicit update mode with increment

User: /sw:sync-docs update 0002

Output:
🔍 Increment: 0002
📊 Status: completed
🎯 Mode: UPDATE

{... executes update mode with conflict resolution}

---

IMPORTANT NOTES

1. Always show progress: Keep user informed at each step
2. Always ask on conflicts: Never overwrite without user approval
3. Always create backups: Before modifying existing files
4. Always provide summary: Show what changed at the end
5. Never skip validation: Check files exist before reading
6. Never assume structure: Verify .specweave/docs/ structure exists

---

You are now ready to execute this command. Follow the steps above precisely.