<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>GitHub · Jared Lynskey</title>
    <link>https://jared.lynskey.co.nz/en/tags/github/</link>
    <description>Short stories of value on software engineering and engineering leadership — performance reviews, hiring and scaling teams, CI/CD, DevOps monitoring and agentic AI. Written from Seoul.</description>
    <generator>Hugo</generator>
    <language>en</language>
    <copyright>© 2026 Jared Lynskey</copyright>
    <lastBuildDate>Mon, 26 Oct 2026 00:00:00 +1200</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/en/tags/github/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>Using GitHub Issues for Decisions and Project Management: Alan&#39;s Method, With a Template</title>
      <link>https://jared.lynskey.co.nz/en/posts/2024/2024-01-04-githubforprojectmanagement/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/en/posts/2024/2024-01-04-githubforprojectmanagement/</guid>
      <pubDate>Tue, 09 Apr 2024 00:30:03 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>GitHub</category>
      <category>GitHub Issues</category>
      <category>Project Management</category>
      <category>Decision Making</category>
      <category>Async Communication</category>
      <category>Remote Work</category>
      <category>Team</category>
      <description>How Alan replaces most meetings with written GitHub issues: when a decision earns an issue, the LOCI roles, the writing rules, an issue template you can drop into .github/ISSUE_TEMPLATE, and when to add a GitHub Project on top.</description>
      <content:encoded><![CDATA[<p>I keep coming back to <a href="https://alan.com/en/healthybusiness/media/a/asynchronous-decisions"  target="_blank" rel="noreferrer">this article</a> from Alan, the French health insurance company, about how they make decisions. The short version: instead of booking a meeting, they open a GitHub issue and argue it out in writing. Now that I&rsquo;m managing a team myself, I&rsquo;ve been taking proper notes. What follows is my digest of their system, with my own comments mixed in.</p>

<h2 class="relative group">Why they gave up on meetings
    <div id="why-they-gave-up-on-meetings" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#why-they-gave-up-on-meetings" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Their starting point will sound familiar. Nobody comes prepared, the meeting starts late, and the loudest voice wins whether it&rsquo;s right or not. An hour later you&rsquo;re more confused than when you walked in and wondering if there&rsquo;s any paracetamol left in the drawer.</p>
<p>Alan tried fixing meetings first — 15 minutes max, clear agenda, decision required. It didn&rsquo;t hold. Discussions drifted, nobody could remember what was said, and absent or remote people were simply out of luck. So they moved the whole thing into writing.</p>
<p>The claims they make for it ring true to me. Writing forces you to slow down and actually think, so the discussion gets more nuanced and better argued. Everything is documented instead of half-remembered. It stops being an eloquence contest. And because the forum is open to the whole company, anyone can contribute — not just whoever happened to be in the room.</p>

<h2 class="relative group">GitHub as the company forum
    <div id="github-as-the-company-forum" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#github-as-the-company-forum" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>The forum itself is GitHub, a platform built for code review that Alan cheerfully hijacked. The setup is almost embarrassingly simple:</p>
<ol>
<li>Create a GitHub account.</li>
<li>Create a private repo with no code in it (theirs is called &ldquo;Topics&rdquo;).</li>
<li>Add a labelling system to categorise conversations.</li>
<li>Use the Issues tab: open issues are live discussions, closed ones are decisions made.</li>
</ol>
<p>They&rsquo;ve passed 17,000 issues. That&rsquo;s a lot of meetings that never had to happen, and — the part I find most appealing — a searchable history of why every decision went the way it did. If you want to challenge an old decision, you can first read which arguments won last time.</p>

<h2 class="relative group">When to open an issue
    <div id="when-to-open-an-issue" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#when-to-open-an-issue" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Not every decision earns an issue. Their filter is four questions: who will be affected? how reversible is it? how urgent is it? do I need more context before deciding?</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="image"
    width="1390"
    height="1213"
    src="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/decisionchart_hu_9ca1837f8ecdf619.webp"
    srcset="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/decisionchart_hu_9ca1837f8ecdf619.webp 800w, https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/decisionchart_hu_8ecbad24825e93ec.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/decisionchart_hu_c84e7ceb7d35c8e2.webp"></span></figure>
</p>
<p>Broadly, high-impact and hard-to-reverse decisions go to the forum; the rest can stay in Slack. They lean on the one-way vs two-way door distinction: a one-way decision (too expensive or painful to reverse — their example is a price increase) gets the full written treatment, while a two-way decision (cheap to undo, worst case you lose some energy) doesn&rsquo;t need the ceremony.</p>

<h2 class="relative group">LOCI: who does what
    <div id="loci-who-does-what" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#loci-who-does-what" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Every discussion assigns roles using the LOCI model — Lead, Owner, Consulted, Informed.</p>
<p>The Lead is accountable for the decision&rsquo;s success and makes sure the context is understood across the team. They say upfront how involved they want to be, then trust the Owner and take responsibility for what the team produces, speaking up only when they strongly disagree. One Lead per discussion.</p>
<p>The Owner makes the final call and drives the project. They keep contributors informed and contributing on time, investigate the problem, open and close the issue, and share the decision. If they hit a wall they can&rsquo;t get past, they go to the Lead. One Owner per decision.</p>
<p>Consulted people are the ones whose input genuinely matters to the trade-off. They&rsquo;re expected to contribute promptly — even if only to say &ldquo;nothing to add&rdquo; — and to raise the alarm (escalating to the Lead if needed) when they think the decision is badly wrong. Alan caps this group at about six, because more input starts costing schedule.</p>
<p>Informed people simply get told, usually once the decision is made. One-way communication, nothing expected back. The Owner decides who&rsquo;s affected enough to be notified.</p>

<h2 class="relative group">The anatomy of an issue
    <div id="the-anatomy-of-an-issue" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#the-anatomy-of-an-issue" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Every issue uses the same template, which both sharpens the thinking and quietly teaches junior people how to break a problem down:</p>
<ul>
<li>Scope — the &ldquo;why&rdquo; of the discussion, including the underrated line &ldquo;this issue is NOT about…&rdquo;</li>
<li>Context &amp; materials — links to prior discussions and documents</li>
<li>LOCI — who&rsquo;s Lead, Owner, Consulted, Informed</li>
<li>A deadline — when to contribute by, when the issue closes, when a solution is needed</li>
<li>A solution proposal — one suggested answer, or options to choose between</li>
<li>Questions — aimed at specific people to confirm or refute specific assumptions, so the issue isn&rsquo;t a message in a bottle</li>
</ul>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="image"
    width="1390"
    height="715"
    src="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/gitpreview_hu_154de40eb6124f02.webp"
    srcset="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/gitpreview_hu_154de40eb6124f02.webp 800w, https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/gitpreview_hu_ab103b11817c0ef0.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/gitpreview_hu_aada79d3a582942a.webp"></span></figure>
</p>

<h2 class="relative group">Writing rules that keep things moving
    <div id="writing-rules-that-keep-things-moving" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#writing-rules-that-keep-things-moving" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>A written debate can drag just as badly as a spoken one, so they have rules. Be concise — they quote Boileau: &ldquo;What is well conceived is clearly stated.&rdquo; If you can&rsquo;t write it simply, you&rsquo;re not actually sure of it yet. Apply the &ldquo;So what?&rdquo; test to everything you write; if the implication of your comment isn&rsquo;t obvious, spell it out.</p>
<p>For the Owner, the follow-up matters as much as the opening. Keep the discussion pointed at the million-dollar question — the one sticking point that actually matters — rather than letting it dissolve into details. Recap regularly what&rsquo;s been agreed and what&rsquo;s still open. And treat Slack reminders as a last resort, reserved for overdue contributions or genuine urgency.</p>
<p><figure><span class="mc-img"><img
    class="my-0 rounded-md"
    loading="lazy"
    decoding="async"
    fetchpriority="auto"
    alt="image"
    width="1390"
    height="910"
    src="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/slackmessage_hu_b208cd2844b5ba3a.webp"
    srcset="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/slackmessage_hu_b208cd2844b5ba3a.webp 800w, https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/slackmessage_hu_f44bfed068b95993.webp 1280w"
    sizes="(min-width: 768px) 50vw, 65vw"
    data-zoom-src="https://jared.lynskey.co.nz/img/posts/2024/2024-01-04-githubforprojectmanagement/slackmessage_hu_3f37871d11c679c.webp"></span></figure>
</p>
<p>Owners also hide comments that don&rsquo;t move the conversation forward, and everyone is expected to know their way around GitHub&rsquo;s formatting — headings, footnotes, tables, keyboard shortcuts — because in writing, form carries almost as much as substance.</p>

<h2 class="relative group">No consensus, no spectators
    <div id="no-consensus-no-spectators" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#no-consensus-no-spectators" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>Two rules stop this from turning into decision-by-committee.</p>
<p>First, the Owner decides as what Alan calls an &ldquo;enlightened despot&rdquo;. They investigate ideas, measure risks, question peers — but they don&rsquo;t seek consensus and they don&rsquo;t have to implement everything they&rsquo;re told. Alan is blunt about not being a democracy: every employee is a shareholder, and the company&rsquo;s interest comes before the team&rsquo;s or the individual&rsquo;s. When the Owner is reasonably sure of the right bet, they decide, everyone tries it, and once the impact is visible they review whether it was the right call.</p>
<p>Second, contributor numbers are controlled. Jeff Bezos&rsquo; two-pizza rule applies to async work too: the more people on an issue, the less each one contributes. Past about six contributors, the spectator effect kicks in and participation quality drops. Notifications follow the same philosophy — Alan trusts everyone to have configured their own GitHub notifications (Settings, then tick &ldquo;Web and Mobile&rdquo; under both &ldquo;Participating&rdquo; and &ldquo;Watching&rdquo;), so direct tags in the Questions section are kept to a minimum.</p>

<h2 class="relative group">What I&rsquo;m taking from it
    <div id="what-im-taking-from-it" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#what-im-taking-from-it" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>You can never fully explain a meeting to someone who wasn&rsquo;t there, but anyone can read a decision. Alan doesn&rsquo;t claim this is the best or only system — just the one that fits them: fewer interruptions, less spectator effect, and decisions made with a step back and the facts written down. I&rsquo;m not about to move every decision my team makes into GitHub issues, but the template below is going straight into our repo.</p>

<h3 class="relative group">The template, as a GitHub issue template
    <div id="the-template-as-a-github-issue-template" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#the-template-as-a-github-issue-template" aria-label="Anchor">#</a>
    </span>
    
</h3>
<p>Save this as <code>.github/ISSUE_TEMPLATE/decision.md</code> in whichever repository you use as the forum, and GitHub offers it every time someone opens a new issue. The sections are Alan&rsquo;s; the LOCI lines and the label are my additions.</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l">Decision</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">about</span><span class="p">:</span><span class="w"> </span><span class="l">Propose a decision and collect input in writing</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">title</span><span class="p">:</span><span class="w"> </span><span class="s2">&#34;[Decision] &#34;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nt">labels</span><span class="p">:</span><span class="w"> </span><span class="l">decision</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="nn">---</span><span class="w">
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Scope
</span></span></span><span class="line"><span class="cl"><span class="k">-</span> The goal of this issue is ...
</span></span><span class="line"><span class="cl"><span class="k">-</span> This issue is NOT about ...
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Why I&#39;m opening this issue
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## LOCI
</span></span></span><span class="line"><span class="cl"><span class="k">-</span> Lead:
</span></span><span class="line"><span class="cl"><span class="k">-</span> Owner:
</span></span><span class="line"><span class="cl"><span class="k">-</span> Consulted:
</span></span><span class="line"><span class="cl"><span class="k">-</span> Informed:
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Timeline
</span></span></span><span class="line"><span class="cl"><span class="k">-</span> Contributions by:
</span></span><span class="line"><span class="cl"><span class="k">-</span> Decision by:
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Context and materials
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="gu">## Proposal
</span></span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl">## Questions</span></span></code></pre></div></div>

<h2 class="relative group">GitHub Issues or GitHub Projects?
    <div id="github-issues-or-github-projects" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#github-issues-or-github-projects" aria-label="Anchor">#</a>
    </span>
    
</h2>
<p>If you&rsquo;re thinking about GitHub for project management more broadly, the two pieces do different jobs. Issues hold the discussion and, once closed, the decision. A GitHub Project is a board or table laid over issues from one or more repositories, with your own fields for status, owner or deadline. For a decision forum like Alan&rsquo;s, labels and the issue list are enough. Add a Project when you want every open decision on one screen, sorted by the date it has to be made, and when you start tracking delivery work in the same place, which is where most teams end up using both.</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2024/2024-01-04-githubforprojectmanagement/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
