Documentation Synchronization

Ensures documentation reflects current reality.

Activation Context

This skill activates during:

• After /ultra-research completion
• Feature completion
• Architecture changes
• /ultra-deliver execution
• Documentation-related discussions

Resources

Documentation Management

Check for Drift

python scripts/doc_sync.py check

Create New ADR

python scripts/doc_sync.py create-adr <number> <title>
python scripts/doc_sync.py create-adr 5 "Use PostgreSQL for primary database"

List All ADRs

python scripts/doc_sync.py list-adrs

Documentation Locations

New projects (specs/):

• specs/product.md - Product requirements
• specs/architecture.md - Technical decisions

Legacy projects (docs/):

• docs/prd.md - Product requirements
• docs/tech.md - Technical decisions

Always:

• .ultra/docs/decisions/ - ADRs (Architecture Decision Records)
• .ultra/docs/research/ - Research reports

Synchronization Tasks

After Research

When research introduces new information:

• Update relevant specification file with findings
• Create ADR if major decision made
• Flag [NEEDS CLARIFICATION] for unresolved items

After Feature Completion

Check alignment between:

• User stories in specs/product.md and implemented features
• Architecture in specs/architecture.md and actual code structure

ADR Creation

Create ADRs for significant decisions:

# ADR-{number}: {Title}

## Status
Accepted

## Context
{What situation led to this decision}

## Decision
{What we decided to do}

## Consequences
{What this means going forward}

Auto-create in: .ultra/docs/decisions/ADR-{number}-{slug}.md

Drift Detection

Look for misalignment:

• Features in code not documented in specs
• Specs describing features not yet implemented
• Architecture docs not matching actual structure
• Stale markers: [NEEDS CLARIFICATION], [TODO], [TBD]

Safe Auto-Creation

Create these files automatically:

• ADRs in .ultra/docs/decisions/
• Tech debt entries in .ultra/docs/tech-debt.md
• Research reports in .ultra/docs/research/
• Project-level CLAUDE.md in project root

Number ADRs sequentially (ADR-001, ADR-002, etc.)

Project-Level CLAUDE.md Generation

Purpose

Generate and maintain a project-specific CLAUDE.md at project root. Claude Code automatically reads this file, providing project context for every conversation.

Trigger Conditions

Generate/update CLAUDE.md when:

1. /ultra-research completes (full generation)
2. Task completes via /ultra-dev (update "Current Focus")
3. specs/ files are modified (incremental update)
4. /ultra-deliver completes (add release info)

Content Structure

# {Project Name}

## Project Overview
{1-2 paragraph summary from specs/product.md}

## Tech Stack
{Extracted from specs/architecture.md}
- Frontend: {framework}
- Backend: {framework}
- Database: {database}
- Testing: {framework}

## Development Rules
{Core rules from architecture decisions}
- Code style: {convention}
- Test coverage: ≥{X}%
- Commit format: Conventional Commits

## Known Risks
{Active risks from risk assessment}
- [High] {risk}: {mitigation}
- [Medium] {risk}: {mitigation}

## Current Focus
{From tasks.json - in_progress and next pending}
- In Progress: Task #{id} - {title}
- Next: Task #{id} - {title}

---
*Auto-generated by syncing-docs skill | Last updated: {timestamp}*

Generation Process

Step 1: Read Source Files

specs/product.md      → Project Overview
specs/architecture.md → Tech Stack, Development Rules
docs/research/*.md    → Known Risks (from risk assessment)
tasks/tasks.json      → Current Focus

Step 2: Extract Content

• Project name from architecture.md or directory name
• First 2 paragraphs from product.md for overview
• Tech stack table from architecture.md
• High/Medium risks only (skip Low)
• First in_progress task + first pending task

Step 3: Generate CLAUDE.md

• Write to project root (not .ultra/)
• Limit to ~500 words to minimize token usage
• Include generation timestamp

Step 4: Update .gitignore

• Ensure CLAUDE.local.md is in .gitignore (personal config)
• CLAUDE.md should be committed (shared team context)

Update Rules

Quality Constraints

• Max length: 500 words (minimize token cost)
• No duplication: Reference specs/ for details, don't copy
• Actionable: Rules should be specific, not vague
• Current: Always reflect latest project state

Output Format

Provide updates in Chinese at runtime:

文档同步检查
========================

发现：
- {具体发现或建议}

建议更新：
- {文件路径}: {需要更新的内容}

========================

Tone: Helpful, proactive