DESIGN.md Synchronization Check

Verify that DESIGN.md accurately reflects the current codebase architecture.

Current Directory Structure

!ls -la internal/ | grep '^d'

DESIGN.md Directory Section

!sed -n '/^## Directory Structure/,/^## /p' DESIGN.md | head -50

Critical File References from DESIGN.md

!grep -oE 'internal/[a-z/]+.go:[0-9]+-[0-9]+' DESIGN.md | sort -u

Recent Changes Since Last DESIGN.md Update

!git log --since="$(git log -1 --format=%ai DESIGN.md 2>/dev/null || echo '1 month ago')" --name-only --oneline -- 'internal/**/*.go' | grep -E '^internal/' | sort -u

Current Package Import Graph

!go list -f '{{.ImportPath}}: {{join .Imports ", "}}' ./internal/... 2>/dev/null | grep 'lazyworktree/internal' | head -30

DESIGN.md Metadata

!head -20 DESIGN.md | grep -E '(Last updated|Version)'

Theme Fields Documented vs Actual

!echo "=== Documented theme fields ===" && grep -A 20 'type Theme struct' DESIGN.md | grep -oE '^\s+[A-Z][a-zA-Z]+' | wc -l && echo "=== Actual theme fields ===" && grep -A 30 'type Theme struct' internal/app/theme.go | grep -oE '^\s+[A-Z][a-zA-Z]+' | wc -l

Analysis Instructions

Based on the data above, check for:

1. Directory Structure Drift

• Are there new directories under internal/ not documented in DESIGN.md?

• Have documented directories been removed or renamed?

• Compare the actual directory listing with the documented structure section

2. Critical File References

• Extract all file:line-range references from DESIGN.md (e.g., app.go:77-210 )

• For each reference:

• Verify the file still exists at that path

• Check if line numbers still point to the documented code section

• If lines have shifted due to refactoring, report the new correct line numbers

• Report any broken references or significant drift

3. Recent Architectural Changes

• Review files changed since the last DESIGN.md update

• Identify if changes affect documented abstractions:

• BubbleTea Model/Update/View pattern

• Git service semaphore implementation

• Screen manager stack

• Theme system

• Config cascade

• Flag changes to critical files that may require DESIGN.md updates

4. Import Graph Consistency

• Compare current package imports with the documented dependency graph

• Flag new internal dependencies not mentioned in DESIGN.md

• Flag removed dependencies still documented

• Check for circular dependencies (which violate documented patterns)

5. Theme System Accuracy

• Verify the count of theme fields matches between documentation and actual code

• If counts differ, identify which fields are missing from documentation

6. Staleness Check

• Report if DESIGN.md hasn't been updated in >90 days

• Suggest updating the "Last updated" date if structural changes were made

Report Format

Provide output as:

✅ Up to Date

• List specific aspects that are still accurate and synchronized

⚠️ Needs Minor Updates

• Line number corrections (e.g., app.go:77-210 → app.go:87-220 )

• New directories to add to documentation

• Minor import graph changes

• Theme field count discrepancies

🔴 Needs Major Updates

• New abstractions or components not documented

• Documented components removed or significantly changed

• Architecture decisions that have changed

• Broken file references

📝 Recommended Actions

• Specific edits with DESIGN.md line numbers to update

• New sections to add (with suggested content outline)

• Sections to remove or rewrite

• Line number corrections for all file references

Usage Workflow

When to Invoke /design-sync

Proactive triggers (before committing):

• Added new package under internal/

• Refactored critical files (app.go, service.go, model.go, etc.)

• Changed architecture pattern (Model-Update-View, semaphore, etc.)

• Added new screen type or theme field

• Modified config cascade or precedence rules

Periodic triggers:

• Quarterly maintenance review

• Before major release

• After merging large architectural PRs

• When DESIGN.md feels outdated

Recommended Workflow

1. Make architectural changes

2. Run design-sync skill

/design-sync

3. Review output for needed updates

4. Update DESIGN.md based on recommendations

5. Update "Last updated" date in DESIGN.md

6. Re-run to verify

/design-sync # Should now show ✅ Up to Date

7. Commit changes together