GEMINI.md - Gira Usage Guide for Gemini

This guide helps Gemini AI agents understand how to use Gira for project management and ticket tracking. Gemini's large context window makes it ideal for analyzing project-wide patterns and managing complex tasks.

🎯 What is Gira?

Gira is a Git-native project management tool that stores all project data as JSON files in .gira/, enabling version control for project management data and seamless AI collaboration.

🔍 Leveraging Gemini's Strengths with Gira

Large-Scale Project Analysis

Gemini's large context window is perfect for analyzing entire project structures and ticket relationships:

1. Project-Wide Ticket Analysis

# Export all tickets for comprehensive analysis
gira export tickets --format json > all-tickets.json

# View all tickets with their relationships
gira ticket list --format json | jq '.'

# Analyze ticket patterns and dependencies
gira epic list --show-progress

2. Batch Ticket Operations

# Process multiple tickets based on criteria
gira ticket list --status todo --priority high | \
  while read -r ticket; do
    gira ticket show "$ticket"
  done

# Find related tickets across epics
for epic in $(gira epic list --format json | jq -r '.[].id'); do
    echo "Epic: $epic"
    gira epic show "$epic"
done

3. Comprehensive Progress Analysis

# Generate project statistics
gira ticket list --format json | \
  jq '[.[] | select(.status == "done")] | length' # Count completed tickets

# Analyze velocity across sprints
gira sprint list --format json | \
  jq '.[] | {name: .name, completed: .completed_points}'

📋 Essential Gira Commands for Gemini

Viewing Project Information

# View the kanban board with all tickets
gira board

# List all tickets with detailed information
gira ticket list

# View epics and their progress
gira epic list --show-progress

# Check sprint status and velocity
gira sprint list

Managing Complex Tasks

# View all tickets in an epic
gira epic show EPIC-001

# Create subtasks for large features
gira ticket create "Implement component A" --type task --epic EPIC-001
gira ticket create "Implement component B" --type task --epic EPIC-001

# Batch update tickets
for ticket in $(gira ticket list --status todo --assignee me --format json | jq -r '.[].id'); do
    gira ticket move "$ticket" "in progress"
done

🚀 Gemini-Specific Workflows

1. Multi-Ticket Analysis Workflow

# Export tickets for analysis
gira export tickets --format json > tickets.json

# Analyze patterns in ticket data
gira ticket list --format json | \
  jq 'group_by(.type) | map({type: .[0].type, count: length})'

# Find tickets without epics
gira ticket list --format json | \
  jq '.[] | select(.epic == null) | .id'

2. Progress Tracking Across Epics

# Generate epic progress report
for epic in $(gira epic list --format json | jq -r '.[].id'); do
    echo "Epic: $epic"
    gira epic show "$epic" | grep -E "(Progress|Status)"
done

# Track sprint velocity
gira sprint list --format json | \
  jq 'map({sprint: .name, velocity: .completed_points})'

3. Dependency Analysis

# Find blocked tickets
gira ticket list --status blocked

# Analyze ticket relationships
gira ticket list --format json | \
  jq '.[] | select(.blocked_by != null) | {id: .id, blocked_by: .blocked_by}'

# Create dependency report
gira comment add TICKET-ID << EOF
Dependency Analysis:
- Blocked tickets: [list]
- Critical path items: [list]
- Recommended unblocking order: [list]
EOF

📊 Using Gira for Project Analytics

Generate Reports

# Ticket distribution by status
gira ticket list --format json | \
  jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Priority analysis
gira ticket list --format json | \
  jq 'group_by(.priority) | map({priority: .[0].priority, count: length})'

# Assignee workload
gira ticket list --format json | \
  jq 'group_by(.assignee) | map({assignee: .[0].assignee, tickets: length})'

🔧 Best Practices for Large-Scale Gira Operations

1. Batch Processing

# Process tickets in batches
gira ticket list --status todo --format json | \
  jq -r '.[].id' | \
  xargs -I {} gira ticket update {} --label "needs-review"

2. Progress Documentation

# Add comprehensive progress update
gira comment add TICKET-ID << EOF
Progress Update:
- Analyzed X tickets
- Identified Y patterns
- Created Z new subtasks
- Next steps: [list actions]
EOF

3. Automated Ticket Creation

# Create multiple related tickets
for component in "auth" "api" "database" "frontend"; do
    gira ticket create "Refactor $component module" \
      --type task \
      --epic EPIC-001 \
      --priority medium
done

🎯 Task Types Well-Suited for Gemini

With its large context window, Gemini excels at:

1. Project-Wide Analysis: Understanding relationships across all tickets and epics
2. Batch Operations: Processing multiple tickets simultaneously
3. Pattern Recognition: Identifying trends in ticket data
4. Comprehensive Reporting: Generating detailed project analytics
5. Migration Planning: Analyzing large sets of tickets for reorganization
6. Workflow Optimization: Suggesting improvements based on historical data

📈 Working with Gira Data

Export and Analysis

# Export all project data
gira export all --output project-backup/

# Export specific data types
gira export tickets --format json > tickets.json
gira export epics --format json > epics.json
gira export sprints --format json > sprints.json

# Analyze exported data
cat tickets.json | jq 'length' # Total ticket count
cat epics.json | jq '.[] | {id: .id, progress: .progress}'

Import Operations

# Import tickets from JSON
gira import tickets tickets.json

# Import from CSV
gira import tickets tickets.csv --format csv

💡 Gemini-Specific Tips

Using JSON Output

Gemini works well with structured data:

# Get all ticket data in JSON
gira ticket list --format json > all-tickets.json

# Get specific fields
gira ticket list --format json | \
  jq '.[] | {id: .id, title: .title, status: .status, assignee: .assignee}'

Parallel Processing

# Process multiple tickets in parallel
gira ticket list --status "in progress" --format json | \
  jq -r '.[].id' | \
  parallel -j 4 'gira ticket show {}'

Historical Analysis

# Analyze ticket completion patterns
gira ticket list --status done --format json | \
  jq '.[] | select(.completed_at != null) | .completed_at' | \
  sort | uniq -c

🔍 Git Integration with Gira

Finding Related Code Changes

# Find commits related to tickets
git log --grep="Gira:" --oneline

# Find tickets that modified specific files
gira ticket blame src/

# Get detailed blame information
gira ticket blame src/ --json > blame-report.json

Commit Message Integration

# Proper format with Gira ticket
git commit -m "feat(TICKET-123): add bulk processing feature

- Implement batch ticket updates
- Add progress tracking
- Include error handling

Gira: TICKET-123"

🚨 Common Scenarios for Gemini

Large Epic Management

# Analyze epic with many tickets
gira epic show EPIC-001 > epic-details.txt

# Find incomplete tickets in epic
gira ticket list --epic EPIC-001 --format json | \
  jq '.[] | select(.status != "done") | {id: .id, title: .title}'

Sprint Planning

# Analyze unassigned high-priority tickets
gira ticket list --status todo --priority high --assignee none

# Calculate sprint capacity
gira ticket list --sprint SPRINT-001 --format json | \
  jq '[.[] | .story_points // 0] | add'

---

This guide helps Gemini work effectively with Gira's Git-native project management system, leveraging its large context window for comprehensive project analysis.