• Every presenter converged on the same pattern from different angles: iterating quickly towards product-market fit, leveraging strengths as a domain expert, and listening closely to what actually needs solving rather than getting caught up with the tooling.
• Learn to understand pain better than the builders do. That’s where the leverage is when combined with agentic tooling.
• The people winning right now are those who actively collapse the distance between “I understand this problem” and “I built the solution.” Sharpening these tools daily, even for a few hours, compounds quickly.
• Keep your orchestration agent lean and leverage subagents to optimize your context window. See my AGENTS.md @ 99a8c1b for my latest thinking and application on this.
• Sign up early to present at the next round of lightning talks.

The shift came after reading Jon Magic’s “How I Work, 2025 Edition” and revisiting Ben Balter’s “Why everything should have a URL”. As someone who’s worked with Git since 2012, the transition felt natural—directing my working memory into version control rather than scattered notes apps.

The immediate benefit: performance reviews and accountability. Instead of scrambling to remember what happened in the last quarter, I had a structured log. Over the past few months, I’ve used this system to understand my own processes better.

Current Structure (April 2026)

• Daily Projects — Day-level focus logs and context, organized by date
• Weekly Notes — Planning, goals, and backlinks; weekly anchors for reflection
• Meeting Notes — Conversations with timestamps and action items
• Snippets — Weekly accomplishment summaries (Ships, Collabs, Risks, etc.)
• Executive Summaries — Distilled updates for leadership
• Projects — Multi-week initiatives with milestones and resources
• Self — Personal context: assessments, performance reviews, goals, personality insights
• Feedback, Transcripts, Templates, Archive — Supporting systems

Automation Skills

I’ve built several agent skills to power the workflow:

• Creating daily notes
• Summarizing weekly notes
• Transforming meeting transcripts into reusable artifacts
• PR review assist: tracking reviews and reusable context

What the Git Log Reveals

The real insight came from studying the corpus itself. I’ve used the historical record to crawl my writing, build a personal writing style guide (packaged as an agent skill), and link ideas across contexts. But the most revealing discovery was what Git captures unintentionally.

The Commit Graph as Data

The content of each note is intentional—I chose every word. But the commit graph isn’t. The timestamps, cadence, and gaps accumulated without my direction.

The gaps are information too. What doesn’t appear in the commit history is as expressive as what does.

• Weekends are nearly silent (intentional design working as intended)
• The system is almost entirely optimized for capture, not retrieval testing. Writing something down is treated as equivalent to knowing it. The implicit bet: git log itself is the retrieval mechanism. When I need to reconstruct February, I run the log, filter by date, and follow the breadcrumbs.

Time Made Legible

It’s easy to treat version control as a technical requirement—something developers use because that’s what we do. But in a knowledge system, Git does something different: it makes time legible.

• Every commit is an unfakeable timestamp
• Every commit message is a claim about intent
• Every diff is the delta between two states of mind
• The full history is preserved—not edited, not summarized, not lost

You can go back and see not just what you thought, but when you thought it and how confident you were.

This is what separates it from a notes app. Notes apps store content. Git stores content and the progression of content over time. The progression is often more valuable than any single snapshot.

Where This Is Headed

The system is alive and imperfect. Some weeks are captured in detail; others get a single setup commit and nothing more. The structure has evolved—directories renamed, skills removed, workflows refactored. That evolution is documented too (which is the point).

The goal was never perfection. It was to build a system that improves through use—and that leaves enough of a trail that anyone paying close attention can see the shape of the work over time.

Resources:

• second-brain-template (open source)

What started as a small project to store tariff data in a SQL database and make it queryable through a CLI grew into something much broader: an MCP server, a publicly searchable index powered by Datasette and Fly.io, and an exported Python library that developers can integrate into their code (though at time of writing, not published to any registry–but certainly possible!). It’s all published as an open source repository at francisfuzz/tariff-everywhere.

Give it a try: https://tariff-everywhere.fly.dev/

How it started

Straight from the United States International Trade Commission’s site:

The Harmonized Tariff Schedule of the United States (HTS) sets out the tariff rates and statistical categories for all merchandise imported into the United States. The HTS is based on the international Harmonized System, which is the global system of nomenclature applied to most world trade in goods.

When I started exploring the US International Trade Commission’s API, I was just trying to understand what was there. The public endpoint was less documented than I expected, and the original plan I’d sketched referenced an endpoint that no longer worked. That initial confusion actually shaped everything that came after.

The real API turned out to be simpler than I’d feared: a flat JSON feed returning about 28,750 tariff entries across 99 chapters. No pagination helpers, no release versioning—just straightforward data. A chapter-based ingest pattern was a natural fit: download one chapter at a time, parse it, store it. It scales linearly and gives you natural checkpoints.

I documented these learnings in early commits because I knew future me would forget the dead ends. 🙈

Building Three Layers

Once I understood the API shape, I needed to figure out how to make this data actually useful. I wanted it to work in three contexts: from the command line for developers, as an MCP server for Claude, and eventually as a browsable interface. But first things first—I had to build the foundation.

The ingest script was straightforward: hit the API for all 99 chapters, parse the JSON, and store everything in SQLite. I created three tables—chapters, hts_entries, and data_freshness—to capture both the tariff data and metadata about when things were last checked. About 134,000 entries in total. It’s a lot of data, but SQLite handles it without breaking a sweat.

The CLI came next, built with Typer. I put together commands for searching by keyword, looking up exact codes, browsing by chapter, and retrieving metadata. Then I built an MCP server that exposed the same queries over stdio for Claude integration. The MCP work taught me something about JSON handling—Claude pointed out that using print() directly instead of Rich’s console formatting keeps ANSI control characters out of the JSON output. A small detail, but one that matters for clean integration.

Tests were important here too. I built the test suite early, using in-memory SQLite fixtures so tests run fast and don’t depend on actual database state. That pattern paid off immediately when refactoring came later.

The Freshness Problem

Once the initial ingest worked, I started thinking about what happens when tariff data changes. The USITC doesn’t expose revision numbers or release dates, so I needed another way to detect staleness. The solution was content hashing: hash each chapter, compare against what’s stored, and only re-ingest if something actually changed.

The refresh script handles this in parallel. It spins up a thread pool, hashes all 99 chapters at once, and compares the results to what’s in the database. If a chapter’s content differs, that chapter gets re-ingested. I also started tracking two timestamps per chapter: when we last checked and when the data actually changed. That distinction matters—it tells you whether something is truly stale or just old data you’ve already validated.

Before any refresh operation, the script creates a backup. It’s a simple step, but it means if something goes wrong, you can recover. Defensive programming isn’t paranoia—it’s respecting that production systems have higher stakes than development. The backup costs almost nothing and buys a lot of peace of mind.

This is where I learned to distinguish between ingest and refresh. Ingest is destructive—it rebuilds everything from scratch. Refresh is careful—it validates, updates selectively, and preserves the database. They have different failure modes, and treating them as such made the system safer.

Stopping to Refactor

At some point, I noticed I was duplicating query logic between the CLI and the MCP server. Both needed the same database operations, just with different invocation patterns. This bothered me more than it should have, so I stopped feature work and extracted a shared core library—which later became an exportable Python module.

Creating hts_core/ with a configurable database path meant both interfaces could import the same functions. Now when I need to change how queries work, I change them in one place. It’s the kind of refactoring that seems optional until you need to update something three months later and realize how grateful you are to past you.

I also hardened the Docker setup and added CI: GitHub Actions runs the test suite on every commit. Standard stuff, but it matters to know the project works reliably—and if it breaks, I’ll know immediately.

The Datasette Pivot

Claude suggested something that changed how I thought about the project: “What if we exposed this as a searchable web interface?” I’d been thinking CLI and MCP only, but that question opened something up. Why shouldn’t people be able to browse tariffs in a browser?

That’s how I ended up building Datasette integration. Datasette is remarkable—it lets you publish a SQLite database as a web interface without writing any web code. Point it at your database, and you have a searchable, browsable interface with full-text search on tariff descriptions. No Flask routes, no HTML templates, no API endpoints to maintain.

The integration taught me some hard lessons. If you create FTS5 indexes with raw SQL, Datasette won’t auto-detect them—but if you create them with sqlite-utils, Datasette sees them immediately. I learned that the hard way when I deployed the first version and search didn’t work. I also ran into a Typer/click compatibility issue that took some untangling.

Getting the chapter titles right was a small thing that mattered a lot. Instead of showing “Chapter 01,” the interface now shows “Live Animals” or “Copper and Articles Thereof.” Users see actual chapter names instead of numbers. Some entries have <i> tags for scientific names, so I installed datasette-render-html to make those render correctly instead of showing raw HTML.

This pivot—from API-only to browsable web interface—is probably the thing I’m most proud of. It made the tariff data accessible to people who don’t write code.

Getting the Name Right

At some point it became clear that usitc-app was the wrong name. It was descriptive—it told you what API it used—but it didn’t communicate what the project did or why you’d want to use it. After thinking about what this thing really was, the name tariff-everywhere emerged: a lookup service you can use everywhere—in your terminal, in Claude, in a web browser. Anywhere you might need to understand a tariff code.

The rename was methodical: first the repository references, then the live web app URL, then the deployment configurations. I could have left stray references to the old name, but that’s the kind of thing that bugs future maintainers. If you’re going to rename something, rename it all the way through.

Documentation and Licensing

A project isn’t really done until someone else can use and maintain it. I rewrote the README to guide people through the three ways they can use tariff-everywhere: from the command line as a developer, as an MCP server with Claude, or as a web interface to just look something up. Each mode has its own documentation, all starting from the same place.

CLAUDE.md became the deep documentation: architecture, patterns, how to debug when things go wrong, how to deploy. I wrote it knowing that future work on this project will probably involve Claude, and whoever touches the code next should understand the decisions that were made.

I also chose the Hippocratic License—an open-source license that protects against the code being used to cause harm. I wanted the code to be open (that’s important to me), but I also wanted guardrails. The Hippocratic License gave me both.

Licensing and documentation are the things people don’t think about when they’re building, but they matter enormously for longevity. A project without documentation dies. A project without thoughtful licensing can end up in places you never intended.

Building With AI

The interesting thing about this project is that Claude was a thinking partner the whole way through. When I was confused about the API, Claude helped me understand what I was looking at. When I missed an ANSI control character vulnerability, Claude caught it. When I was stuck in a CLI-only mindset, Claude suggested a web interface and changed the whole trajectory of the project.

The later commits show the work of preparing the repository for ongoing collaboration with Claude: adding .claude/ to gitignore, documenting patterns and decisions in a way that makes sense to an AI reading the codebase, and revising the core instructions when we missed something. This created a nice loop of shipping, pivoting, and grounding the work. The full CLAUDE.md history is telling in what we went back and forth on (Docker 😉).

This loop came up a lot in my mind and practice as we worked together:

Articulation → Discovery → Explain → Plan → Edit → Review → Refactor → Agent → Monitor → Learn
     ↑                                                                                      |
     └────────────────────── reflection loop ───────────────────────────────────────────────┘

What This Whole Thing Taught Me

Defensive thinking matters. For every feature I added, I asked “what goes wrong?” first. Backups before mutations. Hashes to detect changes. Tests that run in isolation. None of it is glamorous, but it’s the difference between a project you can trust and one you can’t.

Refactoring when you spot duplication pays dividends. The hts_core/ extraction wasn’t required, but it meant later changes happened in one place instead of three.

Naming is important. usitc-app was technically correct and completely unmemorable. tariff-everywhere tells you what the project does and how it works. Spend the time on names.

Many modes of interaction beat one. A CLI for developers. An MCP server for Claude users. A web interface for everyone else. Same underlying code, three entry points. That’s good design.

Documentation is not optional. Not as a checkbox, but because the next person to touch this code—including me, three months from now—needs to understand why decisions were made. CLAUDE.md isn’t a reference manual; it’s the paper trail of thinking.

What Remains

The project is functional. All three modes work—CLI, MCP, web. Tests pass. The Datasette instance is live. The code is documented. The decisions are recorded. If I walked away today, someone could pick this up and maintain it. That feels complete—for now, until I come back to it.

What I’ve tried to do is leave the best gift a developer can leave: a codebase where decisions are explained, not just implemented. Where defensive patterns are intentional, not random. Where someone—whether that’s me in a few months or someone else entirely—can understand not just what the code does, but why it was built that way.

Give it a try: https://tariff-everywhere.fly.dev/

Inspired by Oxide Computer Company’s “Why Does Oxide Use Rust?” blog post, I created this project to pick up Rust again. I planned the build with Claude and chose Rust as the base programming language for this command-line interface.

Getting Started

I had some free hours last weekend and checked in throughout the week. I learned how to use Claude more effectively and optimize my token usage. I learned about Cargo as a build system, setting up GitHub Actions workflows for CI/CD with Rust projects, and using the emojis package for random emoji selection.

The last time I touched Rust was a few years ago during a two-day O’Reilly course presented by my co-worker Nathan Stocks. I hadn’t picked it up since, but with the momentum in AI agentic workflows, I thought: why not build something with a language that has speed and tailwind advantage?

Planning and Ideation

I started by planning the build with Claude. Since I was on-the-go, I used Claude Chat to outline what I wanted, then compacted that context for Claude Code to execute. I had the scaffold ready from my mobile ideation sessions. When I finally sat down at my computer, putting things together was fun.

I looked at setting up a Rust project from scratch, finding appropriate GitHub Actions workflow templates for building and testing, then built my first 0.1 version. Originally I planned to follow a Hello World tutorial precisely, but I decided learning on the fly would be more interesting and engaging than my usual setup process.

Development Journey

After finding the emoji package and Clap for argument parsing, I wanted to run this project not just locally on macOS but also in a Docker container. I remembered that at work, many of our Docker containers were already configured for GitHub Codespaces, but thinking through the setup myself was really valuable. I relearned Docker images, local installation, and how to minimize dependencies and cache them for future builds.

When I pivoted to GitHub Actions, I was pleased to discover pre-built workflows for building, formatting, linting, and testing Rust code. I also learned that unlike Go, TypeScript, and Ruby—where tests are written separately from implementation files—Rust allows writing unit tests right underneath the implementation code. This was interesting and saved me one cognitive cycle from finding where tests should go.

I eventually decided to implement releases and security checks, which I found really interesting. More on that later!

Testing and Development

Writing unit tests in Rust taught me about the different annotations available. I thought about what I wanted to test and how, and having Claude as a thinking partner to bounce ideas off was great.

One thing that impressed me was how Claude wasn’t just my thinking partner during ideation but throughout the entire project. It helped me inside issues, pull requests, and commits as I reviewed my own work. Claude wasn’t plugged into just one part of the process but throughout the whole workflow.

It’s amazing that something I’d used in the UI and as a base model for GitHub Copilot was also ubiquitous across different interfaces: my command line, Claude Code, my VSCode editor, and even GitHub Actions workflow updates via pull request comments. While I’ve used GitHub Copilot at work, it was interesting to see a different perspective in how Claude analyzed and processed my work.

Token Management and Optimization

One incredibly illuminating aspect was token usage. At work I don’t think about quotas—I’m grateful to issue commands at will—but having to manage context and be extra careful about token usage, I quickly discovered sub-agents, instructions, commands, and skills as ways to streamline my workflow and reduce typing (especially since I use Wispr Flow on my personal machine).

Codifying my work was really helpful, whether through a skill just for conventional commits or the Git workflow.

I found the skill creator that Brady provided at Anthropic’s Skills Repository particularly neat, along with the release process of pushing a tag and triggering a release build. You can check out all the skills I created here: https://github.com/francisfuzz/emoji_gen/tree/main/.claude/skills

With regard to optimizing my Claude Code usage, I found a couple of things worked best:

1. While it was neat that Claude could follow both conventional commands and my Git workflow to the letter, I noticed how many tokens it used writing text, pushing changes, checking Git diffs, and pulling pull request information.
2. I chose to use the exclamation mark (bang operator) to carefully execute the commands I wanted, especially for version control and checking pull request status. I saved the thinking-heavy steps for Claude, like debugging compilation or build errors and collaborating on test design.

Reflection

Something that struck me about this whole experience was the element of play. It’s been a while since I’ve executed an idea without a timeline or pressing need. I was more interested in ideating, trying, and seeing what Claude and I would come up with along the way.

While I don’t plan to develop the application further since I’ve already implemented what I wanted, I found the journey extremely illuminating. Whether relearning my own tools or thinking about how to interact with agents not just as tools but as partners in the process, /compact has become my new best friend. The learnings here are cross-transferable between my work at GitHub and my personal projects.

Credits

I need to credit these authors whose work helped me see things differently and try new approaches:

• https://steipete.me/posts/just-talk-to-it
• https://jonmagic.com/posts/how-i-work-2025-edition/
• https://simonwillison.net/2025/Dec/10/html-tools/

Closing thoughts

I asked Claude what it thought about my experience, specifically:

Going through this copy what’s something that you spotted but I did not mention that I think would be a good takeaway moving forward?

Here’s the compacted summary:

Managing collaboration bandwidth, not just token budgets. Through building Emojigen, I developed a practical framework for human-AI collaboration by tiering work across three levels:

• High-value tasks → Let Claude think (debugging, test design, architecture)
• Repetitive tasks → Use bang operator for direct execution (git ops, status checks)
• Reusable patterns → Codify into skills (conventional commits, workflows)

Token constraints became a forcing function to think critically about where AI adds the most value. This delegation triage—deciding what’s worth the “conversation cost”—is transferable beyond Claude Code. As AI tools proliferate across workflows, the real skill isn’t just using them, but developing intuition about which tool, at which stage, and at what level of autonomy.

Until soon, happy building! <3

What’s your weapon of choice as a developer? When GitHub’s CEO asked me that during onboarding in 2015, I said “Unix” to sound cool.

Ten years later, I wish I’d said “asking great questions”—because that single skill shaped everything that followed across four different roles at GitHub.

Here are 10 lessons from a decade of serving others at GitHub.

1. Asking great questions

During my first year as a support engineer, I’d read a customer’s question, interpret it one way, and send a reply—only to have them come back saying I’d completely misunderstood.

One of my mentors taught me a technique that changed everything. Instead of jumping to solutions, he’d ask: “If you had a magic wand, what would you expect to see? And why would that be important to your workflow?”

This question was gold. While most of our tickets were about GitHub’s API and integrations, this simple prompt revealed how people were actually using the platform and where the interface mattered most to them. That context helped me course-correct my replies and connect customers with the right resources and people.

The difference between a great question and a regular one? Context!

Great questions are specific and get to the heart of what matters to your audience.

As I moved from support to program management to partner engineering to product engineering, my questions evolved—adapting to different audiences (customers, stakeholders, partners, cross-functional teams) while becoming more refined as I gained context about what each role needed.

2. Finding a mentor early on can make or break the experience

Ivan Zuzak (@izuzak) is a staff software engineer at GitHub. When we first met, we worked in support and his deep technical chops and distinctive writing style that caught my attention. I was drawn to how he approached helping people—especially around APIs and integrations, the area I found most fascinating from my software engineering background.

I asked my manager how to approach him, and over the next 3½ years, we worked together answering every question under the sun about GitHub’s REST API, GraphQL API, OAuth apps, GitHub Apps, webhooks—anything with programmatic support.

What made Ivan exceptional wasn’t just his technical depth. He identified my superpower early: finding the right people to tackle a problem and building shared understanding across teams. He sponsored me by giving me an opportunity to present at an internal summit on the integrator experience, speaking alongside leaders from engineering, product, and design. That moment let me formalize what I did, how I did it, and why it mattered. It expanded my trajectory from support engineer to product engineer.

Later, when GitHub Actions launched, I became the internal ombudsperson for the feature, leveling up my team and empowering customers. Watching my own progression made me realize something critical: mentorship creates a debt you pay forward. I started seeking out people without mentors, trying to offer what Ivan had given me.

Years later, after several internal pivots, Ivan and I still check in every few months. We work in the same engineering organization now. I still look up to him, and I’m certain I wouldn’t be the same person without his guidance.

3. Once you’ve learned enough about something, package what you’ve learned and present it

Early on, GitHub introduced the Checks API—a richer interface for integrators to report build statuses beyond the simple pending/success/error states of the old Status API. I was intimidated. It wasn’t as intuitive as repositories or pull requests.

I spent time with the lead engineer, @keavy, asking basic questions the documentation didn’t answer. What does this feature do? Why does it exist? I extracted my notes into a Markdown document (this was before AI tools), created a slide deck, and hosted a lunch-and-learn for support engineers. Today, I’d issue multiple pull requests to the documentation or source while working on a Loom to contextualize it for humans in the future (yay distributed workforce!).

Then I invited the partner engineering team. They worked directly with integrators who deeply integrated with GitHub’s systems—high-touch, high-value relationships. Suddenly, packaging my knowledge wasn’t just helping my team on the front lines; it was helping partner engineers be more effective in enabling integrators to succeed.

The act of slowing down and explaining what I’d learned—to myself and others—crystallized my understanding. Follow-up questions filled gaps I didn’t know existed. I realized that even small contributions—a typo fix, a documented question—could improve the next support or engineering interaction.

This practice evolved across my roles. Today, in the age of AI tools, I use Copilot and Claude as thinking partners to analyze what I’ve written and help me package knowledge into reusable wisdom that applies across contexts.

4. Don’t just teach your team—find others who use the same technologies and equip them too

When I became one of the internal ombudspersons for GitHub Actions, I published our internal support documentation in a location where product engineers could see what we were working on and what questions we were getting. Other teams working with integrators and customers building on GitHub Actions could use it too.

This was a turning point. I realized I enjoyed being in the weeds—and sometimes climbing up to see the forest. That forest-level view came from pausing to reflect: What’s the core issue or lesson here? Who else could benefit from what I’ve learned?

Expanding beyond my immediate team wasn’t just about scale—it was about enriching others’ work and careers with lessons from my mistakes and discoveries.

5. Log what gives you zest and find out what other adjacent activities do that too

Early on, I found the thrill in internal research—writing up notes on how things work, why they work, and what to consider. I also loved teaching as a way to crystallize my understanding.

Combining research and teaching helped me pivot into roles like program management, giving me frameworks for understanding domains more deeply. Learning and relearning fundamentals became a pattern. Taking checkpoints—going from understanding how something works to actually practicing and using it—helped me expand into different engineering domains.

When I transitioned back to product engineering as one of the leads for optimizing GitHub Docs’ localization builds, I ramped up on modern JavaScript and build systems across vendors. I wasn’t building pipelines exclusively, but translating requirements across systems taught me how to communicate well asynchronously over text without losing signal.

The through-line? I logged what energized me and looked for adjacent activities that gave me the same feeling.

6. Grow where you’re planted

I worked as a program manager for the GitHub Community for almost a year. I missed the thrill of research, understanding how things work, and communicating directly with people—whether one-on-one or one-to-many.

When a partner engineer role opened up, I applied. It had crossover traits from my support engineering days: prototyping, communicating with integrators about how to build with our platform. But I had a few weeks before I could transition, and I needed to leave my PM work in good shape for whoever took over.

Instead of coasting, I used that time to learn something critical: how to scope work well and build partnerships. As a PM without direct reports or budget, I couldn’t influence metrics alone. I needed to find work that aligned with other teams’ goals—work that helped both of us move forward.

The PM year was hard; I wasn’t in the code. I wasn’t face-to-face with people the way I wanted to be. But that constraint forced me to think about my work more holistically, systematically, and cross-functionally.

Later, when I became a product and engineering lead, that lesson paid off. I could scope quarter-long epics into essential batches, spike out the most meaningful pieces of work, and build the partnerships needed to ship. The PM experience—despite not energizing me—taught me skills I use every day.

7. Technical spikes help you discover if you’d like to do more of the work—not just where the work is going

A technical spike is a time-boxed exercise to answer a few small questions and gain clarity about what needs to change in a system. There’s no pressure to ship something usable on the first try—what matters is understanding how the system works and what its dependencies are before making changes.

On the new user experience team, I was tasked with updating the dashboard’s Copilot interface with targeted icebreakers for users who’d joined GitHub in the last month. The component was built in Rails and Catalyst. The question: should we migrate to React to ship these new icebreakers?

I started my spike by outlining the steps for a React migration. Then I discovered the icebreaker configurations were stored in a format that made them easy to change. The spike revealed we didn’t need to migrate everything right now—and documenting the migration path would help the next person who picked it up.

With shifting planning cycles, time was tight. I found a way to update the configuration and feature-flag the changes, shipping within a week instead of a month. That moment clarified something: I care about outcomes and impact. As much as I love refactoring code, shipping faster let us learn how people were using the icebreakers and where we needed to drive higher signal for users wanting to make the most of GitHub and Copilot.

My advice: Time-box a question or set of questions and dig in to learn how things work. While AI tools are great thinking partners, working with people in the field shows you what brings them joy and what toils them. That insight is invaluable for deciding whether you want more of that work in your career.

8. AI agents need to understand system-wide context before acting—research and discovery matter more than ever

Over the last four years as a product engineer, I’ve watched AI integrate into every phase of the software development lifecycle—whether in VS Code or elsewhere. Planning, asking, editing, having agents work on our behalf—it’s just the start.

But here’s the friction I’m experiencing: agents have limited context windows. Being able to narrow in on what context is most relevant for agents to operate on is the name of the game right now.

Before planning, the research and discovery I’ve described in earlier lessons becomes critical. Understanding how things work independently, how they work with other systems, and what behaviors emerge from those interactions—that’s the foundation agents need.

I want to see agents understand how one change in one part of the system affects the entire system and specific subsystems, even before writing a line of code. Just as we can build abstract syntax trees or create deterministic views of how symbols link together in code search, I’d love to see this kind of system-wide understanding reflected in agents as I work.

Beyond having agents move on our behalf, I think observing changes and iterating based on telemetry would be invaluable. After you’ve planned, implemented, and assessed work, you can codify it—update your configuration so the linter catches it next time, or ensure tests prevent regressions.

But there’s more: agents could analyze how we do this work. If we forgot something during planning, that gap could be codified into the planning or discovery process for next time. Having a focused and accurate memory for where things were, where they are, and where they’re going is just as important as the context window itself.

9. It’s not shipped until you write about it—use story to codify why changes matter

One lesson I’ve carried throughout my time at GitHub: it’s not shipped until you write about it.

Eventually, all the features I’ve worked on that get published have a blog post about them. The narrative explains not just what changed, but why it mattered. Story is how we encode memory—where things were, where they are, where they’re going.

This blog post itself is proof: I’m using narrative to make sense of a decade.

I wonder: what would it look like for agents to capture this in their memory as they ship work? To tell a story about the work and why it was important? Like my daughter, I find stories captivating. How can we use story as a way to convey why a particular changeset matters and incorporate that into the software development lifecycle?

In some ways, the narrative arc could become our specification. Before we write code, we write the story of what we’re building and why it matters to users. That story becomes the North Star for implementation, testing, and ultimately the blog post that announces the feature.

Story isn’t just documentation—it’s how we make meaning from our work and share that meaning with others.

10. The questions you ask shape the person you become

Looking back, I wish I’d told my CEO my weapon of choice was asking great questions—but it took ten years to understand why.

Every lesson here circles back to inquiry: asking customers about their workflows, mentors for guidance, myself what energizes me, systems how they work, agents what context they need, and always asking “why does this matter?”

The through-line isn’t just technical growth. It’s curiosity as a practice. I didn’t just learn technologies—I learned to ask increasingly sophisticated questions that revealed what I cared about and where I wanted to go.

In the age of AI agents, I’m still asking questions. How do we give agents the context they need? How do we codify learning so it persists? How do we use story to capture why work matters?

Ten years in, I’m grateful for the questions I’ve asked and the people who’ve helped me ask better ones. <3

Special Thanks ✨

First, all glory to God. To my wife Angelica and daughter Ava, and my parents who’ve supported me since the beginning.

To Ivan Zuzak for being an exceptional mentor and showing me what great technical leadership looks like.

To the managers who believed in me, sponsored my transitions, and invested in my growth as a person—thank you for helping me become who I am today.

To the New User Experience team for teaching me what it means to build with empathy and impact.

And to the support, partner engineering, program management, and product engineering teams who taught me something new every day—thank you for ten incredible years of learning, building, and asking better questions together.

This post was shaped in partnership with Claude, an AI assistant that helped me articulate these lessons and organize my thoughts. The act of explaining my decade to Claude became its own form of asking questions—which feels fitting.

Code review is where software quality lives or dies. After a decade of reviewing thousands of pull requests across GitHub, startups, and consulting engagements, I’ve learned that great code review isn’t about catching bugs—it’s about building confidence in what ships to production.

Why this matters

Every line of code that reaches your customers passes through code review. The difference between shipping with confidence and shipping with crossed fingers often comes down to how systematically your team approaches this critical gate. Poor code review processes create bottlenecks, missed issues, and team friction. Effective code review accelerates delivery while maintaining quality.

I’ve refined this approach across three distinct roles: as a senior engineer on GitHub’s New User Experience team, as a consultant for early-stage startups, and as a senior support engineer helping teams optimize their pull request workflows. This perspective spans customer-facing features, internal tooling, and developer experience improvements.

The three-phase framework

Effective code review follows a deliberate sequence: gather context, analyze changes, validate impact. Most reviewers jump straight to the code diff, missing critical context that determines whether changes align with business objectives and technical strategy.

Phase 1: Context before code

Before examining a single line of code, I establish the strategic foundation. This prevents costly misalignment and ensures changes serve their intended purpose.

Business context questions:

• Who initiated this work and why now?
• Which users or systems will this impact?
• What problem does this solve or opportunity does it capture?
• How does this align with current technical and product priorities?

Technical context questions:

• What’s the blast radius if this goes wrong?
• Are there dependencies or sequencing requirements?
• Does this require coordination with other teams?
• What validation environments are available?

This context-first approach has prevented numerous issues that would have been expensive to catch in production. When I understand the “why” behind changes, I can evaluate whether the “how” achieves the intended outcome.

Phase 2: Systematic code analysis

With context established, I examine the technical implementation through multiple lenses:

Scope and structure:

• Do all changes belong in this pull request?
• Is the change size appropriate for safe deployment?
• How do the modified files relate to each other?
• Are there unrelated improvements that should be separated?

Quality and maintainability:

• Does the code follow established patterns and conventions?
• Are there performance, security, or accessibility implications?
• Is the implementation clear enough for future maintainers?
• Are appropriate tests included?

I use a consistent commenting system to set clear expectations:

• 💅 Non-blocking suggestion: Style improvements that don’t block approval
• 🙋 Question: Clarifications needed to understand intent or approach
• 🟡 Requested change: Issues that must be addressed before shipping
• ✨ Affirmation: Recognition of particularly well-executed solutions

This taxonomy helps authors prioritize their response and understand what blocks progress versus what offers optional improvement.

Phase 3: Validation and verification

The final phase ensures changes work as intended across relevant environments and edge cases.

Validation checklist:

• Can I reproduce the original issue and verify the fix?
• Do staging or review environments demonstrate the changes correctly?
• Are there clear instructions for testing the changes?
• Have automated tests validated the expected behavior?

This systematic validation has caught numerous issues that passed automated testing but failed in realistic usage scenarios.

Implementation guidelines for teams

For engineering managers:

• Establish clear expectations around review turnaround times
• Ensure your team has adequate staging environments for validation
• Track review quality metrics alongside velocity metrics
• Invest in tooling that surfaces context automatically (linking to issues, ADRs, deployment history)

For individual contributors:

• Structure pull requests to tell a clear story from business need to technical solution
• Include comprehensive testing instructions in your descriptions
• Respond to review feedback systematically, addressing each comment explicitly
• Use review as a teaching opportunity, explaining your technical decisions

For senior engineers:

• Model thorough review practices, especially for junior team members
• Balance perfectionism with shipping velocity—not every suggestion needs to block progress
• Use review as mentorship opportunities to elevate team capabilities
• Document patterns and anti-patterns you see repeatedly

Measuring success

Effective code review creates measurable improvements:

• Reduced production incidents from preventable issues
• Faster onboarding for new team members through consistent code patterns
• Increased deployment confidence leading to more frequent releases
• Better knowledge sharing across the team

Teams that invest in systematic code review processes ship faster and more reliably. The upfront time investment in thorough review pays dividends in reduced debugging, support burden, and technical debt.

Looking ahead

Code review continues evolving with AI assistance, but the fundamental principles remain: understand context, analyze systematically, validate thoroughly. Tools can surface issues and suggest improvements, but human judgment about business alignment, user impact, and system architecture remains irreplaceable.

The best code review isn’t about perfection—it’s about confidence. When your team consistently applies these practices, you ship knowing your changes will work as intended, scale appropriately, and maintain the codebase quality that enables sustainable growth.

Special thanks

• Andrea Takamiya
• Ash Wilson
• Hannah Yiu
• Julie Kang
• Sarah Vessels
• Selene B. Pastelski

I’d like to send a heartfelt thanks to the Web Summit team for extending the ticket. It’s been over three years since I attended a conference, and I am grateful to make my debut back with Web Summit Lisbon.

Pro tips for pitching

This session was hosted by Cristina Fonseca of Indico Capital. Each startup that presented gave me insight into how people are using AI in their capabilities, whether for developer tools, event planning, or even legal documentation.

What I found most interesting was the themes of questions that emerged when Cristina evaluated each of the pitches. Here’s my AI-assisted summary of themes and great questions to ask startups, depending on the context of their pitch:

Product and Competitive Edge:

• Is the (digital) product a separate visual editor or an embedded widget?
• How do you maintain a competitive edge when these open-source models are accessible to everyone?
• What is your dependence on a third-party API to generate data or answers versus using your own proprietary technology?

Geographical Focus and Privacy:

• What is the current and future geographical focus for the short-term? How about the long-term?
• How do you ensure the privacy of students, especially minors, using the app?
• When the data is submitted, how is it stored and secured? What is your current compliance and security posture, and where can it be improved?

Business Model and Competition:

• Explain the business model: how do you make money?
• Share insights on competition in your market. If you think you don’t have any competitors, who or what do you anticipate being a risk to your business in the next year?
• Based on your slides, what is the base currency of your earnings?
• Is this a subscription-based model or something else?

Sales and Go-to-Market Strategy:

• How does selling differ between public and private schools?
• Detail your go-to-market strategy and target audience.
• Is this a business-to-business company? Or a business-to-consumer? Or a mix of something else?

Who are you? How the convergence of microbes, human DNA, and AI can alter our evolution

This session was hosted by Lauren Wright, CEO of The Natural Nipple.

I initially discovered her work when she delivered her company’s Web Summit 2023 Pitch.

The conversation was rich, and while I couldn’t capture every point, I found Lauren’s discussion on the significance of prebiotic foods, the research behind the potency of breastmilk, and details in between fascinating.

One of the notable papers Lauren mentioned was Equally Good Neurological, Growth, and Health Outcomes up to 6 Years of Age in Moderately Preterm Infants Who Received Exclusive vs. Fortified Breast Milk—A Longitudinal Cohort Study. One of the key findings that I garnered was the importance of the microbiome in early life, suggesting that shaping microbial DNA in the first two years is crucial for long-term health. The wonder of the nutrients that come from this form is that it is tailor-made for the child that no other substance or food product can offer. However, where breastfeeding just isn’t possible, she promotes donor milk as the next best option for infants and toddlers.

As far as AI went, Lauren described the power of using machine learning and existing tooling to comprehensively process and combine the collective research on the microbiome for short-term research and related product development. Having AI along with a development team and a group of medical professionals can be a powerhouse in interpreting microbiome data, in addition to improving our collective understanding on the topic. One of the final points Lauren made was addressing historical shifts in formula marketing and its potential correlation with increased inflammation.

What it takes to be a technical leader

This session was moderated by Bobby Allyn of NPR hosting the following panelists: Christine Spang of Nylas, Simon Wistow of Fastly, and Emil Eifrem of Neo4j.

I appreciated that each of the panelists represented their companies’ respective “stage” of a startup and shared their perspectives from that angle: from seed and early round to a slightly larger company nearing one thousand employees, to a company that’s publicly traded.

Below is my paraphrased version of the questions Bobby asked along with the responses from each of the panelists.

How do you attract engineers from a bigger company like Facebook, Apple, Amazon, Netflix, or Google?

• From Simon: Pitching to a FAANG senior engineer — Professional: bigger fish in a smaller pond, outsized impact; direct effects on org // be a company that people are proud to be a part of. Think broader than the technology.
• From Emil: Impact and Culture. Relationship-centric culture and combining empathy with accountability.
• From Christine: Autonomy, 130 people — the amount of control over your working day and who you’re working with is there. Make sure upfront people are aware but a unique opportunity that they can work on internet-plumbing projects. Deep distributed system problems and building the foundation for the future.

Based on your company’s current stage, what is the most important thing you all are focused on achieving?

• For a growth startup, a software engineer’s job transitions from solely writing code. There’s a breadth and depth of competencies spanning from communicating to translating. The keys to success remain the same no matter the activity: being detail-oriented and following through on those commitments. However, there may come a point where you transition from being an individual contributor, and you’re in a position where it’s more impactful to grow your team and having the team aligned on building up the business. In addition, you become an interface to work with other parties in the company and get things done together, which is one of the most difficult things to do, in contrast with the “coding” that you were originally hired to do.
• For a larger organization (many hundred of employees, let’s say), it comes down to the level of scope and abstraction based on the role. For example, as a technical leader, your original task was to build the product. As the product and its user base grow in size, there is a responsibility for the team to work together and for you to coordinate (or perhaps even better, orchestrate) their operation. You grow into the role of being an organizational architect to arrange and generate the most output from each unit. Your days will then be figuring out how to get your product managers working in tandem with Developer Relations, along with the Sales and Marketing teams.

On AI: to what degree should this be core or complementary to your business?

There’s a belief that in this environment, you have to start with AI being the core (and perhaps the only thing) driving your business. Taking a step back, what’s more critical is how it’s used, why, and for whom. Think about how your current offering can be enhanced or complemented with AI is better than just having everything be AI only.

What’s your advice for junior developers wanting to work at your startup?

• Open source experience is valuable
• “Eye of the tiger”: does this person have a sense of enthusiasm and a drive to push themselves? Do they care about the business and are they tuned in on the downstream impacts? Do they ask interesting questions tied to customers? Do they express curiosity that shows they know will be on the high slope of learning?
• Showcase the ability to think structurally, along with the ability to have a longer-term and broader perspective of the impact of what you’re building

Closing thoughts

Attending Web Summit 2023 gave me new insights that I wouldn’t have otherwise watching a stream or a recording. Meeting people in-between sessions over coffee, along with letting the ideas from session to session connect in an organic way gave me a newfound perspective on how what I work on day-to-day affects those who are advancing their fields and serving their customers that wouldn’t have otherwise been touched.

I look forward to returning next year and I will be applying as a speaker. Stay tuned! 😉

There is a dedicated learning and development team that sources speakers and this month, I presented a talk about building psychological safety in the context of code reviews.

I first came across psychological safety while considering the path of becoming a manager years ago. Specifically, OfficeVibe’s Psychological Safety: the key to high-performing teams article gave me a high-level primer and it has become one of my core working practices as a technology professional.

The following post is an abbreviated version of that presentation. Before sharing the content, I’d like to share some healthy “disclosures”, if you will, so we’re all on the same page.

First, I am a software engineer by profession. I’m neither an anthropologist, psychologist, nor a psychiatrist; forgive me if I haven’t taken into account specific cultural or psychological contexts in this article. What’s shared here is my primitive understanding of how psychological safety could work in the context of code reviews based on my observations, experiences, and combined understanding of existing resources. It is by no means the definitive guide on how every software engineering team in the world should carry out this work.

Next, this content is for any professional that requires writing and reviewing code as a part of their day-to-day responsibilities, along with those who manage professionals who do those things. I understand that along with software engineers, technical program managers, data scientists, analysts, and even product managers within GitHub write code as a part of their work. This is my best attempt at being inclusive and to say that, if you code within a team setting, this is for you!

Last, I’m giving this my best and I know that I’m fallible. You’re welcome to open a pull request for any suggested changes.

What is psychological safety?

Let’s start with definitions. Amy Edmondson is the Novartist Professor of Leadership and Management at Harvard Business School and is known for her work with teams. In her TedX HGSE talk Building a psychologically safe workplace she defines psychological safety as:

a belief that one will not be punished or humiliated for speaking up with ideas, questions, concerns, or mistakes.

I recognize that the words punished and humiliated may convey a negative sensitivity for some readers. As I engaged with this definition, one of my mentors shared that psychological safety can be impacted by actions and sentiments less severe. By acknowledging that there’s really a spectrum, one way we can widen the scope of this definition is to offer an alternative, definition:

a belief that one will not be excluded or made inferior for speaking up with ideas, questions, concerns, or mistakes.

Whenever I see terms defined in the negative, I challenge myself by taking a stab at defining it in the affirmative. Here’s the best I could come up with:

a belief that one will be recognized and affirmed for speaking up with ideas, questions, concerns, or mistakes.

Depending on the context and cases I walk through, I’ve fluidly shifted between these three definitions in my day-to-day work life.

Moving from this common understanding, let’s talk about why it matters.

Why does it matter?

Amy Edmondson shares this reason in the aforementioned presentation:

Every time we withhold, we rob ourselves and our colleagues of small moments of learning, and we don’t innovate.

At GitHub, one of our leadership principles is “trust by default.” In my view, psychological safety is foundational to building trust in any of our working relationships. Without trust, it’s pretty tough to do anything else, whether we’re communicating with each other amidst conflict, building a new feature, debugging a tricky bug, or exercising the courage to challenge a controversial decision. Every meaningful piece of work comes from the bedrock of operating under high trust.

Google published their study on the five keys to a successful Google team, specifically what makes a Google team effective. Their research found that “Who is on a team matters less than how the team members interact, structure their work, and view their contributions.” Of the five key dynamics that set successful teams apart from other teams at Google, psychological safety was the most important. Here are those dynamics and a question to frame them in the intended context:

1. Psychological safety: Can we take risks on this team without feeling insecure or embarrassed?
2. Dependability: Can we count on each other to do high quality work on time?
3. Structure & clarity: Are goals, roles, and execution plans on our team clear?
4. Meaning of work: Are we working on something that is personally important for each of us?
5. Impact of work: Do we fundamentally believe that the work we’re doing matters?

McKinsey and Company studied psychological safety in the context of leadership development, describing it as a critical role. What they shared is that the most important driver of a team’s psychological safety is cultivating a positive team climate. The entire article is worth a read, but I found this particular finding illuminating:

By setting the tone for the team climate through their own actions, team leaders have the strongest influence on a team’s psychological safety. Moreover, creating a positive team climate can pay additional dividends during a time of disruption.

Our research finds that a positive team climate has a stronger effect on psychological safety in teams that experienced a greater degree of change in working remotely than in those that experienced less change during the COVID-19 pandemic.

Yet just 43 percent of all respondents report a positive climate within their team.

(The emphasis on that particular statistic is my own. 😉)

Building psychological safety is for teams, where each member believes that they won’t be punished, humiliated, excluded, or made inferior in the face of raising a question, concern, mistake, or new idea. It’s important because it’s one of the ways to build trust, which is the foundation of highly effective teams.

As professionals that write code day-to-day, what are some ways of bringing this into our code review practice?

How do we build psychological safety?

Professor Edmondson offers SAFE as an acronym, where SAFE stands for:

• Setting Limits
• Approachability
• Fallibility
• Engagement

Setting Limits

Limits (read: expectations) give team members confidence to know what the boundaries are: anything that is off-limits or out-of-bounds. When these are known, they can take the time to experiment and try new things within those boundaries.

At GitHub, we have company-wide policies on opening and reviewing pull requests. Teams that manage one or more services use pull request templates for setting guidelines for pull request authors to fill out ahead of opening the pull request. Once these limits are set, each member is responsible for practicing them and they hold each other accountable to follow through with what’s agreed upon.

Case Study: GitHub Sponsors’ PR Review Emoji Schema

One of the problems the GitHub Sponsors team faced in their code reviews is not having a clear understanding of whether comments on their pull request are blocking or not.

After investigation and research, they decided on a new process for using use emojis to indicate the type of review comment that’s being left on a pull request.

Here’s their system:

• 💅🏽	non-blocking changes

• 🛑	blocking changes

• 🔜	fast-follows (address non-blocking changes in a separate PR to come after the one being reviewed)

• ❓

  questions

Credits go to @knittingarch and @cheshire137 for doing the work in making this happen, along with the GitHub Sponsors team for their permission to share this case study publicly!

Approachability

Approachable literally comes from the word “accessible”; in the figurative sense, “affable”, which in context is one that’s “open to conversation or approach.”

In Derek Prior’s RailsConf 2015 - Implementing a Strong Code-Review Culture, he shares a tip for using pull requests and asking questions as a way of driving technical discussion. He mentioned being aware of the negativity bias that comes from reading words in plain text can help drive our approachability: being intentionally and mindfully positive in the code review comments can let the discussion flow in a way that gives everyone a chance to learn more about the code.

As the author of a pull request, being approachable could look like writing up specific questions for reviewers to comment back on, being clear in what kind of feedback you’re looking for.

As the reviewer of a pull request, being approach could look like asking questions that seek to understand the author’s perspective, rather than prioritizing seeking to be understood. For example:

• “What do you think about…?”
• “With Y in place, what’s your take on considering X as well?”
• “Could you tell me more about your process in…?”

Tying back to the McKinsey and Co., team leaders have strongest influence on a team’s psychological safety. Expanding from team leaders, leaders in individual contributor positions ranging in tenure, experience, or level, have an opportunity to set the tone for teammates by how they communicate within code reviews, which in turn, lets their peers match the tone that’s set.

Imagine the ripple effect of folks being approachable with one another and how that could impact code reviews moving forward!

Fallibility

One of the definitions of being fallible means being liable to err. In practice, it’s about taking the time to let others know that you can make mistakes, and admit to them when they happen. In turn, this lets others know that you’re open!

Examples:

• Visibly thank people for catching your mistakes.
• Show your work process, not only the result or where you’ve arrived – tying this to highlighting where you’re unfamiliar with certain areas brings teammates up to speed with where they could provide more precise input. You could even lead with an ask; here are some examples shared by my colleague @UnicodeRogue:
  • “From my perspective, …”
  • “My understanding is …”
  • “Considering A, I did B because…, but could use some pointers about P and Q, namely…”

Engagement

Engaging people means coming in with the understanding that, when operating with a team, Amy Edmondson describes it like this:

Make explicit that there’s enormous uncertainty ahead and enormous interdependence.

Given those two things, we’ve never been here before. We can’t know what will happen.

We’ve got to have everybody’s brains and voices in the game.

That creates the rationale for speaking up.

Put in my own words:

I don’t know what’s ahead, and I need your perspective for all of us to move ahead.

We’re better together.

This is a mindset. No no, the mindset, in my humble opinion.

How does this look like in practice? While keeping this mindset, I’ve found that using people’s names or online handles while addressing them is a good place to start (please don’t give them a nickname they did not ask for). Echoing back from the points of approachability and fallibility, using curiosity as a way to lead and open technical discussion helps, too. Last, in my own experience, I’ve found that taking the time to reach out to your team member(s) and getting to know them outside of the code review can help with building psychological safety. By knowing how they speak and their approach outside of a review, that’s helped my brain contextualize the plain text in their actual voice, which has helped me better assess what they’re saying versus making an assumption of what I think they’re saying.

What’s next? Where do I go now?

The examples in SAFE can be things that you could try with your team today. However, building psychological safety within a team is not going to happen over night. Code reviews are but one medium where we can do that. It’s going to take time and every member’s actions to make it happen, so that a resounding “Yes” can be the answer to this question:

How confident are you that you won’t receive reatliation or criticism if you admit an error or make a mistake?

(Source: Google’s Guide to understanding team effectiveness).

Here are some additional resources that have influenced me that might be worth checking out too:

• DORA: Generative Organizational Culture
• Harvard Business Review: High-Performing Teams Need Psychological Safety: Here’s How to Create It by Laura Delizonna

Special Thanks

There were several individuals and teams that made my presentation possible. Here’s a special thanks to you all, <3:

• Day of Learning Organizers
• GitHub Education Team
• Reviewers: Ernest, Ivan, DeeDee, Roniece, Sarah, Daniel, Laura
• Hubber Alumni: keavy, kytrinyx, gjtorikian, jasonrudolph, jnraine

Here’s the tl;dr version of this post in relation to the above principle:

1. Before working on a new feature, I should ask myself what the smallest, most potent changes I can make are and write that down in an issue where it’s visible to the team.
2. When I start working on a feature, I should open a draft pull request as soon as I have something to show.
3. After two working days, if I haven’t marked my pull request as ready for review, I’m probably working on too much and should ask for my team’s input in narrowing the scope of my pull request into smaller, more potent pull requests.

The story

A few weeks ago, I joined a new track at work focused on shipping a new feature. My track lead gave me the creative autonomy to scope my assigned portion: building a system for managing user permissions.

Our track’s designer shared their designs with me and I used that as a start for my first pull request. I introduced a static version of this system using only Primer View Components and a few of the Rails primitives (routes, controllers, and views). By only focusing on the UI, I was able to ship a small, potent pull request.

Feeling confident, I charged in to work on my next pull request!

Specifically, I started working on a part of the backend that exposed a new method for returning meaningful data in the UI. On Monday, I had a handful of files that were not polished but at the 30% mark of what I felt was ready. On Tuesday and Wednesday, the scope of my pull request grew as I went deeper into development. By Thursday morning, over 20 files had been changed, spanning from updating the views I originally worked on to adding new models and controllers. 😬

When I finally marked my draft pull request ready for review, one of the staff engineers on my team reviewed my work as it was. One of the most valuable questions she asked was if I’d be open to shipping the model-specific changes in separate and earlier pull requests.

I immediately agreed. Writing this out, I’ll go on the record and say that I’m glad I did.

On that Thursday afternoon, I moved the model-specific changes to separate pull requests. This gave me a chance to refactor the new module I introduced and to double-check my tests.

As a part of that work, I found some mistakes in the internal documentation I wrote for that module. For context, the module is written to be mixed into other models. I noticed, however, that I had written the documentation as if it were intended to only be mixed into one kind of model.

I updated it by making the documentation more generic:

-    # Public: Returns the authors of a {MODEL_NAME} in a given resource.
+    # Public: Returns the authors in a given resource, depending on the model it's
+    # called on.

Another mistake I found was in the return value of the method. When I update the method’s API, I forgot to double-check these annotations and took the liberty of updating them:

-    # Returns an ordered Array of authors.
+    # Returns an Array of Arrays, where each element contains the author's username and ID.

By having only four files to focus on rather than twenty, I felt that my self-review was much more focused and something I could confidently share with my reviewers to help them understand the changes I made.

When I re-requested her review near my end-of-day, she gave me very focused feedback on the tests that implicitly taught me of another way of writing the same test fixtures in a more concise way using FactoryBot’s create_list method:

-      # Before: use Ruby's `times` method to create two instances of a model
-
-      2.times do
-        create(:some_resource, post: @unanswered_post, user: author_one)
-      end

+      # After: use FactoryBot's `create_list` method to create two instances of a model
+
+      create_list(:some_resource, 2, post: @unanswered_post, user: author_one)

I came back to work on Friday morning. My goal was to address her feedback by making those requested changes and ship that pull request. After requesting another review, she approved the changes and I spent the rest of the day shepherding it through our deployment queue to get it into production! 🚀

For the future

My tl;dr captures the essence of what I’d like to try. However, something that I recently came across months ago is this practice of Daisy-chaining pull requests. @cheshire137 wrote about this at length in GitHub Protips: Tips, tricks, hacks, and secrets from Sarah Vessels and I’ll write about it in a future post!

Let’s talk about ambiguity 💁‍♀️

One of the key skills I’m learning to develop is identifying assumptions and asking questions, especially when new projects come. Some projects already have a clear goal in mind, while others don’t.

For the latter, there are times when I feel like this:

There are times when I go through “paralysis analysis” where I think more about what to do than actually doing it. Something that’s helped me move forward is asking for help.

Recently, one of the ways that I asked for help with understanding this problem space better is by joining our company’s #how-do-i channel. The channel describes itself as a “safe place to start if you have questions about how to do or find something at GitHub.”

The channel lives up to its name because of the many Hubbers who generously share their time and expertise. For this key skill, I asked them:

How do I learn more about asking the right questions to clarify ambiguous work requirements?

Shortly after posting the questions, I received a stream of responses, resources, and ridiculously good advice. I’ve done the work of summarizing it so you can read and apply it when the situation arises. 😉

The tricky thing about just asking… “why?” 😬

When faced with ambiguity, it’s natural for us to just ask “why?”

Knowing the motivation behind a project is a key factor before choosing to invest more time and resources.

The way we find out about the motivation is also important depending on the outcome we want to drive.

Cindy, one of my colleagues, helped me understand that anytime we ask a plain “why?”, it can sound like we’re being defensive or reluctant to help. 😬

Repositioning “why” with curiosity 👩‍🔬

We can reposition this single-word question to exercise curiosity starting with these expressions:

• “Just to be sure I’m clear…”
• “I want to make sure I know the best way to help…”
• “Tell me more …”

And then leading into the question:

• “What’s the underlying problem you’re trying to solve?”
• “If we had that completed already, what’s the benefit you’d expect to get?”
• “What does your ideal outcome or end goal look like?”

It can also help to include add a reason after asking the question:

• “That way, we can figure out the best options together.”
• “I want to make sure I’m answering the most relevant questions for you.”

Take the time to listen to these responses. Write them down and consider the other person. If this doesn’t “work” for any reason, you can pivot the approach by stating your assumptions up front instead:

• “I’ve read your [doc/specification/ticket] and here are my assumptions. There’s almost certainly something that is missing or needs correcting, so please do so!
  • Assumption: X is higher priority than Y
  • Assumption: X only happens in Y situation
  • Assumption: The reason X is a problem is Y.

It’s much easier for people to react to assumptions than open-ended questions so you tend to get quick responses.

This approach can feel abrupt or offhand the first time you do it. It may also help to add a disclaimer that states the assumptions first and offer to meet with them over a call to clarify things further:

Hey, I’m going to state some assumptions in the hopes that can shorten our meetings. If these are completely off-base, let’s jump on zoom to discuss in real-time.

Going deeper, my awesome colleague Lizzy shared an experience around the difficulties of discussing work requirements if there’s a technical knowledge difference between two parties:

I’ve found work requirements are harder to discuss if there is a technical knowledge difference between the two parties and one of my roles is to remind my teammates that they need to break down the technical components for me (and realistically for others reading who are not security SMEs). I’m not really afraid of looking like I know nothing anymore, but it can be hard to constantly out yourself as not very technical. It can feel like the answers to some of Cindy’s questions are obvious to everyone else, but it’s surprising how often that is not the case.

Cindy re-assured that it’s okay to acknowledge those feelings and confronting the sentiments of the questions head-on:

I often tell people “it will feel awkward and embarrassing to ask these questions!” And unfortunately it doesn’t really go away - I still feel a little anxious when asking people to clarify something or step back and re-state the problem. What helps is that I’ve seen it work every time: unless people are really resisting out of bad faith, they will answer and someone else in the room besides me will say “oh! I didn’t realize that”.

Lizzy also highlighted identifying assumptions as one of the primary technical skills as a Program Manager and the power of mindfulness:

I try to keep in mind as well that people don’t want to assume I know nothing, because that’s also a bad look. I remind myself that identifying assumptions is part of my technical skill as a PM.

I’m also big on self-deprecating humor because not all assumptions are done with poor intent and it helps set the mood as “I need to know this thing, but I don’t need to focus on who’s fault it is that you didn’t already tell me this thing.” Obviously, there are also times where you need to focus on how the assumption has affected progress or is belittling, but especially here, I have had wayyy more instances of the former.

Going deeper 🐇

A number of my colleagues suggested these books to learn more about the topic:

• StackExchange: “What is the XY problem?”
• Domain-driven Design: Tackling Complexity in the Heart of Software
• Agile Retrospectives: Making Good Teams Great
• Project Retrospectives: A Handbook for Team Reviews
• The Power of a Positive No: Save The Deal Save The Relationship and Still Say No