/visualize

allowed-tools: Read, Grep, Bash(fd:*), Bash(rg:*), Bash(bat:*), Bash(jq:*), Bash(git:*), Bash(gdate:*), Write, Task
name: "Visualize"
description: "Generate explanatory diagrams from code and architecture analysis"
author: "wcygan"
tags: ["analyze","data"]
version: "1.0.0"
created_at: "2025-07-14T00:00:00Z"
updated_at: "2025-07-14T00:00:00Z"

/visualize

Context

• Session ID: !`gdate +%s%N`
• Current directory: !`pwd`
• Target: $ARGUMENTS
• Project structure: !`fd . -t d -d 3 | head -10`
• Code files: !`fd "\.(go|rs|ts|js|py|java|cpp|c)$" . | wc -l | tr -d ' ' || echo "0"`
• Config files: !`fd "(docker-compose|kubernetes|k8s)" . -t f | head -5 || echo "No infrastructure configs"`
• Database models: !`rg "(struct|class|interface|type).*\{" --type-add 'code:*.{go,rs,ts,js,py,java}' -t code | head -5 || echo "No models found"`
• Git status: !`git status --porcelain | head -5 || echo "Not a git repository"`
• Documentation: !`fd "docs|documentation" . -t d | head -3 || echo "No docs directory"`

Your Task

STEP 1: Initialize Visualization Session

• Create session state file: /tmp/visualize-$SESSION_ID.json
• Initialize analysis registry and diagram queue
• Setup output directory: docs/diagrams/
• Determine visualization scope from $ARGUMENTS

STEP 2: Analyze Target and Determine Diagram Types

IF $ARGUMENTS contains specific function/method:

• Focus on code flow visualization
• Generate function flowcharts
• Analyze control flow and decision points

ELSE IF $ARGUMENTS contains database/model patterns:

• Generate Entity Relationship Diagrams
• Map table relationships and constraints
• Analyze schema dependencies

ELSE IF $ARGUMENTS contains infrastructure configs:

• Create system architecture diagrams
• Map service dependencies
• Generate deployment topology

ELSE IF $ARGUMENTS contains API/handler patterns:

• Generate sequence diagrams
• Map request/response flows
• Analyze service interactions

ELSE IF $ARGUMENTS is directory or broad scope:

• Use extended thinking to determine optimal visualization strategy
• Consider sub-agent delegation for large codebases:
• Agent 1: Code flow analysis
• Agent 2: Database schema mapping
• Agent 3: System architecture discovery
• Agent 4: API interaction analysis
• Generate comprehensive diagram suite

STEP 3: Execute Analysis and Generation

FOR EACH diagram type identified:

• Analyze relevant code patterns
• Extract relationships and dependencies
• Generate Mermaid.js diagram syntax
• Create markdown file with embedded diagram
• Add interactive elements and complexity annotations

STEP 4: Output and Documentation

• Save diagrams to docs/diagrams/ directory
• Create index file linking all generated diagrams
• Add source links and explanatory text
• Update session state with completion status

Diagram Types Generated:

1. Code Flow Visualization

Analyzes function and method logic to create flowcharts:

**Function Analysis:**

// Example Go function
func ProcessPayment(userID string, amount float64, paymentMethod string) (*Payment, error) {
    user, err := GetUser(userID)
    if err != nil {
        return nil, fmt.Errorf("user not found: %w", err)
    }
    
    if user.Balance < amount {
        return nil, errors.New("insufficient funds")
    }
    
    if paymentMethod == "credit_card" {
        if !ValidateCreditCard(user.CreditCard) {
            return nil, errors.New("invalid credit card")
        }
    }
    
    payment := &Payment{
        UserID: userID,
        Amount: amount,
        Method: paymentMethod,
        Status: "pending",
    }
    
    if err := SavePayment(payment); err != nil {
        return nil, fmt.Errorf("failed to save payment: %w", err)
    }
    
    if err := ProcessExternalPayment(payment); err != nil {
        payment.Status = "failed"
        SavePayment(payment)
        return nil, fmt.Errorf("external payment failed: %w", err)
    }
    
    payment.Status = "completed"
    SavePayment(payment)
    
    return payment, nil
}

**Generated Flowchart:**

flowchart TD
    A[Start: ProcessPayment] --> B[Get User by ID]
    B --> C{User Found?}
    C -->|No| D[Return Error: User Not Found]
    C -->|Yes| E{Sufficient Balance?}
    E -->|No| F[Return Error: Insufficient Funds]
    E -->|Yes| G{Payment Method == Credit Card?}
    G -->|Yes| H[Validate Credit Card]
    H --> I{Valid Credit Card?}
    I -->|No| J[Return Error: Invalid Credit Card]
    I -->|Yes| K[Create Payment Object]
    G -->|No| K
    K --> L[Save Payment to Database]
    L --> M{Save Successful?}
    M -->|No| N[Return Error: Save Failed]
    M -->|Yes| O[Process External Payment]
    O --> P{External Payment Successful?}
    P -->|No| Q[Update Status to Failed]
    Q --> R[Save Updated Payment]
    R --> S[Return Error: External Payment Failed]
    P -->|Yes| T[Update Status to Completed]
    T --> U[Save Updated Payment]
    U --> V[Return Successful Payment]
    
    style A fill:#e1f5fe
    style D fill:#ffebee
    style F fill:#ffebee
    style J fill:#ffebee
    style N fill:#ffebee
    style S fill:#ffebee
    style V fill:#e8f5e8

2. Database Schema Visualization

Analyzes database schemas and models to create Entity Relationship Diagrams:

**Go Struct Analysis:**

type User struct {
    ID        int64     `db:"id" json:"id"`
    Email     string    `db:"email" json:"email"`
    Name      string    `db:"name" json:"name"`
    CreatedAt time.Time `db:"created_at" json:"created_at"`
    Profile   *Profile  `db:"-" json:"profile,omitempty"`
    Orders    []Order   `db:"-" json:"orders,omitempty"`
}

type Profile struct {
    ID     int64  `db:"id" json:"id"`
    UserID int64  `db:"user_id" json:"user_id"`
    Bio    string `db:"bio" json:"bio"`
    Avatar string `db:"avatar" json:"avatar"`
}

type Order struct {
    ID       int64     `db:"id" json:"id"`
    UserID   int64     `db:"user_id" json:"user_id"`
    Total    float64   `db:"total" json:"total"`
    Status   s