Postmortem: How I Got Passed Over for Promotion in 2026 and What I Did Next

# promotion_impact_tracker.py
# CLI tool to aggregate promotion-aligned impact data from GitHub, Jira, and internal review systems
# Requires: requests>=2.31.0, python-dotenv>=1.0.0, tabulate>=0.9.0
import os
import json
import argparse
from datetime import datetime, timedelta
from typing import Dict, List, Optional
import requests
from dotenv import load_dotenv
from tabulate import tabulate

load_dotenv()

class ImpactTrackerError(Exception):
    \"\"\"Custom exception for tracker failures\"\"\"
    pass

class PromotionImpactTracker:
    def __init__(self, github_username: str, jira_project: str):
        self.github_username = github_username
        self.jira_project = jira_project
        self.github_token = os.getenv(\"GITHUB_TOKEN\")
        self.jira_token = os.getenv(\"JIRA_TOKEN\")
        if not self.github_token:
            raise ImpactTrackerError(\"GITHUB_TOKEN environment variable not set\")
        self.github_headers = {
            \"Authorization\": f\"token {self.github_token}\",
            \"Accept\": \"application/vnd.github.v3+json\"
        }
        self.jira_headers = {
            \"Authorization\": f\"Bearer {self.jira_token}\",
            \"Accept\": \"application/json\"
        }
        self.impact_data: Dict[str, List[dict]] = {
            \"commits\": [],
            \"prs\": [],
            \"jira_tickets\": [],
            \"okr_updates\": []
        }

    def fetch_github_commits(self, repo: str, days_back: int = 90) -> None:
        \"\"\"Fetch commits by the user in a repo from the last N days\"\"\"
        since_date = (datetime.now() - timedelta(days=days_back)).isoformat()
        url = f\"https://api.github.com/repos/{repo}/commits\"
        params = {
            \"author\": self.github_username,
            \"since\": since_date,
            \"per_page\": 100
        }
        try:
            response = requests.get(url, headers=self.github_headers, params=params, timeout=10)
            response.raise_for_status()
            commits = response.json()
            for commit in commits:
                self.impact_data[\"commits\"].append({
                    \"repo\": repo,
                    \"sha\": commit[\"sha\"][:7],
                    \"message\": commit[\"commit\"][\"message\"].split(\"\\n\")[0],
                    \"date\": commit[\"commit\"][\"author\"][\"date\"]
                })
        except requests.exceptions.RequestException as e:
            raise ImpactTrackerError(f\"GitHub commit fetch failed: {str(e)}\")
        except (KeyError, json.JSONDecodeError) as e:
            raise ImpactTrackerError(f\"Failed to parse GitHub commit response: {str(e)}\")

    def fetch_jira_tickets(self, days_back: int = 90) -> None:
        \"\"\"Fetch completed Jira tickets for the user in the project\"\"\"
        if not self.jira_token:
            raise ImpactTrackerError(\"JIRA_TOKEN environment variable not set\")
        since_date = (datetime.now() - timedelta(days=days_back)).strftime(\"%Y-%m-%d\")
        url = f\"https://jira.example.com/rest/api/3/search\"
        params = {
            \"jql\": f\"project={self.jira_project} AND assignee={self.github_username} AND status=Done AND updated>= {since_date}\",
            \"maxResults\": 100
        }
        try:
            response = requests.get(url, headers=self.jira_headers, params=params, timeout=10)
            response.raise_for_status()
            tickets = response.json().get(\"issues\", [])
            for ticket in tickets:
                self.impact_data[\"jira_tickets\"].append({
                    \"key\": ticket[\"key\"],
                    \"summary\": ticket[\"fields\"][\"summary\"],
                    \"story_points\": ticket[\"fields\"].get(\"customfield_10016\", 0),
                    \"resolution_date\": ticket[\"fields\"][\"resolutiondate\"]
                })
        except requests.exceptions.RequestException as e:
            raise ImpactTrackerError(f\"Jira ticket fetch failed: {str(e)}\")

    def generate_report(self) -> str:
        \"\"\"Generate a markdown report of all tracked impact\"\"\"
        report_lines = [\"# Promotion Impact Report\", f\"Generated: {datetime.now().isoformat()}\"]
        for data_type, entries in self.impact_data.items():
            report_lines.append(f\"\\n## {data_type.replace('_', ' ').title()} ({len(entries)} entries)\")
            if entries:
                if data_type == \"commits\":
                    report_lines.append(tabulate(entries, headers=\"keys\", tablefmt=\"github\"))
                else:
                    report_lines.append(tabulate(entries, headers=\"keys\", tablefmt=\"github\"))
            else:
                report_lines.append(\"No entries found.\")
        return \"\\n\".join(report_lines)

if __name__ == \"__main__\":
    parser = argparse.ArgumentParser(description=\"Track promotion-aligned impact data\")
    parser.add_argument(\"--github-user\", required=True, help=\"GitHub username\")
    parser.add_argument(\"--jira-project\", required=True, help=\"Jira project key\")
    parser.add_argument(\"--repo\", action=\"append\", help=\"GitHub repo to track (can specify multiple)\")
    parser.add_argument(\"--days\", type=int, default=90, help=\"Number of days to look back\")
    parser.add_argument(\"--output\", default=\"impact_report.md\", help=\"Output report path\")
    args = parser.parse_args()

    try:
        tracker = PromotionImpactTracker(args.github_user, args.jira_project)
        if args.repo:
            for repo in args.repo:
                print(f\"Fetching commits for {repo}...\")
                tracker.fetch_github_commits(repo, args.days)
        print(\"Fetching Jira tickets...\")
        tracker.fetch_jira_tickets(args.days)
        report = tracker.generate_report()
        with open(args.output, \"w\") as f:
            f.write(report)
        print(f\"Report generated: {args.output}\")
    except ImpactTrackerError as e:
        print(f\"Tracker error: {e}\")
        exit(1)
    except Exception as e:
        print(f\"Unexpected error: {e}\")
        exit(1)

# performance_review_parser.py
# Parses internal performance review data to identify promotion gaps
# Requires: pandas>=2.1.0, PyPDF2>=3.0.0, scikit-learn>=1.3.0
import json
import os
import re
from typing import Dict, List, Optional
import pandas as pd
from PyPDF2 import PdfReader
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity

class ReviewParseError(Exception):
    \"\"\"Custom exception for review parsing failures\"\"\"
    pass

class PerformanceReviewParser:
    def __init__(self, okr_path: str):
        self.okr_path = okr_path
        self.okrs: List[Dict] = []
        self.reviews: List[Dict] = []
        self._load_okrs()

    def _load_okrs(self) -> None:
        \"\"\"Load OKR definitions from JSON file\"\"\"
        if not os.path.exists(self.okr_path):
            raise ReviewParseError(f\"OKR file not found: {self.okr_path}\")
        try:
            with open(self.okr_path, \"r\") as f:
                self.okrs = json.load(f)
            if not isinstance(self.okrs, list):
                raise ReviewParseError(\"OKR file must contain a JSON array\")
            print(f\"Loaded {len(self.okrs)} OKRs\")
        except json.JSONDecodeError as e:
            raise ReviewParseError(f\"Invalid OKR JSON: {str(e)}\")

    def parse_pdf_review(self, pdf_path: str) -> Dict:
        \"\"\"Parse a performance review PDF into structured data\"\"\"
        if not os.path.exists(pdf_path):
            raise ReviewParseError(f\"Review PDF not found: {pdf_path}\")
        try:
            reader = PdfReader(pdf_path)
            text = \"\"
            for page in reader.pages:
                text += page.extract_text() or \"\"
            # Extract sections using regex
            sections = {}
            current_section = None
            for line in text.split(\"\\n\"):
                line = line.strip()
                if re.match(r\"^(Strengths|Areas for Improvement|OKR Progress|Manager Feedback)$\", line, re.IGNORECASE):
                    current_section = line.lower().replace(\" \", \"_\")
                    sections[current_section] = []
                elif current_section and line:
                    sections[current_section].append(line)
            # Calculate OKR alignment score
            okr_text = \" \".join([\" \".join(s) for s in sections.get(\"okr_progress\", [])])
            alignment_score = self._calculate_okr_alignment(okr_text)
            review_data = {
                \"source\": pdf_path,
                \"sections\": sections,
                \"okr_alignment_score\": alignment_score,
                \"raw_text\": text[:500]  # Truncate for storage
            }
            self.reviews.append(review_data)
            return review_data
        except Exception as e:
            raise ReviewParseError(f\"Failed to parse PDF {pdf_path}: {str(e)}\")

    def _calculate_okr_alignment(self, review_text: str) -> float:
        \"\"\"Calculate cosine similarity between review text and OKR definitions\"\"\"
        if not self.okrs:
            return 0.0
        okr_texts = [f\"{okr['title']} {okr['description']}\" for okr in self.okrs]
        corpus = okr_texts + [review_text]
        vectorizer = TfidfVectorizer(stop_words=\"english\")
        tfidf_matrix = vectorizer.fit_transform(corpus)
        # Compare review text (last in corpus) to each OKR
        review_vector = tfidf_matrix[-1]
        okr_vectors = tfidf_matrix[:-1]
        similarities = cosine_similarity(review_vector, okr_vectors)[0]
        return float(sum(similarities) / len(similarities)) if similarities.size > 0 else 0.0

    def identify_promotion_gaps(self) -> List[str]:
        \"\"\"Identify gaps between review feedback and promotion criteria\"\"\"
        gaps = []
        if not self.reviews:
            gaps.append(\"No performance reviews parsed\")
            return gaps
        # Check for consistent areas of improvement
        all_improvements = []
        for review in self.reviews:
            all_improvements.extend(review[\"sections\"].get(\"areas_for_improvement\", []))
        if all_improvements:
            vectorizer = TfidfVectorizer(stop_words=\"english\")
            tfidf = vectorizer.fit_transform(all_improvements)
            mean_score = tfidf.mean(axis=0).A1
            top_indices = mean_score.argsort()[-3:][::-1]
            top_terms = [vectorizer.get_feature_names_out()[i] for i in top_indices]
            gaps.append(f\"Top recurring improvement areas: {', '.join(top_terms)}\")
        # Check OKR alignment
        avg_alignment = sum(r[\"okr_alignment_score\"] for r in self.reviews) / len(self.reviews)
        if avg_alignment < 0.4:
            gaps.append(f\"Low average OKR alignment score: {avg_alignment:.2f} (target >=0.4)\")
        return gaps

if __name__ == \"__main__\":
    parser = argparse.ArgumentParser(description=\"Parse performance reviews for promotion gaps\")
    parser.add_argument(\"--okr-file\", required=True, help=\"Path to OKR JSON file\")
    parser.add_argument(\"--review-pdf\", action=\"append\", help=\"Path to performance review PDF (can specify multiple)\")
    parser.add_argument(\"--output\", default=\"review_gaps.json\", help=\"Output gaps path\")
    args = parser.parse_args()

    try:
        parser_obj = PerformanceReviewParser(args.okr_file)
        if args.review_pdf:
            for pdf in args.review_pdf:
                print(f\"Parsing {pdf}...\")
                parser_obj.parse_pdf_review(pdf)
        gaps = parser_obj.identify_promotion_gaps()
        with open(args.output, \"w\") as f:
            json.dump({\"gaps\": gaps, \"review_count\": len(parser_obj.reviews)}, f, indent=2)
        print(f\"Gaps identified: {len(gaps)}\")
        for gap in gaps:
            print(f\"- {gap}\")
    except ReviewParseError as e:
        print(f\"Parse error: {e}\")
        exit(1)
    except Exception as e:
        print(f\"Unexpected error: {e}\")
        exit(1)

# contribution_automator.py
# Automates tracking of open-source and internal contributions for promotion packets
# Requires: requests>=2.31.0, python-dotenv>=1.0.0, pandas>=2.1.0
import os
import json
from datetime import datetime, timedelta
from typing import Dict, List
import requests
from dotenv import load_dotenv
import pandas as pd

load_dotenv()

class ContributionError(Exception):
    \"\"\"Custom exception for contribution tracking failures\"\"\"
    pass

class ContributionAutomator:
    def __init__(self, github_username: str):
        self.github_username = github_username
        self.token = os.getenv(\"GITHUB_TOKEN\")
        if not self.token:
            raise ContributionError(\"GITHUB_TOKEN environment variable not set\")
        self.headers = {
            \"Authorization\": f\"token {self.token}\",
            \"Accept\": \"application/vnd.github.v3+json\"
        }
        self.contributions: List[Dict] = []

    def track_repo_contributions(self, repo: str, days_back: int = 180) -> None:
        \"\"\"Track all contributions to a repo (commits, PRs, issues)\"\"\"
        # Validate repo format
        if \"/\" not in repo:
            raise ContributionError(f\"Invalid repo format: {repo}. Use owner/repo (e.g., https://github.com/octocat/Hello-World)\")
        # Fetch commits
        self._fetch_commits(repo, days_back)
        # Fetch pull requests
        self._fetch_prs(repo, days_back)
        # Fetch issues
        self._fetch_issues(repo, days_back)

    def _fetch_commits(self, repo: str, days_back: int) -> None:
        \"\"\"Fetch commits by user in repo\"\"\"
        since = (datetime.now() - timedelta(days=days_back)).isoformat()
        url = f\"https://api.github.com/repos/{repo}/commits\"
        params = {\"author\": self.github_username, \"since\": since, \"per_page\": 100}
        try:
            response = requests.get(url, headers=self.headers, params=params, timeout=10)
            response.raise_for_status()
            for commit in response.json():
                self.contributions.append({
                    \"repo\": repo,
                    \"repo_url\": f\"https://github.com/{repo}\",
                    \"type\": \"commit\",
                    \"sha\": commit[\"sha\"][:7],
                    \"message\": commit[\"commit\"][\"message\"].split(\"\\n\")[0],
                    \"date\": commit[\"commit\"][\"author\"][\"date\"]
                })
        except requests.exceptions.RequestException as e:
            print(f\"Warning: Failed to fetch commits for {repo}: {str(e)}\")

    def _fetch_prs(self, repo: str, days_back: int) -> None:
        \"\"\"Fetch PRs authored by user in repo\"\"\"
        since = (datetime.now() - timedelta(days=days_back)).isoformat()
        url = f\"https://api.github.com/repos/{repo}/pulls\"
        params = {\"state\": \"all\", \"creator\": self.github_username, \"since\": since, \"per_page\": 100}
        try:
            response = requests.get(url, headers=self.headers, params=params, timeout=10)
            response.raise_for_status()
            for pr in response.json():
                self.contributions.append({
                    \"repo\": repo,
                    \"repo_url\": f\"https://github.com/{repo}\",
                    \"type\": \"pull_request\",
                    \"number\": pr[\"number\"],
                    \"title\": pr[\"title\"],
                    \"state\": pr[\"state\"],
                    \"merged\": pr[\"merged_at\"] is not None,
                    \"date\": pr[\"created_at\"]
                })
        except requests.exceptions.RequestException as e:
            print(f\"Warning: Failed to fetch PRs for {repo}: {str(e)}\")

    def generate_contribution_report(self, output_path: str = \"contributions.csv\") -> None:
        \"\"\"Generate a CSV report of all tracked contributions\"\"\"
        if not self.contributions:
            raise ContributionError(\"No contributions tracked. Run track_repo_contributions first.\")
        df = pd.DataFrame(self.contributions)
        df.to_csv(output_path, index=False)
        print(f\"Report generated: {output_path} ({len(df)} contributions)\")

    def get_top_repos(self, n: int = 5) -> List[Dict]:
        \"\"\"Get top N repos by number of contributions\"\"\"
        if not self.contributions:
            return []
        df = pd.DataFrame(self.contributions)
        top = df.groupby(\"repo\").size().sort_values(ascending=False).head(n)
        return [{\"repo\": repo, \"count\": int(count), \"url\": f\"https://github.com/{repo}\"} for repo, count in top.items()]

if __name__ == \"__main__\":
    parser = argparse.ArgumentParser(description=\"Automate contribution tracking for promotions\")
    parser.add_argument(\"--github-user\", required=True, help=\"GitHub username\")
    parser.add_argument(\"--repo\", action=\"append\", required=True, help=\"Repo to track (owner/repo, e.g., https://github.com/owner/repo)\")
    parser.add_argument(\"--days\", type=int, default=180, help=\"Days back to track\")
    parser.add_argument(\"--output\", default=\"contributions.csv\", help=\"Output CSV path\")
    args = parser.parse_args()

    try:
        automator = ContributionAutomator(args.github_user)
        for repo in args.repo:
            # Extract owner/repo from URL if full URL is provided
            if repo.startswith(\"https://github.com/\"):
                repo = repo.replace(\"https://github.com/\", \"\")
            print(f\"Tracking contributions for {repo}...\")
            automator.track_repo_contributions(repo, args.days)
        automator.generate_contribution_report(args.output)
        top_repos = automator.get_top_repos()
        print(\"\\nTop contributing repos:\")
        for repo in top_repos:
            print(f\"- {repo['repo']}: {repo['count']} contributions ({repo['url']})\")
    except ContributionError as e:
        print(f\"Contribution error: {e}\")
        exit(1)
    except Exception as e:
        print(f\"Unexpected error: {e}\")
        exit(1)

# impact_statement_generator.py
# Generates business impact statements from Jira tickets
import json

def generate_impact_statement(ticket: dict) -> str:
    \"\"\"Generate impact statement from Jira ticket data\"\"\"
    summary = ticket.get(\"summary\", \"No summary\")
    story_points = ticket.get(\"story_points\", 0)
    metrics = ticket.get(\"impact_metrics\", {})
    okr = ticket.get(\"linked_okr\", \"Company OKR\")
    statement = f\"Shipped {summary} ({story_points} story points), \"
    if \"latency_reduction\" in metrics:
        statement += f\"reducing p99 latency by {metrics['latency_reduction']}%, \"
    if \"cost_savings\" in metrics:
        statement += f\"saving ${metrics['cost_savings']}/month, \"
    statement += f\"contributing to {okr}.\"
    return statement.strip()

# Example usage
ticket = {
    \"summary\": \"checkout API performance tuning\",
    \"story_points\": 8,
    \"impact_metrics\": {\"latency_reduction\": 95, \"cost_savings\": 18000},
    \"linked_okr\": \"Q3 2026 Revenue Growth OKR\"
}
print(generate_impact_statement(ticket))

# github_contribution_action.yml
# GitHub Action to automate contribution tracking
name: Track Contributions
on:
  schedule:
    - cron: \"0 0 * * 0\" # Run weekly
jobs:
  track:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: 3.12
      - name: Install dependencies
        run: pip install requests python-dotenv pandas
      - name: Run contribution automator
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: python contribution_automator.py --github-user myusername --repo https://github.com/myorg/myrepo --output contributions.csv
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: contributions
          path: contributions.csv

// sample_okrs.json
// Sample OKR file for gap analysis
[
    {
        \"id\": \"okr-2026-q3-1\",
        \"title\": \"Reduce checkout latency to <200ms p99\",
        \"description\": \"Improve checkout API performance to reduce cart abandonment and increase revenue\",
        \"owner\": \"backend-team\",
        \"target\": \"p99 latency <= 200ms\"
    },
    {
        \"id\": \"okr-2026-q3-2\",
        \"title\": \"Increase developer productivity by 20%\",
        \"description\": \"Reduce CI build times and improve internal tooling\",
        \"owner\": \"platform-team\",
        \"target\": \"CI build time <= 5 minutes\"
    }
]