From 6e50b28611bf9af0ac01f43dfe69dbe35113f3be Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Sun, 4 Jan 2026 18:14:20 -0500 Subject: [PATCH 01/11] docs: add "Brag Docs for Developers Who Ship" blog post MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New blog post targeting serious developers, positioning BragDoc as a comprehensive tool that captures full developer impact - code, PRs, tickets, AND meetings/calendar. Key messaging: - Captures everything: Git, GitHub, Jira, Google Calendar - Built for developers with CLI-first workflow - Automates work log tracking (links to Pragmatic Engineer) - "The Full Picture of Developer Impact" - code + soft work 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../brag-docs-for-developers-who-ship.mdx | 143 ++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 apps/marketing/content/blog/brag-docs-for-developers-who-ship.mdx diff --git a/apps/marketing/content/blog/brag-docs-for-developers-who-ship.mdx b/apps/marketing/content/blog/brag-docs-for-developers-who-ship.mdx new file mode 100644 index 00000000..4b17b6d5 --- /dev/null +++ b/apps/marketing/content/blog/brag-docs-for-developers-who-ship.mdx @@ -0,0 +1,143 @@ +--- +title: "Brag Docs for Developers Who Ship" +date: "2026-01-04" +description: "Track your full impact: Git commits, GitHub PRs, Jira tickets, and Google Calendar. Built for developers with a CLI-first workflow." +author: "BragDoc Team" +tags: ["cli", "git", "developer-tools", "performance-reviews", "career-growth"] +image: "/screenshots/terminal/bragdoc-extract.png" +published: true +canonical_url: "https://www.bragdoc.ai/blog/brag-docs-for-developers-who-ship" +--- + +Your impact as a developer is scattered across a dozen systems. Commits in Git. PRs and code reviews on GitHub. Tickets in Jira. Architecture discussions in meetings. Mentoring in 1:1s. No single tool captures all of it. + +Keeping a [work log](https://blog.pragmaticengineer.com/work-log-template-for-software-engineers/) is one of the best habits for software engineers. But doing it manually is tedious, and most people give up after a few weeks. + +BragDoc automates it. We pull from your Git history, your GitHub activity, your Jira tickets, and your Google Calendar. Everything that represents your work, captured automatically. + +But here's what makes us different: we built this for developers, not for everyone. + + + +## Built for the Terminal + +Most productivity tools assume you live in a browser. They want you to click through dashboards, drag cards around, and manually enter your accomplishments. That workflow makes sense for project managers. It doesn't make sense for developers. + +BragDoc starts in your terminal. Install the CLI, authenticate once, and you're done: + +```bash +npm install -g @bragdoc/cli +bragdoc login +bragdoc init +``` + +That's it. Three commands and your repository is configured. No web forms. No onboarding wizards. No fifteen-minute setup tutorials. + +When you want to extract achievements from your recent work: + +```bash +bragdoc extract --since 7d +``` + +Your commits get analyzed, grouped by theme, and turned into achievement statements. The whole process takes seconds. + + + +## Your Git History Is Your Brag Doc + +Every commit you make is already documentation. The timestamp shows when you did the work. The message explains why. The diff shows what changed. This is more accurate than anything you could write from memory three months later. + +The problem isn't that your work isn't documented. The problem is that git log output isn't formatted for [performance reviews](/use-cases). + +BragDoc bridges that gap. It reads your commit history, understands the context, and generates achievement statements that make sense to managers. You keep writing commits the way you always have. BragDoc handles the translation. + +## Every Source, One Workflow + +Real developer work spans multiple systems. You commit code locally. You open PRs and review code on GitHub. You close tickets in Jira. You lead architecture discussions and mentor teammates in meetings. A complete brag doc needs to capture all of it. + +BragDoc uses a [pluggable connector architecture](/features) that pulls from wherever your work happens: + +- **Git**: Local commits, branches, full diff context. Works offline. +- **GitHub**: PRs, issues, code reviews, commits, and discussions. +- **Jira**: Tickets, story points, sprint contributions. +- **Google Calendar**: Meetings, 1:1s, architecture sessions, planning. + +You configure which sources matter for each project through the web app or API. The CLI pulls from all your configured sources automatically: + +```bash +bragdoc extract # All configured sources +bragdoc extract --project myapp # Specific project only +bragdoc extract --since 30d # Last 30 days +``` + +## Branch Control + +Not every branch matters for your brag doc. Experimental work, abandoned features, and one-off debugging branches probably shouldn't appear in your performance review. + +BragDoc lets you whitelist branches per project: + +```bash +bragdoc projects add --branch-whitelist "main,develop,release/*" +``` + +Only commits from those branches get extracted. Everything else is ignored. This keeps your achievement list focused on work that actually shipped. + +## Privacy by Default + +Your source code is sensitive. You don't want it uploaded to some cloud service where it might be used to train AI models or leaked in a data breach. + +BragDoc processes your code locally. The CLI runs on your machine. Your diffs never leave your computer. Only the generated achievement summaries sync to the server, and even that's optional. + +If you want complete control, you can run the entire system locally with [Ollama](https://ollama.ai): + +```bash +bragdoc llm set ollama llama3.2 +``` + +Now your commits are analyzed by a local model. Nothing touches the internet. Your code stays yours. + + + +## The Full Picture of Developer Impact + +Great developers do more than commit code. You lead architecture discussions. You mentor teammates. You coordinate across teams. You make decisions in meetings that shape the direction of projects. All of that is impact. + +Most tools force you to choose: track your code OR track your meetings. BragDoc tracks both. Your commits and your calendar. Your PRs and your 1:1s. The technical work and the leadership work. + +The difference is how we do it. We built BragDoc for developers, with a CLI that fits your workflow, integrations that go deep into your tools, and AI that understands technical context. [Learn more about the different types of developer impact](/blog/six-types-developer-impact) and how to document each one. + +## For Developers Who Ship + +BragDoc is built for developers who ship. If you write code, review PRs, close tickets, and push to production, this is your tool. The CLI fits your workflow. The integrations pull from where your work actually happens. The output reflects your technical contributions. + +[Give BragDoc a try](/get-started). Install the CLI, point it at your repositories, and let it capture what you build. Your commits already tell the story of your work. It's time your brag doc did too. + + From 4017404302053a11ecad14566c36aa42e4421818 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:06:43 -0500 Subject: [PATCH 02/11] docs: add "The Promotion Gap" blog post Data-driven blog post about why great engineers get overlooked for promotions. Covers rater bias (50%+ of rating variance), proximity bias (42% of managers forget remote workers), and recency bias. Includes concrete example comparing two engineers, acknowledges limitations of documentation as a strategy, and positions BragDoc as a tool that improves odds rather than guarantees success. All statistics sourced from credible research: Culture Amp, HBR, Levels.fyi, StaffEng, and JetBrains 2025 Developer Survey. Co-Authored-By: Claude Opus 4.5 --- ...gap-why-great-engineers-get-overlooked.mdx | 98 +++++++++++++++++++ .../the-promotion-gap/promotion-gap-data.svg | 80 +++++++++++++++ 2 files changed, 178 insertions(+) create mode 100644 apps/marketing/content/blog/the-promotion-gap-why-great-engineers-get-overlooked.mdx create mode 100644 apps/marketing/public/images/blog/the-promotion-gap/promotion-gap-data.svg diff --git a/apps/marketing/content/blog/the-promotion-gap-why-great-engineers-get-overlooked.mdx b/apps/marketing/content/blog/the-promotion-gap-why-great-engineers-get-overlooked.mdx new file mode 100644 index 00000000..6edd88d9 --- /dev/null +++ b/apps/marketing/content/blog/the-promotion-gap-why-great-engineers-get-overlooked.mdx @@ -0,0 +1,98 @@ +--- +title: "The Promotion Gap: Why Engineers Get Overlooked" +description: "Research reveals how bias affects tech promotions. Why great engineers get passed over—and what you can do about it." +date: "2026-01-09" +author: "BragDoc Team" +tags: ["promotion", "career-growth", "bias", "performance-reviews", "engineering-careers"] +image: "/images/blog/the-promotion-gap/promotion-gap-data.svg" +imageAlt: "Infographic showing promotion gap statistics: less than 10% of engineers are Staff level, 50%+ of rating variance is rater bias, 42% of managers forget remote workers, 66% of devs say metrics miss contributions" +published: false +canonical_url: "https://www.bragdoc.ai/blog/the-promotion-gap-why-great-engineers-get-overlooked" +--- + +You've shipped more features than your peers. You've fixed critical bugs that saved the company money. You've mentored junior developers. Yet when promotion season arrives, someone else gets the title. + +This promotion gap happens far more often than it should. And it's probably not because you're not good enough. + +Research suggests that systematic biases in how we evaluate engineers create patterns where excellent work goes unrecognized. This doesn't explain every missed promotion, but it explains more than most engineers realize. + + + +## The Core Problem: Your Rating Depends on Who's Rating You + +If there's one number that matters most, it's this: more than 50% of performance rating variance comes from rater bias, not actual performance differences. + +More than half the difference between your rating and your peer's rating has nothing to do with how good you actually are. It's about who's doing the rating, their preferences, and what they happen to remember. + +## How Bias Shows Up in Practice + +Two biases matter most: + +**Proximity bias** affects who gets seen. 42% of managers admit they forget about remote workers when assigning high-visibility work. Your manager sees the person sitting next to them every day. They remember that person's wins. + +**Recency bias** affects what gets remembered. Recency bias is one of the most common biases in performance reviews—managers give disproportionate weight to what happened in recent weeks rather than the full review period. The engineer who shipped something visible last week beats the engineer who shipped something critical in March. + +These biases compound. If you're remote and your biggest wins happened early in the review cycle, you're fighting an uphill battle that has nothing to do with the quality of your work. + +## What This Looks Like in Practice + +Consider two engineers on the same team. Both are senior. Both are technically strong. + +Engineer A works from home. In February, she led a complex database migration that prevented a potential outage affecting thousands of users. In her 1:1s, she mentioned it briefly. She didn't write it down anywhere else. + +Engineer B sits two desks from their manager. In October—three weeks before reviews—he shipped a visible dashboard feature. Nothing critical, but the whole team saw the launch. His manager mentioned it in the weekly standup. + +Come December, the manager writes performance reviews. The migration? It's been ten months. The specifics are fuzzy. The dashboard? Fresh in mind, easy to describe, clearly impactful. + +Engineer B gets the stronger review. Not because he's better—because his work was recent and visible. + +This isn't a story about bad managers. It's a story about how memory works, and what happens when documentation doesn't exist. + +## The Structural Reality + +According to Levels.fyi research, staff engineers typically make up less than 10% of engineering organizations. The senior level is a "career level" by design—most engineers who reach it stay there. + +This isn't necessarily bad. Not everyone wants to be a staff engineer, and that's valid. But for those who do want to advance, internal promotions to staff are notoriously difficult. At competitive levels, visibility can be the deciding factor between candidates of similar ability. + +## What the Data Doesn't Explain + +Before we talk about solutions: limitations matter. + +A missed promotion might be bias—or it might be that you weren't ready, that there wasn't headcount, or that your manager had legitimate concerns. Documentation helps in organizations that are fundamentally fair but imperfect. It doesn't help in toxic environments. It doesn't replace having a manager who advocates for you. + +If good documentation and consistent performance still don't move the needle, the problem might not be your visibility. It might be the organization. + +## What You Can Actually Do + +For engineers in reasonably functional organizations, visibility gaps are often fixable: + +- **Document wins as they happen.** Julia Evans' brag document approach captures achievements when they occur, not six months later. (See our guide on [how to write a self-evaluation](/blog/how-to-write-self-evaluation-developer).) +- **Be specific about impact.** "Fixed a bug" is forgettable. "Fixed a race condition causing 2% transaction failures, protecting $50K/month revenue" is not. +- **Share wins regularly.** Distribute when your manager learns about your work across the year to counteract recency bias. + +These aren't guaranteed solutions. They're habits that tend to help in environments where effort is generally rewarded. + +## Why We Built BragDoc + +We kept noticing the same pattern: engineers scrambling before review season, trying to reconstruct months of work from vague memories and incomplete git logs. The same struggle showed up in job searches, salary negotiations, and even weekly standups. + +[BragDoc](/features) pulls from Git history, GitHub activity, and other sources to capture achievements automatically. Your commits already document what you did and when—we translate that into statements you can actually use. + +It won't fix broken organizations or guarantee promotions. But for engineers in environments where documentation matters, it removes the part where you have to remember everything yourself. + +Whether you're preparing for [performance reviews](/use-cases), negotiating a raise, or maintaining a clear record of your trajectory, documented evidence tends to improve your odds. + +--- + +**Next steps:** Start documenting your wins this week. Add three recent accomplishments to a simple document, then capture each new win as it happens. By review season, you'll have clearer evidence of your impact—and a better foundation for whatever conversation comes next. + + diff --git a/apps/marketing/public/images/blog/the-promotion-gap/promotion-gap-data.svg b/apps/marketing/public/images/blog/the-promotion-gap/promotion-gap-data.svg new file mode 100644 index 00000000..0bc869cd --- /dev/null +++ b/apps/marketing/public/images/blog/the-promotion-gap/promotion-gap-data.svg @@ -0,0 +1,80 @@ + + + + + + + + + + + + + The Promotion Gap: What The Data Shows + Why excellent engineers get overlooked + + + + + + <10% + of engineers are + Staff level or above + Source: Levels.fyi + + + + 50%+ + of rating variance is + rater bias, not performance + Source: Culture Amp + + + + 42% + of managers forget + remote workers for tasks + Source: HBR + + + + 66% + of devs say metrics don't + reflect true contributions + Source: JetBrains 2025 + + + Three Biases That Block Promotions + + + + + 1 + Proximity Bias + Who sits near the manager gets + remembered. Remote workers lose. + + + + + 2 + Recency Bias + Last month matters more than + 6 months ago. Timing beats impact. + + + + + 3 + Rater Bias + 50%+ of your rating is about who's + rating you, not your actual work. + + + + The solution: Make your work visible through continuous documentation + Engineers with documented achievements advance faster and negotiate better compensation + + + bragdoc.ai + From e09cb1389292ee2a8f01f28c2f45d78b38d64164 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:25:40 -0500 Subject: [PATCH 03/11] docs: add "From Commits to Performance Review" blog post Building-in-public technical blog covering the BragDoc pipeline: - CLI extraction via pluggable connector architecture - Workstreams with embeddings and DBSCAN clustering - Performance review document generation (streaming) - Upcoming Jira and Google Calendar integrations Includes pipeline overview SVG diagram. Co-Authored-By: Claude Opus 4.5 --- .../from-commits-to-performance-review.mdx | 152 ++++++++++++++++++ .../pipeline-overview.svg | 132 +++++++++++++++ 2 files changed, 284 insertions(+) create mode 100644 apps/marketing/content/blog/from-commits-to-performance-review.mdx create mode 100644 apps/marketing/public/images/blog/from-commits-to-performance-review/pipeline-overview.svg diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx new file mode 100644 index 00000000..eb7f424e --- /dev/null +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -0,0 +1,152 @@ +--- +title: "From Commits to Performance Review: The Pipeline" +description: "A look inside how BragDoc turns Git history into performance review documentation. CLI extraction, AI clustering, and document generation." +date: "2026-01-10" +author: "BragDoc Team" +tags: ["engineering", "performance-reviews", "architecture", "building-in-public", "workstreams"] +image: "/images/blog/from-commits-to-performance-review/pipeline-overview.svg" +imageAlt: "Diagram showing BragDoc pipeline from Git commits through workstreams to performance review document" +published: false +canonical_url: "https://www.bragdoc.ai/blog/from-commits-to-performance-review" +--- + +Performance review season is approaching. You have six months of commits, PRs, and closed tickets scattered across systems. Somewhere in that pile is the story of what you actually accomplished—but extracting it feels like archaeology. + +We're building BragDoc to solve this. The goal: turn your Git history into a performance review document with minimal manual effort. This post walks through how the pipeline works, what we've shipped, and what we're building next. + +## The Problem We're Solving + +Most developers track their work in at least four places: Git commits, GitHub PRs, issue trackers, and calendars. When review time comes, you're left reconstructing the narrative manually. You scroll through months of history, trying to remember which commits mattered and which were just noise. + +The information exists. It's just not in a usable format. + +Our approach: extract achievements automatically, group them into coherent themes, and generate a document you can actually submit. Here's how each stage works. + +## Stage 1: Extraction via CLI + +Everything starts with the [BragDoc CLI](/features). It runs locally on your machine, which means your source code never leaves your computer. + +```bash +npm install -g @bragdoc/cli +bragdoc login +bragdoc init +bragdoc extract --since 30d +``` + +The CLI uses a pluggable connector architecture. Each data source—Git, GitHub, Jira—implements the same interface, so adding new sources doesn't require changing core logic. + +For Git extraction, the CLI: +1. Reads your commit history within the specified date range +2. Applies branch whitelisting (so experimental branches don't pollute your achievements) +3. Sends commit messages and diffs to an LLM for analysis +4. Returns structured achievement objects with title, summary, and impact score + +The LLM runs locally if you prefer. We support Ollama for fully offline extraction: + +```bash +bragdoc llm set ollama llama3.2 +``` + +Your diffs stay on your machine. Only the generated achievement summaries sync to the server. + +## Stage 2: Workstreams (Automatic Clustering) + +Raw achievements are useful, but they don't tell a story. A six-month review period might produce 50+ achievements across different projects. Presenting that as a flat list isn't helpful. + +This is where workstreams come in. They're automatically generated clusters of related achievements—themes that emerge from your work. + +The clustering pipeline: + +**Embedding generation**: Each achievement gets converted to a 1536-dimensional vector using OpenAI's text-embedding-3-small model. The embedding captures semantic meaning, so similar achievements end up close together in vector space. + +**DBSCAN clustering**: We use density-based clustering (DBSCAN) rather than k-means because we don't know how many clusters exist beforehand. DBSCAN finds natural groupings and handles outliers gracefully. Parameters adapt based on dataset size. + +**Workstream naming**: An LLM generates a 2-5 word name and one-sentence description for each cluster based on its achievements. "Payment System Refactor" rather than "Cluster 7." + +The result: your 50 achievements become 5-8 workstreams with descriptive names. Each workstream groups related work, making it easier to explain what you actually accomplished. + +You can filter workstreams by date range and project. If you're preparing a Q4 review, you see only Q4 workstreams. The clustering runs on your filtered subset. + +## Stage 3: Performance Review Document (Shipping Now) + +This is what we're actively building. The performance review feature takes your achievements and workstreams and generates an actual document. + +The flow: +1. Create a new performance review with a date range (e.g., "Q4 2024") +2. The system loads all achievements and workstreams from that period +3. You provide optional instructions for the AI ("Focus on leadership impact" or "Emphasize technical depth") +4. Click generate, and the document streams in + +The generated document is editable. After the initial generation, you can refine it through a chat interface—ask the AI to expand a section, add metrics, or adjust tone. The document updates in real-time. + +We're using GPT-4o for document generation because the quality difference matters for something you'll submit to your manager. Extraction can run on smaller models; the final document benefits from a more capable one. + +## The Architecture + +Here's how the pieces connect: + +``` +CLI (local) Web App Database + │ │ │ + ├─► Git extraction │ │ + │ via connectors │ │ + │ │ │ + └─► POST /api/achievements ──────────────►│ + │ │ + ├─► Generate embeddings + │ (OpenAI API) │ + │ │ + ├─► DBSCAN clustering + │ (in-memory) │ + │ │ + ├─► Create workstreams ────►│ + │ │ + ├─► Performance Review │ + │ document generation │ + │ (streaming, GPT-4o) │ + │ │ + └─► Chat refinement │ + (streaming) │ +``` + +The CLI handles extraction. The web app handles clustering and document generation. Everything is scoped by user—your data stays yours. + +## What's Shipping Next + +We're expanding the connector architecture to pull from more sources: + +**Jira integration**: Extract achievements from closed tickets. Story points, sprint contributions, and ticket descriptions become part of your achievement record. + +**Google Calendar integration**: Meetings represent invisible work. Architecture discussions, 1:1 mentoring, planning sessions—these matter for reviews but don't show up in Git. Calendar integration captures them. + +Both will work through the existing CLI. You'll configure sources per project, and `bragdoc extract` will pull from all of them. + +## Why We're Building This Way + +A few design decisions worth explaining: + +**Local-first extraction**: Your code is sensitive. We don't want it on our servers, and you probably don't either. Running extraction locally means your diffs never leave your machine. Only the summaries sync. + +**Pluggable connectors**: Different teams use different tools. The connector architecture lets us add sources without touching core logic. Want to extract from GitLab instead of GitHub? Same interface, different implementation. + +**Semantic clustering over manual organization**: You could manually tag achievements into categories. Most people won't. Automatic clustering means you get organized output without extra work. + +**Streaming document generation**: Performance review documents are long. Waiting for a full document to generate is frustrating. Streaming shows progress immediately and lets you start reading before generation completes. + +## Try It + +If you're preparing for a performance review, the pipeline is ready to use: + +1. [Install the CLI](/get-started) and extract your recent commits +2. Generate workstreams from your achievements +3. Create a performance review and generate your document + +The whole process takes minutes instead of hours. Your Git history already contains the raw material—we just make it usable. + +We're building this in public because we think the approach matters as much as the product. If you have questions about the architecture or want to see specific features, [let us know](mailto:hello@bragdoc.ai). + +--- + +**Related**: [Why Developers Need Automated Brag Docs](/blog/why-developers-need-automated-brag-docs) explains the problem in more depth. [Six Types of Developer Impact](/blog/six-types-developer-impact) covers what to include beyond code. + + diff --git a/apps/marketing/public/images/blog/from-commits-to-performance-review/pipeline-overview.svg b/apps/marketing/public/images/blog/from-commits-to-performance-review/pipeline-overview.svg new file mode 100644 index 00000000..7d24834d --- /dev/null +++ b/apps/marketing/public/images/blog/from-commits-to-performance-review/pipeline-overview.svg @@ -0,0 +1,132 @@ + + + + + + + + + + + + + + + + + From Commits to Performance Review + How BragDoc transforms your Git history into review-ready documentation + + + + + + CLI Extraction + + + + + + + $ bragdoc extract + Analyzing commits... + 12 achievements found + + Git, GitHub, Jira + Local processing + + + + + + + + + + Workstreams + + + + + + + + + + + + + + + + + Embeddings + DBSCAN + Automatic clustering + Semantic grouping + + + + + + + + + + Performance Review + + + + + + + + + + + AI document generation + Streaming output + + + + + + + + Ready to + Submit + + + + + Data Sources + + + + Git + Local commits + + + + GitHub + PRs, Issues + + + + + Jira + Coming soon + + + + + Calendar + Coming soon + + + + Ollama + Local LLM + + + bragdoc.ai + \ No newline at end of file From 2fd37a10dc4e4d190bdbe9b0ab9e58239400980f Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:27:48 -0500 Subject: [PATCH 04/11] fix: use generic model reference in blog post Changed 'GPT-4o' to 'OpenAI's latest models' to avoid being tied to a specific model version that may change. Co-Authored-By: Claude Opus 4.5 --- .../content/blog/from-commits-to-performance-review.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx index eb7f424e..f0b4f9f9 100644 --- a/apps/marketing/content/blog/from-commits-to-performance-review.mdx +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -79,7 +79,7 @@ The flow: The generated document is editable. After the initial generation, you can refine it through a chat interface—ask the AI to expand a section, add metrics, or adjust tone. The document updates in real-time. -We're using GPT-4o for document generation because the quality difference matters for something you'll submit to your manager. Extraction can run on smaller models; the final document benefits from a more capable one. +We use OpenAI's latest models for document generation because the quality difference matters for something you'll submit to your manager. Extraction can run on smaller models; the final document benefits from a more capable one. ## The Architecture From 5ad3fbe1b6e3fe71c3a97c3fd29cb359b3da785b Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:31:16 -0500 Subject: [PATCH 05/11] docs: apply blog enhancements for SEO and clarity - Updated title to be more keyword-forward: "How BragDoc Turns Git History into Performance Reviews" - Expanded meta description with action words - Added external links: Ollama docs and DBSCAN Wikipedia - Added concrete example in Stage 3 showing how achievements become coherent narrative - Fixed architecture diagram to use generic "OpenAI" instead of specific model name Co-Authored-By: Claude Opus 4.5 --- .../blog/from-commits-to-performance-review.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx index f0b4f9f9..85e0069d 100644 --- a/apps/marketing/content/blog/from-commits-to-performance-review.mdx +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -1,6 +1,6 @@ --- -title: "From Commits to Performance Review: The Pipeline" -description: "A look inside how BragDoc turns Git history into performance review documentation. CLI extraction, AI clustering, and document generation." +title: "How BragDoc Turns Git History into Performance Reviews" +description: "A look inside how BragDoc automates performance review documentation. CLI extraction, AI clustering, and document generation—from commits to review-ready docs." date: "2026-01-10" author: "BragDoc Team" tags: ["engineering", "performance-reviews", "architecture", "building-in-public", "workstreams"] @@ -41,7 +41,7 @@ For Git extraction, the CLI: 3. Sends commit messages and diffs to an LLM for analysis 4. Returns structured achievement objects with title, summary, and impact score -The LLM runs locally if you prefer. We support Ollama for fully offline extraction: +The LLM runs locally if you prefer. We support Ollama for fully offline extraction: ```bash bragdoc llm set ollama llama3.2 @@ -59,7 +59,7 @@ The clustering pipeline: **Embedding generation**: Each achievement gets converted to a 1536-dimensional vector using OpenAI's text-embedding-3-small model. The embedding captures semantic meaning, so similar achievements end up close together in vector space. -**DBSCAN clustering**: We use density-based clustering (DBSCAN) rather than k-means because we don't know how many clusters exist beforehand. DBSCAN finds natural groupings and handles outliers gracefully. Parameters adapt based on dataset size. +**DBSCAN clustering**: We use density-based clustering (DBSCAN) rather than k-means because we don't know how many clusters exist beforehand. DBSCAN finds natural groupings and handles outliers gracefully. Parameters adapt based on dataset size. **Workstream naming**: An LLM generates a 2-5 word name and one-sentence description for each cluster based on its achievements. "Payment System Refactor" rather than "Cluster 7." @@ -77,6 +77,8 @@ The flow: 3. You provide optional instructions for the AI ("Focus on leadership impact" or "Emphasize technical depth") 4. Click generate, and the document streams in +Say you have achievements like "Reduced API latency by 35%," "Implemented Redis caching layer," and "Optimized database queries for the checkout flow." The system recognizes these as related—they all live in a workstream called "Performance Optimization"—and weaves them into a coherent narrative rather than listing them as isolated bullet points. + The generated document is editable. After the initial generation, you can refine it through a chat interface—ask the AI to expand a section, add metrics, or adjust tone. The document updates in real-time. We use OpenAI's latest models for document generation because the quality difference matters for something you'll submit to your manager. Extraction can run on smaller models; the final document benefits from a more capable one. @@ -103,7 +105,7 @@ CLI (local) Web App Database │ │ ├─► Performance Review │ │ document generation │ - │ (streaming, GPT-4o) │ + │ (streaming, OpenAI) │ │ │ └─► Chat refinement │ (streaming) │ From c9c31bc0ca5a0788ef08d5ca0e4714a0836560e9 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:40:02 -0500 Subject: [PATCH 06/11] docs: rewrite blog as feature announcement Major restructure based on editorial feedback: - Lead with explicit feature announcement ("We're shipping...") - Add "What You Can Do Now" section with concrete user actions - Add functional checkpoints after each pipeline stage - Include status table differentiating stable/shipping/roadmap - Mark [NEW] features in architecture diagram - Rewrite CTA specifically for Performance Review feature - Close with announcement framing for review season context - Cut redundant technical repetition - Connect all architecture to user-facing actions Co-Authored-By: Claude Opus 4.5 --- .../from-commits-to-performance-review.mdx | 150 +++++++----------- 1 file changed, 61 insertions(+), 89 deletions(-) diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx index 85e0069d..a5e19bcb 100644 --- a/apps/marketing/content/blog/from-commits-to-performance-review.mdx +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -1,6 +1,6 @@ --- title: "How BragDoc Turns Git History into Performance Reviews" -description: "A look inside how BragDoc automates performance review documentation. CLI extraction, AI clustering, and document generation—from commits to review-ready docs." +description: "BragDoc's Performance Review feature is shipping now. Generate review-ready documents from your Git history—with AI clustering, streaming generation, and chat refinement." date: "2026-01-10" author: "BragDoc Team" tags: ["engineering", "performance-reviews", "architecture", "building-in-public", "workstreams"] @@ -10,144 +10,116 @@ published: false canonical_url: "https://www.bragdoc.ai/blog/from-commits-to-performance-review" --- -Performance review season is approaching. You have six months of commits, PRs, and closed tickets scattered across systems. Somewhere in that pile is the story of what you actually accomplished—but extracting it feels like archaeology. +**We're shipping Performance Review document generation.** Starting today, you can select a date range, click generate, and get a review-ready document built from your actual work history. -We're building BragDoc to solve this. The goal: turn your Git history into a performance review document with minimal manual effort. This post walks through how the pipeline works, what we've shipped, and what we're building next. +No more scrolling through six months of commits trying to reconstruct what you did. No more staring at a blank self-evaluation form. Your Git history becomes a polished document you can edit, refine, and submit. -## The Problem We're Solving +Here's what changed, what's available now, and how the system works. -Most developers track their work in at least four places: Git commits, GitHub PRs, issue trackers, and calendars. When review time comes, you're left reconstructing the narrative manually. You scroll through months of history, trying to remember which commits mattered and which were just noise. +## What You Can Do Now -The information exists. It's just not in a usable format. +The Performance Review feature turns months of scattered achievements into a structured document. Here's the workflow: -Our approach: extract achievements automatically, group them into coherent themes, and generate a document you can actually submit. Here's how each stage works. +1. **Select a date range** for your review period (Q4 2024, last 6 months, etc.) +2. **Add optional instructions** ("Focus on leadership impact" or "Emphasize technical depth") +3. **Click generate** and watch your document stream in +4. **Edit and refine** through a chat interface—ask the AI to expand sections, add metrics, or adjust tone -## Stage 1: Extraction via CLI +The document pulls from your achievements and workstreams automatically. If you've been extracting commits with the CLI, you already have the raw material. The Performance Review feature assembles it into something you can actually use. -Everything starts with the [BragDoc CLI](/features). It runs locally on your machine, which means your source code never leaves your computer. +**This is shipping now.** The core generation and editing flow is stable and ready for your next review cycle. -```bash -npm install -g @bragdoc/cli -bragdoc login -bragdoc init -bragdoc extract --since 30d -``` +## How the Pipeline Works -The CLI uses a pluggable connector architecture. Each data source—Git, GitHub, Jira—implements the same interface, so adding new sources doesn't require changing core logic. +Three stages turn your Git history into a performance review document. Each stage builds on the previous one. -For Git extraction, the CLI: -1. Reads your commit history within the specified date range -2. Applies branch whitelisting (so experimental branches don't pollute your achievements) -3. Sends commit messages and diffs to an LLM for analysis -4. Returns structured achievement objects with title, summary, and impact score +### Stage 1: Extraction (Stable) -The LLM runs locally if you prefer. We support Ollama for fully offline extraction: +The [BragDoc CLI](/features) extracts achievements from your local repositories. Your source code never leaves your machine. ```bash -bragdoc llm set ollama llama3.2 +bragdoc extract --since 6m ``` -Your diffs stay on your machine. Only the generated achievement summaries sync to the server. - -## Stage 2: Workstreams (Automatic Clustering) +The CLI reads your commit history, analyzes changes with an LLM, and returns structured achievements with titles, summaries, and impact scores. You can run extraction fully offline using Ollama. -Raw achievements are useful, but they don't tell a story. A six-month review period might produce 50+ achievements across different projects. Presenting that as a flat list isn't helpful. +**What this enables:** You stop losing track of what you shipped. Every meaningful commit becomes a documented achievement you can reference later. -This is where workstreams come in. They're automatically generated clusters of related achievements—themes that emerge from your work. +### Stage 2: Workstreams (Stable) -The clustering pipeline: +Raw achievements get clustered into themes automatically. We use DBSCAN clustering on semantic embeddings to find natural groupings in your work. -**Embedding generation**: Each achievement gets converted to a 1536-dimensional vector using OpenAI's text-embedding-3-small model. The embedding captures semantic meaning, so similar achievements end up close together in vector space. +Your 50+ achievements become 5-8 named workstreams like "Payment System Refactor" or "API Performance Optimization." Each workstream groups related work across the review period. -**DBSCAN clustering**: We use density-based clustering (DBSCAN) rather than k-means because we don't know how many clusters exist beforehand. DBSCAN finds natural groupings and handles outliers gracefully. Parameters adapt based on dataset size. +**What this enables:** You stop presenting flat lists of accomplishments. Your work gets organized into coherent themes that tell a story. -**Workstream naming**: An LLM generates a 2-5 word name and one-sentence description for each cluster based on its achievements. "Payment System Refactor" rather than "Cluster 7." +### Stage 3: Performance Review Document (Shipping Now) -The result: your 50 achievements become 5-8 workstreams with descriptive names. Each workstream groups related work, making it easier to explain what you actually accomplished. +This is the new feature. Select a date range, and the system loads your achievements and workstreams from that period. Add optional instructions, click generate, and the document streams in. -You can filter workstreams by date range and project. If you're preparing a Q4 review, you see only Q4 workstreams. The clustering runs on your filtered subset. +Say you have achievements like "Reduced API latency by 35%," "Implemented Redis caching layer," and "Optimized database queries." The system recognizes these as related—they live in your "Performance Optimization" workstream—and weaves them into a narrative rather than listing them as isolated bullet points. -## Stage 3: Performance Review Document (Shipping Now) +After generation, you edit through a chat interface. Ask the AI to expand a section, add quantitative impact, or match your company's review format. The document updates in real-time. -This is what we're actively building. The performance review feature takes your achievements and workstreams and generates an actual document. +**What this enables:** You stop writing performance reviews from scratch. You generate a first draft from real data, then refine it to match your voice and your company's expectations. -The flow: -1. Create a new performance review with a date range (e.g., "Q4 2024") -2. The system loads all achievements and workstreams from that period -3. You provide optional instructions for the AI ("Focus on leadership impact" or "Emphasize technical depth") -4. Click generate, and the document streams in +## What's Available Now vs Coming Soon -Say you have achievements like "Reduced API latency by 35%," "Implemented Redis caching layer," and "Optimized database queries for the checkout flow." The system recognizes these as related—they all live in a workstream called "Performance Optimization"—and weaves them into a coherent narrative rather than listing them as isolated bullet points. +| Feature | Status | +|---------|--------| +| CLI extraction (Git, GitHub) | **Stable** | +| Workstream clustering | **Stable** | +| Performance Review generation | **Shipping now** | +| Document editing via chat | **Shipping now** | +| Jira integration | In development | +| Google Calendar integration | On roadmap | -The generated document is editable. After the initial generation, you can refine it through a chat interface—ask the AI to expand a section, add metrics, or adjust tone. The document updates in real-time. +The extraction and clustering infrastructure has been stable for months. The Performance Review feature is new—we're releasing it now for review season. Jira and Calendar integrations will expand what gets captured, but the core pipeline is ready to use today. -We use OpenAI's latest models for document generation because the quality difference matters for something you'll submit to your manager. Extraction can run on smaller models; the final document benefits from a more capable one. +## How the Pieces Connect -## The Architecture - -Here's how the pieces connect: +For those who want the technical details: ``` CLI (local) Web App Database │ │ │ - ├─► Git extraction │ │ - │ via connectors │ │ + ├─► Extract commits │ │ + │ (your machine) │ │ │ │ │ - └─► POST /api/achievements ──────────────►│ + └─► POST achievements ─────────────────►│ │ │ ├─► Generate embeddings │ (OpenAI API) │ │ │ - ├─► DBSCAN clustering - │ (in-memory) │ - │ │ - ├─► Create workstreams ────►│ + ├─► Cluster into │ + │ workstreams │ │ │ - ├─► Performance Review │ - │ document generation │ - │ (streaming, OpenAI) │ + ├─► [NEW] Generate │ + │ performance review + │ (streaming) │ │ │ - └─► Chat refinement │ - (streaming) │ + └─► [NEW] Chat │ + refinement │ ``` -The CLI handles extraction. The web app handles clustering and document generation. Everything is scoped by user—your data stays yours. - -## What's Shipping Next - -We're expanding the connector architecture to pull from more sources: - -**Jira integration**: Extract achievements from closed tickets. Story points, sprint contributions, and ticket descriptions become part of your achievement record. - -**Google Calendar integration**: Meetings represent invisible work. Architecture discussions, 1:1 mentoring, planning sessions—these matter for reviews but don't show up in Git. Calendar integration captures them. +The CLI handles extraction locally—your diffs never leave your machine. The web app handles clustering and document generation. The new Performance Review feature sits at the end of this pipeline, consuming all the data you've already captured. -Both will work through the existing CLI. You'll configure sources per project, and `bragdoc extract` will pull from all of them. +## Try Performance Review Generation -## Why We're Building This Way +If you're preparing for a review cycle, here's how to get started: -A few design decisions worth explaining: +1. **[Install the CLI](/get-started)** and run `bragdoc extract --since 6m` on your repositories +2. **Open the web app** and navigate to Performance Reviews +3. **Create a new review** with your date range +4. **Generate your document** and refine it until it's ready to submit -**Local-first extraction**: Your code is sensitive. We don't want it on our servers, and you probably don't either. Running extraction locally means your diffs never leave your machine. Only the summaries sync. +The first draft takes seconds. Refinement takes as long as you need. Either way, you're starting from your actual work history instead of a blank page. -**Pluggable connectors**: Different teams use different tools. The connector architecture lets us add sources without touching core logic. Want to extract from GitLab instead of GitHub? Same interface, different implementation. - -**Semantic clustering over manual organization**: You could manually tag achievements into categories. Most people won't. Automatic clustering means you get organized output without extra work. - -**Streaming document generation**: Performance review documents are long. Waiting for a full document to generate is frustrating. Streaming shows progress immediately and lets you start reading before generation completes. - -## Try It - -If you're preparing for a performance review, the pipeline is ready to use: - -1. [Install the CLI](/get-started) and extract your recent commits -2. Generate workstreams from your achievements -3. Create a performance review and generate your document - -The whole process takes minutes instead of hours. Your Git history already contains the raw material—we just make it usable. +--- -We're building this in public because we think the approach matters as much as the product. If you have questions about the architecture or want to see specific features, [let us know](mailto:hello@bragdoc.ai). +**This is what we're putting in your hands now.** Performance Review document generation is built for engineers facing review season, promo packets, or compensation conversations. Your Git history already contains the evidence of what you accomplished—we're making it usable. ---- +Questions about the feature or feedback on the generation? [Let us know](mailto:hello@bragdoc.ai). **Related**: [Why Developers Need Automated Brag Docs](/blog/why-developers-need-automated-brag-docs) explains the problem in more depth. [Six Types of Developer Impact](/blog/six-types-developer-impact) covers what to include beyond code. From a342b1d5a02328018694fc81cdfad26192cc2adb Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:41:38 -0500 Subject: [PATCH 07/11] fix: update Q4 2024 to Q4 2025 in blog examples --- .../content/blog/from-commits-to-performance-review.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx index a5e19bcb..62f1989e 100644 --- a/apps/marketing/content/blog/from-commits-to-performance-review.mdx +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -20,7 +20,7 @@ Here's what changed, what's available now, and how the system works. The Performance Review feature turns months of scattered achievements into a structured document. Here's the workflow: -1. **Select a date range** for your review period (Q4 2024, last 6 months, etc.) +1. **Select a date range** for your review period (Q4 2025, last 6 months, etc.) 2. **Add optional instructions** ("Focus on leadership impact" or "Emphasize technical depth") 3. **Click generate** and watch your document stream in 4. **Edit and refine** through a chat interface—ask the AI to expand sections, add metrics, or adjust tone From 6b63977765beff58ad3ca01ce1e0e917fe3e58c0 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:42:22 -0500 Subject: [PATCH 08/11] fix: replace markdown table with list (MDX doesn't support tables) --- .../from-commits-to-performance-review.mdx | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx index 62f1989e..79cb4cfb 100644 --- a/apps/marketing/content/blog/from-commits-to-performance-review.mdx +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -65,14 +65,17 @@ After generation, you edit through a chat interface. Ask the AI to expand a sect ## What's Available Now vs Coming Soon -| Feature | Status | -|---------|--------| -| CLI extraction (Git, GitHub) | **Stable** | -| Workstream clustering | **Stable** | -| Performance Review generation | **Shipping now** | -| Document editing via chat | **Shipping now** | -| Jira integration | In development | -| Google Calendar integration | On roadmap | +**Stable:** +- CLI extraction (Git, GitHub) +- Workstream clustering + +**Shipping now:** +- Performance Review generation +- Document editing via chat + +**Coming soon:** +- Jira integration (in development) +- Google Calendar integration (on roadmap) The extraction and clustering infrastructure has been stable for months. The Performance Review feature is new—we're releasing it now for review season. Jira and Calendar integrations will expand what gets captured, but the core pipeline is ready to use today. From bc0dba455090c98967ce4ffaf06f4c48644e8911 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Fri, 9 Jan 2026 18:47:17 -0500 Subject: [PATCH 09/11] docs: apply fine-tuning feedback to blog post - Remove 1 redundant "shipping now" echo (keep in lede, Stage 3, status) - Clarify Git vs GitHub: Stage 1 is local Git, GitHub is separate connector - Add privacy clarification: embeddings use summaries, not source code - Add output description to CTA: "review draft organized by workstreams" - Add specific feedback channels: GitHub issues + email Co-Authored-By: Claude Opus 4.5 --- .../from-commits-to-performance-review.mdx | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/apps/marketing/content/blog/from-commits-to-performance-review.mdx b/apps/marketing/content/blog/from-commits-to-performance-review.mdx index 79cb4cfb..e549d79d 100644 --- a/apps/marketing/content/blog/from-commits-to-performance-review.mdx +++ b/apps/marketing/content/blog/from-commits-to-performance-review.mdx @@ -27,21 +27,19 @@ The Performance Review feature turns months of scattered achievements into a str The document pulls from your achievements and workstreams automatically. If you've been extracting commits with the CLI, you already have the raw material. The Performance Review feature assembles it into something you can actually use. -**This is shipping now.** The core generation and editing flow is stable and ready for your next review cycle. - ## How the Pipeline Works Three stages turn your Git history into a performance review document. Each stage builds on the previous one. ### Stage 1: Extraction (Stable) -The [BragDoc CLI](/features) extracts achievements from your local repositories. Your source code never leaves your machine. +The [BragDoc CLI](/features) extracts achievements from your local Git repositories. Your source code never leaves your machine. ```bash bragdoc extract --since 6m ``` -The CLI reads your commit history, analyzes changes with an LLM, and returns structured achievements with titles, summaries, and impact scores. You can run extraction fully offline using Ollama. +The CLI reads your local commit history, analyzes changes with an LLM, and returns structured achievements with titles, summaries, and impact scores. For teams using GitHub, the CLI can also pull PR metadata and code review activity through a separate connector. You can run extraction fully offline using Ollama. **What this enables:** You stop losing track of what you shipped. Every meaningful commit becomes a documented achievement you can reference later. @@ -66,12 +64,12 @@ After generation, you edit through a chat interface. Ask the AI to expand a sect ## What's Available Now vs Coming Soon **Stable:** -- CLI extraction (Git, GitHub) +- CLI extraction (local Git + GitHub connector) - Workstream clustering **Shipping now:** -- Performance Review generation -- Document editing via chat +- Performance Review document generation +- Chat-based document editing **Coming soon:** - Jira integration (in development) @@ -105,7 +103,7 @@ CLI (local) Web App Database refinement │ ``` -The CLI handles extraction locally—your diffs never leave your machine. The web app handles clustering and document generation. The new Performance Review feature sits at the end of this pipeline, consuming all the data you've already captured. +The CLI handles extraction locally—your diffs never leave your machine. Only the generated achievement summaries sync to the server. When we generate embeddings for clustering, we're embedding those summaries, not your source code. The web app handles clustering and document generation. The new Performance Review feature sits at the end of this pipeline, consuming all the data you've already captured. ## Try Performance Review Generation @@ -116,13 +114,15 @@ If you're preparing for a review cycle, here's how to get started: 3. **Create a new review** with your date range 4. **Generate your document** and refine it until it's ready to submit +You'll end up with a review draft organized by workstreams, ready to copy into your company's review form or export as-is. + The first draft takes seconds. Refinement takes as long as you need. Either way, you're starting from your actual work history instead of a blank page. --- **This is what we're putting in your hands now.** Performance Review document generation is built for engineers facing review season, promo packets, or compensation conversations. Your Git history already contains the evidence of what you accomplished—we're making it usable. -Questions about the feature or feedback on the generation? [Let us know](mailto:hello@bragdoc.ai). +Questions or feedback? Open an issue on GitHub or email us at hello@bragdoc.ai. **Related**: [Why Developers Need Automated Brag Docs](/blog/why-developers-need-automated-brag-docs) explains the problem in more depth. [Six Types of Developer Impact](/blog/six-types-developer-impact) covers what to include beyond code. From bc2eef106f5e069f00efcc6ee26838262a7798b8 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Tue, 13 Jan 2026 16:55:57 -0500 Subject: [PATCH 10/11] docs: add email templates for Loops.so onboarding sequence 4-email nurture sequence for new signups: - Day 0: Welcome + CLI install instructions - Day 3: The problem (visibility gap education) - Day 7: Quick win (workstreams feature) - Day 14: Check-in (plain text re-engagement) Includes HTML, Markdown, and plain text versions. Co-Authored-By: Claude Opus 4.5 --- .claude/docs/processes/email-templates.html | 115 +++++++++++++ .claude/docs/processes/email-templates.md | 182 ++++++++++++++++++++ .claude/docs/processes/email-templates.txt | 107 ++++++++++++ 3 files changed, 404 insertions(+) create mode 100644 .claude/docs/processes/email-templates.html create mode 100644 .claude/docs/processes/email-templates.md create mode 100644 .claude/docs/processes/email-templates.txt diff --git a/.claude/docs/processes/email-templates.html b/.claude/docs/processes/email-templates.html new file mode 100644 index 00000000..01849432 --- /dev/null +++ b/.claude/docs/processes/email-templates.html @@ -0,0 +1,115 @@ + + + + + BragDoc Email Templates + + + + + + + + + + + + + + + + + + diff --git a/.claude/docs/processes/email-templates.md b/.claude/docs/processes/email-templates.md new file mode 100644 index 00000000..7cc75dd3 --- /dev/null +++ b/.claude/docs/processes/email-templates.md @@ -0,0 +1,182 @@ +# BragDoc Email Templates (Loops.so) + +Email sequence for new signups who haven't fully activated. + +## Sequence Overview + +| # | Email | When | Goal | +|---|-------|------|------| +| 1 | Welcome | Immediate (Day 0) | Get them to install CLI | +| 2 | The problem | Day 3 | Educate, build urgency | +| 3 | Quick win | Day 7 | Show value, re-engage | +| 4 | Check-in | Day 14 | Catch stragglers | + +--- + +## Email 1: Welcome + +**Trigger:** Immediate after signup (Day 0) + +**Subject:** You're in. Here's how to get started. + +**Body:** + +``` +Hey, + +Thanks for signing up for BragDoc. + +The fastest way to get value: install the CLI and run your first extraction. Takes about 2 minutes. + +npm install -g @bragdoc/cli +bragdoc login +bragdoc extract --since 3m + +That pulls the last 3 months of your Git history and turns it into documented achievements. Your code stays local - only the summaries sync. + +Once you've extracted, you can see your achievements in the dashboard, watch them cluster into workstreams, and eventually generate performance review docs from them. + +Questions? Just reply to this email. + +- The BragDoc team +``` + +**Notes:** +- Short +- One clear CTA (install and extract) +- Addresses privacy concern upfront +- "Reply to this email" feels personal + +--- + +## Email 2: The Problem + +**Trigger:** Day 3 after signup + +**Subject:** The thing about performance reviews + +**Body:** + +``` +Quick story. + +Every review cycle, engineers scramble to remember what they did. They scroll through 6 months of commits, skim old PRs, and try to reconstruct their impact from memory. + +The result? They undersell themselves. They forget the hard stuff. They write vague bullet points like "contributed to several projects" and hope their manager fills in the gaps. + +Managers don't fill in the gaps. They're busy. They have 8 other people to review. They rely on what you tell them. + +This is the visibility gap - and it's why engineers who document well get promoted faster than engineers who just do good work. + +BragDoc fixes this by capturing your work as it happens. Your Git history already contains the evidence. We just make it usable. + +If you haven't run your first extraction yet: + +bragdoc extract --since 6m + +Takes 2 minutes. You'll have 6 months of achievements documented before your next meeting. + +- BragDoc +``` + +**Notes:** +- Storytelling, not feature list +- Hits the emotional pain point (underselling yourself) +- Reinforces the CTA without being pushy + +--- + +## Email 3: Quick Win + +**Trigger:** Day 7 after signup + +**Subject:** One thing you can do today + +**Body:** + +``` +If you've already extracted your achievements - nice. You're ahead of most engineers. + +Here's what to do next: look at your workstreams. + +BragDoc automatically groups your achievements into themes. So instead of a flat list of 50 things you did, you get 5-8 named workstreams like "Payment System Refactor" or "API Performance." + +This matters because review conversations aren't about individual commits. They're about patterns. "I led three major infrastructure initiatives this year" lands better than "I made 200 commits." + +Check your workstreams in the dashboard. If they don't look right, you can rename or reorganize them. + +And if you haven't extracted yet - now's a good time. Review season is coming. + +bragdoc extract --since 6m + +- BragDoc +``` + +**Notes:** +- Assumes some users engaged, acknowledges them +- Teaches something (workstreams = patterns = better story) +- Gentle nudge for non-extractors +- Seasonal urgency without being salesy + +--- + +## Email 4: Check-in + +**Trigger:** Day 14 after signup + +**Subject:** Quick question + +**Body:** + +``` +Hey, + +Noticed you signed up a couple weeks ago. Just wanted to check in. + +Did you get a chance to run an extraction? If something didn't work or wasn't clear, I'd like to know. + +If you're waiting for a better time - review season is coming up fast. Most engineers wish they'd started documenting earlier. Now's a good window. + +Either way, no pressure. Just reply if you have questions. + +- Natalia +``` + +**Notes:** +- Plain text (no design, feels personal) +- Short +- From a person's name, not "The Team" +- Asks a question (invites reply) +- Soft urgency without desperation + +--- + +## Segmentation Strategy + +After Day 14: +- **Engaged users (extracted):** Move to product update / feature announcement list +- **Non-engaged users:** Move to monthly newsletter (lower frequency) +- **Non-openers:** Consider sunset after 60 days of no opens + +--- + +## Key Events to Track in Loops + +1. `user.signed_up` - triggers welcome sequence +2. `user.extracted` - marks activation, stops nudge emails +3. `user.generated_review` - high-value action +4. `user.inactive_14d` - triggers check-in + +--- + +## Seasonal Campaigns (Outside Core Sequence) + +**Q4 (Oct-Dec) and Q1 (Jan-Feb):** Performance review season +- Increase email frequency +- Focus on review generation feature +- Subject lines referencing "review season" + +**Example seasonal subject lines:** +- "Review season is here" +- "Your Q4 achievements, documented" +- "Before your next 1:1" diff --git a/.claude/docs/processes/email-templates.txt b/.claude/docs/processes/email-templates.txt new file mode 100644 index 00000000..b8443bb8 --- /dev/null +++ b/.claude/docs/processes/email-templates.txt @@ -0,0 +1,107 @@ +BRAGDOC EMAIL TEMPLATES +======================= + +================================================================================ +EMAIL 1: WELCOME +Trigger: Day 0 (immediate after signup) +================================================================================ + +Subject: You're in. Here's how to get started. + +--- + +Hey, + +Thanks for signing up for BragDoc. + +The fastest way to get value: install the CLI and run your first extraction. Takes about 2 minutes. + +npm install -g @bragdoc/cli +bragdoc login +bragdoc extract --since 3m + +That pulls the last 3 months of your Git history and turns it into documented achievements. Your code stays local - only the summaries sync. + +Once you've extracted, you can see your achievements in the dashboard, watch them cluster into workstreams, and eventually generate performance review docs from them. + +Questions? Just reply to this email. + +- The BragDoc team + + +================================================================================ +EMAIL 2: THE PROBLEM +Trigger: Day 3 +================================================================================ + +Subject: The thing about performance reviews + +--- + +Quick story. + +Every review cycle, engineers scramble to remember what they did. They scroll through 6 months of commits, skim old PRs, and try to reconstruct their impact from memory. + +The result? They undersell themselves. They forget the hard stuff. They write vague bullet points like "contributed to several projects" and hope their manager fills in the gaps. + +Managers don't fill in the gaps. They're busy. They have 8 other people to review. They rely on what you tell them. + +This is the visibility gap - and it's why engineers who document well get promoted faster than engineers who just do good work. + +BragDoc fixes this by capturing your work as it happens. Your Git history already contains the evidence. We just make it usable. + +If you haven't run your first extraction yet: + +bragdoc extract --since 6m + +Takes 2 minutes. You'll have 6 months of achievements documented before your next meeting. + +- BragDoc + + +================================================================================ +EMAIL 3: QUICK WIN +Trigger: Day 7 +================================================================================ + +Subject: One thing you can do today + +--- + +If you've already extracted your achievements - nice. You're ahead of most engineers. + +Here's what to do next: look at your workstreams. + +BragDoc automatically groups your achievements into themes. So instead of a flat list of 50 things you did, you get 5-8 named workstreams like "Payment System Refactor" or "API Performance." + +This matters because review conversations aren't about individual commits. They're about patterns. "I led three major infrastructure initiatives this year" lands better than "I made 200 commits." + +Check your workstreams in the dashboard. If they don't look right, you can rename or reorganize them. + +And if you haven't extracted yet - now's a good time. Review season is coming. + +bragdoc extract --since 6m + +- BragDoc + + +================================================================================ +EMAIL 4: CHECK-IN +Trigger: Day 14 +================================================================================ + +Subject: Quick question + +--- + +Hey, + +Noticed you signed up a couple weeks ago. Just wanted to check in. + +Did you get a chance to run an extraction? If something didn't work or wasn't clear, I'd like to know. + +If you're waiting for a better time - review season is coming up fast. Most engineers wish they'd started documenting earlier. Now's a good window. + +Either way, no pressure. Just reply if you have questions. + +- Natalia From 04153c41e38bad826af18e2da87a024950fa3177 Mon Sep 17 00:00:00 2001 From: Natalia Spencer Date: Tue, 13 Jan 2026 17:01:57 -0500 Subject: [PATCH 11/11] Revert "docs: add email templates for Loops.so onboarding sequence" This reverts commit bc2eef106f5e069f00efcc6ee26838262a7798b8. --- .claude/docs/processes/email-templates.html | 115 ------------- .claude/docs/processes/email-templates.md | 182 -------------------- .claude/docs/processes/email-templates.txt | 107 ------------ 3 files changed, 404 deletions(-) delete mode 100644 .claude/docs/processes/email-templates.html delete mode 100644 .claude/docs/processes/email-templates.md delete mode 100644 .claude/docs/processes/email-templates.txt diff --git a/.claude/docs/processes/email-templates.html b/.claude/docs/processes/email-templates.html deleted file mode 100644 index 01849432..00000000 --- a/.claude/docs/processes/email-templates.html +++ /dev/null @@ -1,115 +0,0 @@ - - - - - BragDoc Email Templates - - - - - - - - - - - - - - - - - - diff --git a/.claude/docs/processes/email-templates.md b/.claude/docs/processes/email-templates.md deleted file mode 100644 index 7cc75dd3..00000000 --- a/.claude/docs/processes/email-templates.md +++ /dev/null @@ -1,182 +0,0 @@ -# BragDoc Email Templates (Loops.so) - -Email sequence for new signups who haven't fully activated. - -## Sequence Overview - -| # | Email | When | Goal | -|---|-------|------|------| -| 1 | Welcome | Immediate (Day 0) | Get them to install CLI | -| 2 | The problem | Day 3 | Educate, build urgency | -| 3 | Quick win | Day 7 | Show value, re-engage | -| 4 | Check-in | Day 14 | Catch stragglers | - ---- - -## Email 1: Welcome - -**Trigger:** Immediate after signup (Day 0) - -**Subject:** You're in. Here's how to get started. - -**Body:** - -``` -Hey, - -Thanks for signing up for BragDoc. - -The fastest way to get value: install the CLI and run your first extraction. Takes about 2 minutes. - -npm install -g @bragdoc/cli -bragdoc login -bragdoc extract --since 3m - -That pulls the last 3 months of your Git history and turns it into documented achievements. Your code stays local - only the summaries sync. - -Once you've extracted, you can see your achievements in the dashboard, watch them cluster into workstreams, and eventually generate performance review docs from them. - -Questions? Just reply to this email. - -- The BragDoc team -``` - -**Notes:** -- Short -- One clear CTA (install and extract) -- Addresses privacy concern upfront -- "Reply to this email" feels personal - ---- - -## Email 2: The Problem - -**Trigger:** Day 3 after signup - -**Subject:** The thing about performance reviews - -**Body:** - -``` -Quick story. - -Every review cycle, engineers scramble to remember what they did. They scroll through 6 months of commits, skim old PRs, and try to reconstruct their impact from memory. - -The result? They undersell themselves. They forget the hard stuff. They write vague bullet points like "contributed to several projects" and hope their manager fills in the gaps. - -Managers don't fill in the gaps. They're busy. They have 8 other people to review. They rely on what you tell them. - -This is the visibility gap - and it's why engineers who document well get promoted faster than engineers who just do good work. - -BragDoc fixes this by capturing your work as it happens. Your Git history already contains the evidence. We just make it usable. - -If you haven't run your first extraction yet: - -bragdoc extract --since 6m - -Takes 2 minutes. You'll have 6 months of achievements documented before your next meeting. - -- BragDoc -``` - -**Notes:** -- Storytelling, not feature list -- Hits the emotional pain point (underselling yourself) -- Reinforces the CTA without being pushy - ---- - -## Email 3: Quick Win - -**Trigger:** Day 7 after signup - -**Subject:** One thing you can do today - -**Body:** - -``` -If you've already extracted your achievements - nice. You're ahead of most engineers. - -Here's what to do next: look at your workstreams. - -BragDoc automatically groups your achievements into themes. So instead of a flat list of 50 things you did, you get 5-8 named workstreams like "Payment System Refactor" or "API Performance." - -This matters because review conversations aren't about individual commits. They're about patterns. "I led three major infrastructure initiatives this year" lands better than "I made 200 commits." - -Check your workstreams in the dashboard. If they don't look right, you can rename or reorganize them. - -And if you haven't extracted yet - now's a good time. Review season is coming. - -bragdoc extract --since 6m - -- BragDoc -``` - -**Notes:** -- Assumes some users engaged, acknowledges them -- Teaches something (workstreams = patterns = better story) -- Gentle nudge for non-extractors -- Seasonal urgency without being salesy - ---- - -## Email 4: Check-in - -**Trigger:** Day 14 after signup - -**Subject:** Quick question - -**Body:** - -``` -Hey, - -Noticed you signed up a couple weeks ago. Just wanted to check in. - -Did you get a chance to run an extraction? If something didn't work or wasn't clear, I'd like to know. - -If you're waiting for a better time - review season is coming up fast. Most engineers wish they'd started documenting earlier. Now's a good window. - -Either way, no pressure. Just reply if you have questions. - -- Natalia -``` - -**Notes:** -- Plain text (no design, feels personal) -- Short -- From a person's name, not "The Team" -- Asks a question (invites reply) -- Soft urgency without desperation - ---- - -## Segmentation Strategy - -After Day 14: -- **Engaged users (extracted):** Move to product update / feature announcement list -- **Non-engaged users:** Move to monthly newsletter (lower frequency) -- **Non-openers:** Consider sunset after 60 days of no opens - ---- - -## Key Events to Track in Loops - -1. `user.signed_up` - triggers welcome sequence -2. `user.extracted` - marks activation, stops nudge emails -3. `user.generated_review` - high-value action -4. `user.inactive_14d` - triggers check-in - ---- - -## Seasonal Campaigns (Outside Core Sequence) - -**Q4 (Oct-Dec) and Q1 (Jan-Feb):** Performance review season -- Increase email frequency -- Focus on review generation feature -- Subject lines referencing "review season" - -**Example seasonal subject lines:** -- "Review season is here" -- "Your Q4 achievements, documented" -- "Before your next 1:1" diff --git a/.claude/docs/processes/email-templates.txt b/.claude/docs/processes/email-templates.txt deleted file mode 100644 index b8443bb8..00000000 --- a/.claude/docs/processes/email-templates.txt +++ /dev/null @@ -1,107 +0,0 @@ -BRAGDOC EMAIL TEMPLATES -======================= - -================================================================================ -EMAIL 1: WELCOME -Trigger: Day 0 (immediate after signup) -================================================================================ - -Subject: You're in. Here's how to get started. - ---- - -Hey, - -Thanks for signing up for BragDoc. - -The fastest way to get value: install the CLI and run your first extraction. Takes about 2 minutes. - -npm install -g @bragdoc/cli -bragdoc login -bragdoc extract --since 3m - -That pulls the last 3 months of your Git history and turns it into documented achievements. Your code stays local - only the summaries sync. - -Once you've extracted, you can see your achievements in the dashboard, watch them cluster into workstreams, and eventually generate performance review docs from them. - -Questions? Just reply to this email. - -- The BragDoc team - - -================================================================================ -EMAIL 2: THE PROBLEM -Trigger: Day 3 -================================================================================ - -Subject: The thing about performance reviews - ---- - -Quick story. - -Every review cycle, engineers scramble to remember what they did. They scroll through 6 months of commits, skim old PRs, and try to reconstruct their impact from memory. - -The result? They undersell themselves. They forget the hard stuff. They write vague bullet points like "contributed to several projects" and hope their manager fills in the gaps. - -Managers don't fill in the gaps. They're busy. They have 8 other people to review. They rely on what you tell them. - -This is the visibility gap - and it's why engineers who document well get promoted faster than engineers who just do good work. - -BragDoc fixes this by capturing your work as it happens. Your Git history already contains the evidence. We just make it usable. - -If you haven't run your first extraction yet: - -bragdoc extract --since 6m - -Takes 2 minutes. You'll have 6 months of achievements documented before your next meeting. - -- BragDoc - - -================================================================================ -EMAIL 3: QUICK WIN -Trigger: Day 7 -================================================================================ - -Subject: One thing you can do today - ---- - -If you've already extracted your achievements - nice. You're ahead of most engineers. - -Here's what to do next: look at your workstreams. - -BragDoc automatically groups your achievements into themes. So instead of a flat list of 50 things you did, you get 5-8 named workstreams like "Payment System Refactor" or "API Performance." - -This matters because review conversations aren't about individual commits. They're about patterns. "I led three major infrastructure initiatives this year" lands better than "I made 200 commits." - -Check your workstreams in the dashboard. If they don't look right, you can rename or reorganize them. - -And if you haven't extracted yet - now's a good time. Review season is coming. - -bragdoc extract --since 6m - -- BragDoc - - -================================================================================ -EMAIL 4: CHECK-IN -Trigger: Day 14 -================================================================================ - -Subject: Quick question - ---- - -Hey, - -Noticed you signed up a couple weeks ago. Just wanted to check in. - -Did you get a chance to run an extraction? If something didn't work or wasn't clear, I'd like to know. - -If you're waiting for a better time - review season is coming up fast. Most engineers wish they'd started documenting earlier. Now's a good window. - -Either way, no pressure. Just reply if you have questions. - -- Natalia