🚨 HIGH: Auto-documentation hits rate limits and crashes git hooks

[alicoding]

🐛 Problem Description

Auto-documentation generation hits ElectronHub API rate limits during git commits, causing timeouts and failed commits.

# What happens during git commit:
git commit -m "message"
# → Triggers pre-commit hook
# → Runs PropertyGraphIndex generation
# → Hits 500 errors from ElectronHub
# → Commit times out after 2 minutes

🎯 Expected Behavior

• Documentation generation respects API rate limits
• Git commits complete successfully
• Incremental updates work after first generation
• Fallback behavior when API unavailable

🔍 Root Cause Analysis

• src/core/auto_docs.py makes dozens of API calls without rate limiting
• No exponential backoff or retry strategy
• PropertyGraphIndex entity extraction is API-intensive
• Git hooks block on documentation generation

📋 Definition of Ready (DoR)

• Rate limiting errors reproduced
• Git commit timeout documented
• PropertyGraphIndex persistence implemented (helps reduce API calls)
• Impact on user workflow identified

✅ Definition of Done (DoD)

• Rate limiting with exponential backoff implemented
• Maximum retry attempts configured
• Timeout configuration for auto-documentation
• Graceful degradation when API unavailable
• Persistent storage prevents rebuilding from scratch
• Git hooks don't block on documentation failures
• Configuration option to disable auto-docs
• Async documentation generation option
• Integration test for rate limiting scenarios
• Manual testing with rate-limited API

🔥 Impact

• HIGH - Blocks normal development workflow
• Git commits become unreliable
• Documentation generation unreliable
• User frustration with timeouts

📚 References

• ElectronHub API rate limiting documentation
• src/core/auto_docs.py - PropertyGraphIndex usage
• LlamaIndex rate limiting best practices

🧪 Test Scenarios

1. Trigger rate limit → verify graceful handling
2. API unavailable → verify fallback behavior
3. Large codebase → verify incremental updates work
4. Git commit → verify doesn't timeout

🏷️ Labels

bug, rate-limiting, api, production