Sync Application Design Document

User Request: $ARGUMENTS

Context

• Project root: !pwd
• Package.json: @package.json
• Current design doc: @.claude/rules/1-app-design-document.mdc
• Last modified: !stat -f "%Sm" .claude/rules/1-app-design-document.mdc 2>/dev/null || echo "No existing document"

Goal

Update the existing Application Design Document to reflect current codebase state, new features, changed priorities, and project evolution. Maintain consistency with the original document while incorporating new information.

Process

1. Document Analysis

• Read and understand the existing 1-app-design-document.mdc
• Establish baseline understanding of documented features
• Note the document's structure and tone
• Identify areas that may need updates

2. Codebase Change Detection

Think deeply about what has changed in the codebase since the document was last updated.

Analyze for:

• New Features: Components, modules, or capabilities added
• Modified Flows: Changes to user journeys or business logic
• Removed Features: Deprecated or deleted functionality
• Architecture Evolution: New patterns, services, or integrations
• Scale Changes: Growth in complexity or user base
• Security Updates: New authentication/authorization patterns

Extended thinking helps identify subtle changes, understand how new features integrate with existing ones, and recognize patterns that indicate architectural evolution.

3. Interactive Update Session

CRITICAL: Ask project stage question FIRST to assess if priorities have changed:

• Use lettered/numbered options for easy response
• Focus on what has changed and why
• Gather context for accurate updates

4. Update Project Configuration

If project stage or priorities have changed:

• Update .claude/rules/3-project-status.mdc
• Adjust DO/DON'T lists for new priorities
• Document any stage transitions

5. Sync Document

Update the document incrementally:

• Preserve accurate existing content
• Add new sections only when necessary
• Update outdated information
• Maintain consistent tone and structure

6. Save Updated Document

• Backup suggestion if major changes
• Overwrite existing 1-app-design-document.mdc
• Note what was updated

Required Questions Template

🎯 CRITICAL: Project Evolution Assessment (Ask First!)

1. Has your project stage evolved since the last update?

a) Same Stage - Still in [current stage], just adding features
b) Stage Evolution - Moved from [current] to next stage
c) Major Pivot - Significant change in direction or purpose
d) Help Me Assess - Let's review current state together

2. Have your development priorities changed?

Based on your current stage, are these still your priorities?

[Show current DO/DON'T lists from .claude/rules/3-project-status.mdc]

a) Same Priorities - These still reflect our focus
b) Adjusted Priorities - Some changes needed (please specify)
c) New Focus Areas - Different priorities based on learnings
d) Stage-Based Change - Priorities changed due to stage evolution

📊 Change Identification Questions

3. What major features have been added?

Please describe any significant new capabilities, modules, or user-facing features added since the last update.

4. Have any core user flows changed?

a) Authentication/Authorization - Login, permissions, security
b) Main User Journey - Primary application workflow
c) Data Management - How users create/edit/delete data
d) Integration Points - External service connections
e) None/Minor Only - No significant flow changes

5. What has been removed or deprecated?

List any features, integrations, or capabilities that have been removed or are being phased out.

6. Have you integrated new external services?

a) Payment Processing - Stripe, PayPal, etc.
b) Communication - Email, SMS, notifications
c) Analytics/Monitoring - Tracking, logging services
d) AI/ML Services - LLMs, image processing, etc.
e) Other - Please specify
f) None - No new integrations

🚀 Future Direction Questions

7. How has user feedback influenced changes?

Describe any significant pivots or adjustments made based on user feedback or usage patterns.

8. What are your updated success metrics?

Have your KPIs or success measurements changed? Current focus:

• User growth targets?
• Revenue goals?
• Engagement metrics?
• Performance benchmarks?

9. What's the next major milestone?

a) Feature Release - Specific new capability
b) Scale Milestone - User/revenue target
c) Technical Goal - Performance, security, architecture
d) Business Goal - Partnerships, funding, market expansion

Update Strategy

Incremental Updates

• Preserve: Keep accurate existing content
• Enhance: Add new information to existing sections
• Replace: Update outdated or incorrect information
• Remove: Mark deprecated features appropriately

Change Documentation

• New Features: Add to relevant feature categories
• Modified Flows: Update user journey descriptions
• Architecture Changes: Reflect in system architecture section
• Business Evolution: Update goals and success metrics

Consistency Maintenance

• Keep the same professional, accessible tone
• Maintain technology-agnostic descriptions
• Focus on WHAT not HOW
• Preserve document structure

Document Update Areas

Always Review:

1. Introduction

   • Update if purpose or audience has shifted
   • Reflect any pivot in value proposition

2. Core Features

   • Add new feature categories if needed
   • Update existing features with enhancements
   • Mark removed features as deprecated

3. User Experience

   • Update user journeys with new flows
   • Add new user personas if applicable
   • Reflect UI/UX improvements

4. System Architecture

   • Add new integrations
   • Update data flow diagrams
   • Reflect new security patterns

5. Business Logic

   • Update rules and workflows
   • Reflect new validation requirements
   • Document new business constraints

6. Future Considerations

   • Update roadmap based on progress
   • Add new planned features
   • Reflect lessons learned

Execution Steps

1. Start with Analysis

# Check when document was last updated
stat -f "%Sm" .claude/rules/1-app-design-document.mdc

# Review recent commits for feature changes
git log --oneline --since="30 days ago" | head -20

Think deeply about: "What has fundamentally changed in this application? How have new features altered the original vision? What patterns indicate architectural evolution?"

2. Interactive Q&A

• MUST ASK PROJECT STAGE FIRST
• Present all questions clearly
• Wait for complete responses

3. Update Project Status (if needed)

If stage or priorities changed, update both:

# In `.claude/rules/3-project-status.mdc`

## Project Status

**Current Stage**: [New Stage]

### DO Care About (Production-Ready Foundation)

[Updated priorities]

### DO NOT Care About (Skip for Velocity)

[Updated items to skip]

4. Sync Document

• Make targeted updates
• Preserve document quality
• Add version note if helpful:

<!-- Last updated: [date] - Major changes: [summary] -->

5. Save and Backup

# Optional: Create backup
cp .claude/rules/1-app-design-document.mdc .claude/rules/1-app-design-document.backup.mdc

# Save updated document
# Overwrite .claude/rules/1-app-design-document.mdc

Key Principles

DO:

• Preserve Quality: Maintain document's professional tone
• Incremental Updates: Don't rewrite unnecessarily
• Clear Changes: Make updates obvious and well-integrated
• User Focus: Keep emphasis on user value
• Stage Awareness: Align with current project maturity

DON'T:

• Complete Rewrite: Unless fundamentally pivoted
• Technical Details: Maintain high-level focus
• Break Structure: Keep established organization
• Lose History: Preserve context of major decisions
• Skip Analysis: Always understand current state first

Output

• Format: Markdown (.mdc)
• Location: .claude/rules/
• Filename: 1-app-design-document.mdc (overwrites)
• Backup: Suggest if major changes

Final Checklist

1. ✅ Read existing document completely
2. ✅ Analyze codebase changes thoroughly
3. ✅ Ask project stage question FIRST
4. ✅ Update .claude/rules/3-project-status.mdc if stage/priorities changed
5. ✅ Make incremental, targeted updates
6. ✅ Preserve document quality and tone
7. ✅ Suggest backup for major changes
8. ✅ Consider 2-tech-stack.mdc updates if needed