{"id":29025963,"url":"https://github.com/rootly-ai-labs/rootly-burnout-detector","last_synced_at":"2025-09-05T08:20:06.577Z","repository":{"id":301042597,"uuid":"1007977723","full_name":"Rootly-AI-Labs/Rootly-burnout-detector","owner":"Rootly-AI-Labs","description":"Based on Christina   Maslach's Burnout Inventory research, it   calculates risk scores across emotional   exhaustion, depersonalization, and personal   accomplishment dimensions to enable proactive   well-being interventions.","archived":false,"fork":false,"pushed_at":"2025-06-24T21:02:03.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-24T22:19:28.641Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Rootly-AI-Labs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-24T20:40:59.000Z","updated_at":"2025-06-24T21:02:06.000Z","dependencies_parsed_at":"2025-06-24T22:19:30.262Z","dependency_job_id":"a0405284-3927-4292-b28c-cfdda43f3ce8","html_url":"https://github.com/Rootly-AI-Labs/Rootly-burnout-detector","commit_stats":null,"previous_names":["rootly-ai-labs/rootly-burnout-detector"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Rootly-AI-Labs/Rootly-burnout-detector","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rootly-AI-Labs%2FRootly-burnout-detector","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rootly-AI-Labs%2FRootly-burnout-detector/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rootly-AI-Labs%2FRootly-burnout-detector/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rootly-AI-Labs%2FRootly-burnout-detector/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Rootly-AI-Labs","download_url":"https://codeload.github.com/Rootly-AI-Labs/Rootly-burnout-detector/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Rootly-AI-Labs%2FRootly-burnout-detector/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262003991,"owners_count":23243356,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-26T05:07:10.931Z","updated_at":"2025-06-26T05:07:11.954Z","avatar_url":"https://github.com/Rootly-AI-Labs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rootly Burnout Detector\n\nA data-driven burnout detection system for on-call engineers using Rootly's incident data and Christina Maslach's Burnout Inventory research. The system connects to Rootly's [MCP Server](https://github.com/Rootly-AI-Labs/Rootly-MCP-server/tree/main), enabling secure and efficient data retrieval.\n\n![Rootly Burnout Analysis Dashboard](dashboard-screenshot.png)\n\n## Requirements\n\n- Python 3.12+\n- uv package manager (`brew install uv` or see [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/))\n- Rootly API token\n\n## Quick Start\n\n1. **Setup Environment**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n2. **Configure API Tokens**\n   ```bash\n   cp secrets.env.example secrets.env\n   ```\n   \n   Edit `secrets.env` and add your tokens:\n   ```bash\n   # Required\n   ROOTLY_API_TOKEN=your-rootly-api-token-here\n   \n   # Optional - for GitHub integration\n   GITHUB_TOKEN=ghp_your-github-personal-access-token\n   \n   # Optional - for interactive Q\u0026A mode (add one)\n   OPENAI_API_KEY=sk-your-openai-key-here      # GPT-4\n   ANTHROPIC_API_KEY=sk-ant-your-anthropic-key # Claude\n   HF_TOKEN=hf_your-huggingface-token          # Hugging Face (free)\n   ```\n\n3. **Run Analysis**\n   ```bash\n   # Standard analysis (incident data only)\n   python main.py --days 30\n   \n   # Enhanced analysis with GitHub activity data\n   python main.py --include-github --days 30\n   ```\n\n4. **Interactive Mode (Optional)**\n   ```bash\n   # Requires LLM API key configured in step 2\n   python main.py --days 30 --interactive\n   ```\n\n5. **View Results**\n   ```bash\n   open output/dashboard.html\n   ```\n\n## Configuration\n\n### Token Management\n\nThe Rootly API token is configured in the `secrets.env` file as shown in the Quick Start section above. The token can also be provided via environment variable or command line flag if needed.\n\n### Analysis Settings\n\nEdit `config/config.json` to adjust:\n- Analysis time period (default: 30 days)\n- Burnout risk thresholds\n- Business hours definition\n- Severity weights\n- Output options\n\n### Interactive Mode\n\nFor interactive Q\u0026A mode, set one LLM API key:\n- `OPENAI_API_KEY` - GPT-4 (paid, high quality)\n- `ANTHROPIC_API_KEY` - Claude (paid, high quality)  \n- `HF_TOKEN` - Hugging Face (free tier available)\n\n## GitHub Integration\n\nThe Rootly Burnout Detector can integrate GitHub activity data to provide a more comprehensive burnout assessment by analyzing both incident response patterns and coding work patterns.\n\n### Setup GitHub Integration\n\n1. **Create GitHub Personal Access Token**\n   - Go to GitHub Settings → Developer Settings → Personal Access Tokens → Tokens (classic)\n   - Generate a new token with these scopes:\n     - `repo` (for private repositories)\n     - `public_repo` (for public repositories)\n     - `user:email` (for email correlation)\n\n2. **Configure Token**\n   ```bash\n   # Add to secrets.env\n   GITHUB_TOKEN=ghp_your-github-personal-access-token\n   ```\n\n3. **Configure Organizations**\n   \n   Edit `config/config.json` to specify your GitHub organizations:\n   ```json\n   {\n     \"github_integration\": {\n       \"enabled\": false,\n       \"organizations\": [\"your-org-1\", \"your-org-2\"],\n       \"user_mappings\": {\n         \"engineer@company.com\": \"github-username\"\n       }\n     }\n   }\n   ```\n\n### Usage\n\n```bash\n# Include GitHub data in burnout analysis\npython main.py --include-github --days 30\n\n# Refresh GitHub cache (forces new API calls)\npython main.py --include-github --refresh-github-cache --days 30\n\n# Standard analysis without GitHub data\npython main.py --days 30\n```\n\n### How It Works\n\n1. **User Correlation**: Automatically correlates Rootly users with GitHub accounts by:\n   - Mining commit history for email addresses\n   - Matching email patterns and usernames\n   - Using manual mappings from configuration\n\n2. **Activity Collection**: Gathers 30 days of GitHub activity:\n   - Commits (with timestamp and repository info)\n   - Pull requests (creation and collaboration patterns)\n   - Issues (assignment and resolution)\n\n3. **Burnout Analysis Integration**: Enhances the three Maslach dimensions:\n\n   **Emotional Exhaustion** (+30% GitHub weight):\n   - After-hours commits percentage\n   - Weekend coding activity  \n   - Commit clustering (rapid consecutive commits indicating stress)\n\n   **Depersonalization** (+30% GitHub weight):\n   - Repository switching patterns (scattered focus)\n   - Pull request collaboration rates\n   - Code review participation\n\n   **Personal Accomplishment** (+30% GitHub weight):\n   - Productive commit frequency (sweet spot: 3-8 commits/week)\n   - Pull request creation rates\n   - Repository contribution diversity\n\n### Caching \u0026 Performance\n\n- **Indefinite Caching**: GitHub data is cached in `.github_cache/` directory\n- **Fast Subsequent Runs**: Uses cached data unless `--refresh-github-cache` is specified\n- **Optimized API Usage**: Searches user activity directly instead of scanning repositories\n- **Rate Limit Friendly**: Respects GitHub API limits (5000 requests/hour)\n\n### User Correlation\n\nThe system automatically discovers user correlations by:\n1. **Email Mining**: Extracts email addresses from commit history across organizations\n2. **Pattern Matching**: Matches usernames and email patterns\n3. **Manual Mappings**: Supports explicit user mappings in config for improved accuracy\n\nExample correlation output:\n```\n✅ GitHub correlation: 15/40 users matched (37.5%)\n📝 Add 25 users to config.json user_mappings for better coverage\n```\n\n### Benefits\n\n- **Holistic View**: Combines incident stress with coding work patterns\n- **Early Detection**: Identifies burnout patterns that incident data alone might miss\n- **Work-Life Balance**: Detects after-hours and weekend work patterns\n- **Productivity Insights**: Understands sustainable vs. excessive coding activity\n- **Collaboration Patterns**: Identifies social withdrawal through reduced PR/review activity\n\n### Data Storage\n\nGitHub data is stored in:\n- **Cache**: `.github_cache/activity_{username}_{dates}.json` (gitignored)\n- **Analysis Results**: Integrated into `output/burnout_analysis.json`\n- **Correlation Data**: Email mappings cached for fast subsequent runs\n\n## Project Structure\n\n```\nrootly-burnout-detector/\n├── config/\n│   ├── config.json           # Default configuration\n│   └── config.example.json   # Example configuration\n├── src/\n│   ├── mcp_client.py         # MCP server connection\n│   ├── data_collector.py     # Data extraction from Rootly\n│   ├── burnout_analyzer.py   # Risk calculation engine (with GitHub integration)\n│   ├── dashboard.py          # HTML report generation\n│   ├── github_correlator.py  # User correlation between Rootly and GitHub\n│   ├── github_collector.py   # GitHub activity data collection\n│   ├── interactive_analyzer.py # LLM-powered Q\u0026A interface\n│   └── burnout_tools.py      # Custom smolagents tools\n├── output/\n│   ├── burnout_analysis.json # Analysis results (includes GitHub data)\n│   ├── dashboard.html        # Interactive dashboard\n│   ├── summary_report.txt    # Text summary\n│   └── individual_reports/   # Per-user detailed reports\n├── .github_cache/            # GitHub data cache (git-ignored)\n│   ├── activity_*.json       # Cached user activity data\n│   └── email_mapping.json    # User correlation cache\n├── secrets.env               # API tokens (git-ignored)\n├── secrets.env.example       # Example secrets file\n├── requirements.txt          # Python dependencies\n└── main.py                  # Entry point\n```\n\n## Features\n\n- **Timezone-aware after-hours detection** (9 AM - 5 PM per engineer's timezone)\n- **Maslach Burnout Inventory inspired scoring** (Emotional Exhaustion, Depersonalization, Personal Accomplishment)\n- **GitHub Integration** (optional) - Combines incident data with coding activity patterns\n- **Automatic user correlation** between Rootly and GitHub accounts\n- **Individual and team-level analysis**\n- **Configurable thresholds and parameters**\n- **Interactive HTML dashboard**\n- **JSON export for further analysis**\n- **Intelligent caching** for fast subsequent analysis runs\n\n\n## Burnout Metrics\n\n### Emotional Exhaustion Indicators\n**Incident Data:**\n- High incident frequency\n- Extended incident durations  \n- Frequent after-hours responses\n- Short recovery time between incidents\n\n**GitHub Data** (when `--include-github` is used):\n- After-hours commits percentage\n- Weekend coding activity\n- Commit clustering (rapid consecutive commits)\n\n### Depersonalization Indicators\n**Incident Data:**\n- Decreased collaboration\n- Increased escalation rates\n- Reduced post-incident participation\n\n**GitHub Data** (when `--include-github` is used):\n- Repository switching patterns (scattered focus)\n- Reduced pull request creation\n- Lower code review participation\n\n### Personal Accomplishment Indicators\n**Incident Data:**\n- Resolution success rates\n- Time to resolution improvements\n- Knowledge sharing participation\n\n**GitHub Data** (when `--include-github` is used):\n- Productive commit frequency (optimal: 3-8 commits/week)\n- Pull request collaboration rates\n- Consistent repository contributions\n\n## Output\n\n- **Individual Risk Scores**: Per-engineer burnout risk (0-10 scale)\n- **Team Aggregations**: Department/team level insights\n- **Trend Analysis**: Changes over time\n- **Actionable Recommendations**: Suggested interventions\n\n## MCP Server\n\nThe tool uses uvx to automatically download and run the Rootly MCP server:\n\n- **Automatic setup**: No manual installation required\n- **Always latest**: Gets the most recent version automatically  \n- **Clean environment**: Uses temporary isolated environment\n- **No conflicts**: Doesn't interfere with your Python packages\n\n## How Burnout Scores Are Calculated\n\nThis tool uses **Christina Maslach's Burnout Assessment Inventory**, adapted for on-call engineering work. The system analyzes three dimensions:\n\n### 1. **Emotional Exhaustion (40% weight)**\nMeasures physical and emotional depletion from work demands:\n- Incident frequency relative to team norms\n- After-hours work percentage  \n- Average incident resolution time\n- Incident clustering (multiple incidents within 4 hours)\n\n### 2. **Depersonalization (30% weight)**  \nMeasures cynicism and detachment from work:\n- Escalation frequency (inability to resolve alone)\n- Solo incident handling rate\n- Response time trends (are you getting slower to respond over time?)\n- Communication quality (resolution message length)\n\n### 3. **Personal Accomplishment (30% weight, inverted)**\nMeasures sense of achievement and competence:\n- Incident resolution success rate\n- Resolution time improvement trends\n- Handling of complex/high-severity incidents  \n- Knowledge sharing and documentation quality\n\n### Overall Score\n\n**Standard Analysis** (incident data only):\n```\nBurnout Score = (Emotional Exhaustion × 0.4) + (Depersonalization × 0.3) + ((10 - Personal Accomplishment) × 0.3)\n```\n\n**Enhanced Analysis** (with `--include-github`):\n```\nEach Dimension = (Incident Component × 0.7) + (GitHub Component × 0.3)\nBurnout Score = (Emotional Exhaustion × 0.4) + (Depersonalization × 0.3) + ((10 - Personal Accomplishment) × 0.3)\n```\n\n**Score Ranges:**\n- **0-3.9**: Low risk - Healthy engagement levels\n- **4.0-6.9**: Medium risk - Early warning signs, intervention recommended\n- **7.0-10**: High risk - Immediate action needed\n\nThe scoring system identifies early burnout indicators through incident response patterns, enabling proactive interventions before burnout becomes severe.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootly-ai-labs%2Frootly-burnout-detector","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frootly-ai-labs%2Frootly-burnout-detector","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frootly-ai-labs%2Frootly-burnout-detector/lists"}