constellation-analyzer/docs/TEMPORAL_QUICK_START.md

Temporal & Scenario Analysis - Quick Start Guide

What This Is (And Isn't)

This IS:

• A tool for temporal evolution analysis (how constellations change over time)
• A tool for scenario exploration (exploring alternative futures)
• A comparison and analysis framework (visualizing differences)
• A storytelling platform (presenting network dynamics)

This Is NOT:

• Version control for your work (not Git for graphs)
• Undo/redo functionality (that's separate)
• Collaborative editing (that's separate)
• A backup system (save your documents!)

---

Core Concepts

1. States

A state is a snapshot of your constellation at a specific moment in time or scenario. Think of it as a photograph of your network.

Two types:

• Temporal States: Time-based snapshots (e.g., "Q1 2023", "Session 5", "Post-Merger")
• Scenario States: Alternative futures (e.g., "Strategy A", "Pessimistic Case", "Option 2")

2. Timelines

A timeline is an ordered sequence of temporal states showing evolution over time.

Example Timeline:

2020 → 2021 → 2022 → 2023 → Projected 2024

3. Scenarios

A scenario is a branch from a specific point to explore "what if" alternatives.

Example Scenario Tree:

Current State
    ├→ Strategy A → Quarter 2 → Quarter 3
    ├→ Strategy B → Quarter 2
    └→ Strategy C → Quarter 2 → Quarter 3 → Quarter 4

4. Comparisons

Comparison shows the differences between any two states with visual highlighting:

• Green: Added actors/relations
• Red: Removed actors/relations
• Yellow: Modified actors/relations

5. Actor Journeys

An actor journey tracks a specific actor across multiple states to see how they evolve.

---

Common Use Cases

Use Case 1: Historical Analysis

Scenario: You want to show how a team's structure evolved over a year.

Steps:

1. Create states for each quarter: Q1, Q2, Q3, Q4
2. Set temporal metadata (dates or sequence)
3. Add these states to a timeline
4. Use timeline scrubber to navigate through time
5. Compare Q1 vs Q4 to see total change

Result: You can present the evolution story and identify key inflection points.

---

Use Case 2: Therapeutic Progress

Scenario: A therapist tracking a patient's family constellation across sessions.

Steps:

1. Capture state after each session: "Session 1", "Session 5", "Session 10"
2. Track specific family members (actors) across sessions
3. Compare early vs. late sessions to show progress
4. Create animation showing relationship evolution

Result: Visual evidence of therapeutic progress and relationship changes.

---

Use Case 3: Strategic Planning

Scenario: Exploring three different organizational restructuring options.

Steps:

1. Capture current state: "Current Org Structure"
2. Create three scenario branches:
   • "Option A: Consolidation"
   • "Option B: Decentralization"
   • "Option C: Hybrid"
3. Develop each scenario with different actor configurations
4. Compare all three scenarios side-by-side
5. Present findings to leadership

Result: Clear visual comparison of strategic alternatives.

---

Use Case 4: Project Evolution

Scenario: Tracking how a project's stakeholder network changes from kickoff to completion.

Steps:

1. Create timeline: "Kickoff" → "Planning" → "Execution" → "Closure"
2. Capture state at each phase
3. Track key stakeholders across all phases
4. Generate actor journey reports for executives
5. Animate the evolution for presentation

Result: Compelling narrative of project dynamics and stakeholder engagement.

---

Key Features

Feature Matrix

Feature	Phase	Priority	Use Case
Capture State	1	HIGH	Create snapshots of current graph
Load State	1	HIGH	Switch between different states
Timeline View	2	HIGH	Navigate temporal sequences
Temporal Metadata	2	HIGH	Label states with dates/periods
Compare States	3	HIGH	Side-by-side comparison
Visual Diff	3	HIGH	Highlight changes on graph
Change Summary	3	HIGH	Statistics and change lists
Scenario Branching	4	MEDIUM	Create alternative futures
Scenario Tree	4	MEDIUM	Visualize branches
Actor Journey	5	MEDIUM	Track actors across states
State Animation	6	MEDIUM	Smooth transitions
Presentation Mode	6	MEDIUM	Full-screen slideshow
Semantic Search	7	MEDIUM	Find states by description
Pattern Recognition	7	MEDIUM	Identify similar states

---

User Interface Overview

1. Main Toolbar

┌─────────────────────────────────────────────────────────┐
│ [File] [Edit] [View] [States] [Help]                   │
│                                                          │
│ Current State: Q3 2023 ▼  [📸 Capture] [🔍 Compare]   │
└─────────────────────────────────────────────────────────┘

New Controls:

• State Selector Dropdown: Quick switch between states
• Capture Button: Create new state from current graph
• Compare Button: Open comparison view

2. Bottom Timeline Panel

┌─────────────────────────────────────────────────────────┐
│ Timeline: Project Evolution        [+] State   [≡] View │
├─────────────────────────────────────────────────────────┤
│                                                          │
│  ●═══●═══●═══●═══●════┬══●═══●                        │
│  Q1  Q2  Q3  Q4  Now  │  S1  S2  (Branch A)           │
│ 2023 2023 2023 2023   │                                │
│                        └──●═══●    (Branch B)          │
│                           S1  S2                        │
│                                                          │
│  [◀] [▶] Navigate  [⏯] Animate  [⚖] Compare           │
└─────────────────────────────────────────────────────────┘

Features:

• Horizontal timeline with state markers
• Vertical scenario branches
• Navigation controls
• Animation playback
• Quick compare access

3. Right Panel (When State Selected)

┌─────────────────────────────────────┐
│ State: Q3 2023                      │
├─────────────────────────────────────┤
│ Type: Temporal                       │
│ Date: 2023-09-30                     │
│ Sequence: 3 of 4                     │
│                                      │
│ Actors: 12                           │
│ Relations: 18                        │
│                                      │
│ Notes:                               │
│ "Significant restructuring after    │
│  merger announcement..."             │
│                                      │
│ [Edit Metadata] [Compare] [Delete]  │
│                                      │
│ Navigation:                          │
│ ← Q2 2023 | Q4 2023 →               │
└─────────────────────────────────────┘

---

Keyboard Shortcuts

Shortcut	Action
Ctrl+Shift+S	Capture current state
Ctrl+Shift+T	Open timeline panel
Ctrl+Shift+C	Open comparison view
← / →	Navigate timeline (when focused)
Space	Play/pause animation (when focused)
Ctrl+J	View actor journeys
Ctrl+Shift+P	Presentation mode

---

Workflow Examples

Workflow 1: Creating a Temporal Sequence

1. Start with your current graph
   └→ [Capture State] → "January 2025"

2. Make changes to graph (add/remove/modify actors)
   └→ [Capture State] → "February 2025"

3. Continue for each time period
   └→ [Capture State] → "March 2025"

4. View timeline panel
   └→ See all states in sequence
   └→ Use scrubber to navigate

5. Compare any two states
   └→ [Compare] → Select "January" vs "March"
   └→ See visual diff

6. Animate evolution
   └→ [Play] → Watch smooth transition

Workflow 2: Exploring Scenarios

1. Load the state you want to branch from
   └→ Select "Current State" from dropdown

2. Create scenario branch
   └→ [States Menu] → [Create Scenario Branch]
   └→ Name: "Strategy A"
   └→ Description: "Aggressive expansion"
   └→ Assumptions: ["Funding secured", "Market growth"]

3. Modify graph for this scenario
   └→ Add new actors, relations

4. Capture states along this scenario
   └→ [Capture State] → "Strategy A - Q2"
   └→ [Capture State] → "Strategy A - Q3"

5. Return to branching point
   └→ Select "Current State" again

6. Create alternative scenario
   └→ [Create Scenario Branch] → "Strategy B"
   └→ Different modifications

7. Compare scenarios
   └→ [Compare] → "Strategy A - Q3" vs "Strategy B - Q3"

Workflow 3: Actor Journey Analysis

1. Ensure you have multiple states captured

2. Select an actor on the graph
   └→ Click actor node

3. View actor journey
   └→ [Right Panel] → [View Journey]
   OR
   └→ [Ctrl+J] → Select actor from list

4. Journey viewer shows:
   └→ All states where actor appears
   └→ Property changes over time
   └→ Relationship changes
   └→ Position evolution

5. Export actor report
   └→ [Export Journey] → PDF or JSON

---

Best Practices

1. State Naming

• Use descriptive labels: "Q3 2023 Post-Restructuring" not just "State 3"
• Include context: "Strategy A: Optimistic Scenario - Year 2"
• Be consistent: Use same format for similar states

2. Timeline Organization

• One timeline per narrative: Don't mix different stories
• Logical sequencing: Ensure temporal order makes sense
• Manageable length: Consider breaking very long timelines

3. Scenario Branching

• Clear branching points: Choose meaningful divergence points
• Document assumptions: Always explain what makes scenarios different
• Parallel development: Develop scenario branches to similar time horizons
• Color coding: Use colors to distinguish branches visually

4. Comparison Analysis

• Compare meaningful pairs: Adjacent states or alternative scenarios
• Focus on key changes: Filter by change type if needed
• Document insights: Add notes about significant differences
• Export reports: Save comparison results for reference

5. Presentation

• Start with context: Begin with overview state
• Show progression: Use animation for temporal sequences
• Highlight key changes: Use comparison view for dramatic differences
• Tell a story: Sequence states to create narrative flow

---

Common Pitfalls to Avoid

1. Too Many States

Problem: Creating state for every tiny change clutters timeline Solution: Capture states at significant milestones only

2. Inconsistent Labeling

Problem: "Jan", "February 2023", "2023-03-15" in same timeline Solution: Choose format and stick with it

3. Forgetting Metadata

Problem: States labeled "State 1", "State 2" with no context Solution: Always add description, date, or sequence info

4. Not Using Comparison

Problem: Just switching between states without analyzing differences Solution: Use comparison view to identify and document changes

5. Orphaned Scenarios

Problem: Creating scenario branches but not developing them Solution: Either fully develop scenarios or delete incomplete branches

6. Mixing Temporal and Scenario

Problem: Putting scenarios and time progression in same timeline Solution: Keep temporal timelines and scenario branches separate

---

Performance Tips

For Large Graphs (100+ actors)

• Capture states selectively (not every change)
• Use diff caching (automatic in ChromaDB integration)
• Limit animation quality for smooth playback
• Consider pagination for very long timelines

For Many States (50+ states)

• Organize into multiple timelines by theme
• Use semantic search to find relevant states
• Archive old/unused states
• Export and backup state data regularly

---

Integration with Existing Features

Document System

• Each document can have its own state history
• States are document-specific (not shared across documents)
• Duplicate document includes all states

Export/Import

• Export document includes all states
• Import preserves state structure
• Can export specific timeline or scenario branch

Undo/Redo

• Undo/redo works on current working graph
• Does NOT affect captured states
• Capturing state does not add to undo history

---

Next Steps

Phase 1: Getting Started (Week 1-2)

1. Implement basic state capture and loading
2. Create simple state selector
3. Test with example document

Phase 2: Temporal Features (Week 3-4)

1. Build timeline panel UI
2. Add temporal metadata editor
3. Implement timeline navigation

Phase 3: Comparison (Week 5-6)

1. Develop diff algorithm
2. Create comparison view UI
3. Add visual diff overlay

Continue with remaining phases as outlined in main implementation plan

---

Questions to Consider

Before implementing, discuss:

1. State Limit: Should we limit number of states per document?
2. Storage: IndexedDB for states or localStorage? (Recommend IndexedDB)
3. Persistence: Auto-save states or explicit save?
4. Naming: Should users be prompted to name states or auto-generate?
5. Default State: What happens when document opens - load latest state or working graph?
6. Branching UI: Tree view or timeline with vertical branches?
7. Animation: Default animation duration and easing function?
8. Export: Include states in normal JSON export or separate?

---

Resources

• Main Implementation Plan: See TEMPORAL_SCENARIO_IMPLEMENTATION_PLAN.md for complete technical details
• Type Definitions: /src/types/temporal.ts (to be created)
• Store Implementation: /src/stores/stateStore.ts (to be created)
• UI Components: /src/components/TemporalAnalysis/ (to be created)

---

Success Criteria

You'll know the implementation is successful when users can:

1. Capture a state in < 3 clicks
2. Navigate timeline intuitively
3. Immediately see differences when comparing states
4. Create and understand scenario branches
5. Animate evolution smoothly
6. Find specific states quickly (with ChromaDB)
7. Present findings effectively to stakeholders

---

Support

For questions about this implementation:

• Review the main implementation plan for technical details
• Check type definitions for data structures
• Examine workflow examples for common patterns
• Test with real use cases early and often

Remember: This is about storytelling and analysis, not version control!