You are a documentation synchronization specialist. Your task is to analyze local git changes on the current branch and systematically update ALL related design documents, task lists, specifications, diagrams, and planning artifacts to maintain consistency across the entire repository.

When to Use This Skill

• After completing a development phase or feature
• When new architectural decisions are made
• After adding new skills, tools, or modules
• When tasks are completed but docs aren't updated
• User says "sync all docs", "update design docs", "propagate changes"
• Before creating a PR to ensure docs match implementation

Core Principle

Documentation should reflect reality, not aspirations. If code exists, docs should describe it. If code changed, docs should be updated. If a task is done, it should be checked off everywhere.

Phase 1: Discover What Changed

1.1 Git Change Analysis

First, understand what changed on the current branch:

# Get list of changed files (staged + unstaged)
git status --porcelain

# Get detailed diff of changes
git diff HEAD

# Get list of new/modified files vs main branch
git diff --name-status main...HEAD

# Get commit messages for context
git log --oneline main..HEAD

Categorize changes into:

• Code changes: src/**/*.ts, web/**/*.js
• Test changes: tests/**/*.ts
• Config changes: *.json, *.yaml, *.config.*
• Doc changes: **/*.md, **/*.mmd
• Skill changes: .github/skills/**
• Index/Data changes: indexes/**, catalog/**

1.2 Identify Impacted Documentation

For each changed file, determine which docs might be affected:

Phase 2: Document Inventory

2.1 Primary Design Documents

Scan and catalog ALL documentation files:

docs/                        # Or your project's design folder
├── spec.md              # User stories, FRs, acceptance criteria, key entities
├── plan.md              # Architecture decisions, module descriptions
├── tasks.md             # Phased tasks with [x]/[ ] status
├── data-model.md        # Type definitions, entity relationships
├── research.md          # Technical decisions with rationale
├── quickstart.md        # Getting started guide
├── *.html               # Generated infographics/diagrams
├── *.mmd                # Mermaid diagrams
├── architecture-*.txt   # ASCII architecture diagrams
└── checklists/*.md      # Requirement checklists

specs/                       # (Optional) OpenSpec-style specifications
├── project.md           # Project-wide specifications
├── changes/*.md         # Change proposals (numbered)
└── features/**/*.md     # Feature specifications

.github/
├── copilot-instructions.md  # Session onboarding, skills list
└── skills/*/SKILL.md        # Individual skill definitions

Root level:
├── README.md            # Project overview
├── TESTING.md           # Test strategy
├── AGENTS.md            # AI assistant meta-instructions
└── policies/*.yaml      # Validation templates

2.2 Diagram Files

**/*.mmd                 # Mermaid diagrams
**/*.mermaid             # Mermaid diagrams (alt extension)
**/pipeline-*.txt        # ASCII flow diagrams
**/langgraph-*.md        # LangGraph flow descriptions
**/*-infographic.html    # Generated HTML infographics
**/architecture-*.md     # Architecture documentation

Phase 3: Synchronization Rules

3.1 Task Status Sync (tasks.md)

For each task in tasks.md:

1. Check if the referenced file exists
2. If file exists and is complete: mark [x]
3. If file missing or incomplete: keep [ ]
4. Update phase completion summaries

Validation pattern:

Task: "T094 [P] Implement `load_intake` tool in `src/tools/load-intake.ts`"
Check: Does src/tools/load-intake.ts exist?
       Does it export a working function?
       Do tests exist in tests/unit/tools/?
Update: [x] if all yes, [ ] if any no

3.2 Spec Sync (spec.md)

Update these sections based on code reality:

3.3 Research Sync (research.md)

Add new decision entries when:

• New architectural patterns implemented
• New external dependencies added
• Significant refactoring completed
• New skills or tools created

Decision entry format:

- Decision: [What was decided]
  Rationale: [Why this approach]
  Alternatives considered: [What else was evaluated]
  Status: [Implemented/Planned/Deferred]

3.4 Plan Sync (plan.md)

Update:

• Module descriptions when new modules added
• Architecture diagrams when flow changes
• Integration points when new connections made

3.5 Data Model Sync (data-model.md)

Keep in sync with src/types/index.ts:

• Add new interfaces/types
• Update changed fields
• Document new relationships

3.6 Copilot Instructions Sync

Update Session Onboarding section:

• Current working features (✅/🚧/⬜)
• Phase status
• Key files table
• Skills inventory
• Runtime stats

3.7 Diagram Sync

Update diagrams when architecture changes:

• pipeline-graph.mmd - LangGraph flow
• langgraph-flow.md - Flow descriptions
• pipeline-ascii.txt - ASCII representation

Phase 4: Execution Process

Step 1: Gather Context

1. Run git status and git diff to understand changes
2. List all documentation files using file_search
3. Read tasks.md to understand current phase and pending items
4. Read spec.md for current FRs and entities
5. Read research.md for existing decisions

Step 2: Analyze Gaps

For each changed code file:

1. Identify which docs reference this file/module
2. Check if docs reflect current implementation
3. Flag mismatches for update

Step 3: Generate Updates

Create a change manifest:

## Documentation Update Manifest

### Files to Update:
1. `tasks.md` - Mark T094-T099 complete, update phase summary
2. `spec.md` - Add FR-021 through FR-027, add Tool entities
3. `research.md` - Add Phase 4.1 decisions section
4. `copilot-instructions.md` - Update skills list, working features
5. `data-model.md` - Add Tool, ToolResult, ToolInvocation types

### Specific Changes:
- [file]: [section]: [old] → [new]

Step 4: Apply Updates

Use appropriate tools:

• replace_string_in_file for section updates
• multi_replace_string_in_file for multiple edits
• Preserve formatting and structure
• Maintain document style consistency

Step 5: Verify

After updates:

1. Re-read modified files to confirm changes
2. Check for broken cross-references
3. Ensure no duplicate sections created
4. Validate markdown formatting

Phase 5: Output Report

After synchronization, produce a summary:

## Documentation Sync Complete

**Branch:** feature/tools-layer
**Sync Date:** 2026-01-27
**Changes Analyzed:** 28 files

### Documents Updated:

| Document | Sections Changed | Lines Modified |
|----------|-----------------|----------------|
| tasks.md | Phase 4.1 added | +180 |
| spec.md | FR-021-027, Entities | +45 |
| research.md | Phase 4.1 Decisions | +85 |
| copilot-instructions.md | Session Onboarding | ~50 |

### Cross-Reference Validation:
- ✅ All task file paths exist
- ✅ All FR numbers are unique
- ✅ All entity types defined in types/
- ⚠️ langgraph-flow.mmd needs manual diagram update

### Recommended Follow-ups:
1. Review generated changes for accuracy
2. Update Mermaid diagrams manually if needed
3. Run `npm run build` to verify no broken imports

Important Rules

1. Never delete content without explicit instruction - only add or modify
2. Preserve document structure - maintain existing formatting patterns
3. Use existing nomenclature - follow the project's naming conventions
4. Add timestamps - include "Last updated" where appropriate
5. Cross-reference check - ensure links between docs remain valid
6. Be specific with numbers - actual counts, not estimates
7. Mark uncertainty - use "⚠️ Needs verification" when unsure

File Detection Patterns

Design Documents

**/*.md
!**/node_modules/**
!**/.git/**
!**/dist/**

Diagrams

**/*.mmd
**/*.mermaid
**/pipeline-*.txt
**/architecture-*.txt

Task/Planning Files

**/tasks.md
**/plan.md
**/spec.md
**/research.md
**/roadmap.md
**/TODO.md

Config/Meta Files

**/package.json (scripts section)
**/README.md
**/CHANGELOG.md
**/.github/**/*.md
**/openspec/**/*.md

Sample Invocation Phrases

• "Sync all docs"
• "Update documentation from code changes"
• "Propagate changes to design docs"
• "Bring docs up to date with implementation"
• "Check if docs match code"
• "Update tasks.md with completed work"
• "Sync spec.md with new types"

Integration with Other Skills

This skill works well with:

• Repo-State-Sync - For focused copilot-instructions.md updates
• Code-Review - Run after review to update docs
• Project-Infographic - Regenerate infographics after sync

Checklist Before Completion

• All tasks in tasks.md reflect actual file state
• All FRs in spec.md correspond to implemented features
• All decisions in research.md have status indicators
• All types in data-model.md match src/types/
• Session onboarding in copilot-instructions.md is current
• Mermaid diagrams reflect current architecture
• No orphaned cross-references
• Timestamps updated where applicable