Ship Your First Card Through GitHub

Introduction

30 Second Summary

Every real deliverable travels through the same loop: planned, built, reviewed, and shipped as a version others can trust. That loop is the transferable skill, not the content of any single artifact.

In this project, you will ship a one-page Global-Problem Card about a real, sourced statistic through a complete GitHub workflow. You will plan with decision records, draft with AI, score against a rubric, and deliver a tagged release.

What You'll Build

You will show someone your tagged GitHub release and walk them through the full trail: planned issues, a reviewed pull request, and a frozen version of your sourced card that passed the rubric before it shipped.

By the end of this project, you'll have:

• A tagged release (v1.0.0) inside a private GitHub organization repo, with both issues closed and a Project board showing the work moved from Todo to Done.
• Three MADR decision records you can defend under questioning, each naming what it beat, the tradeoff it accepted, and what would make you reverse it.
• All four signature artifacts ready for delivery: the validated working system, a two-line stakeholder readout, a teach-back that walks and defends the loop, and an honest after-action review.
• Secret Mission: Ship a second Global-Problem Card on a different sourced problem as v1.1.0, proving the rails are reusable.

Do I need to know Git already?

No. This project includes full setup for Git, the GitHub CLI, and your AI drafting tool. You need a GitHub account (free) and terminal access on macOS, Windows, or Linux.

Before We Start

Before you touch a single tool, lock in what you are about to build and why it matters. The loop you ship through is the lesson. The card is just the payload that proves you ran the loop correctly.

Set Up Your Tools

You cannot ship through GitHub rails without Git and the GitHub CLI authenticated against your account.

This step installs both tools, proves they work, and creates the organization that will house your repository. By the end, every gate passes and you are ready to design.

In this step, get ready to:

• Install Git and the GitHub CLI.
• Choose and install a code editor.
• Authenticate the GitHub CLI and create a free GitHub organization.
• Run a day-zero gate that confirms all tools work.

Install Git and the GitHub CLI

• Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
• Type Terminal (macOS/Linux) or PowerShell (Windows) and press Enter to open it.
• Check if Git is already installed by running:

git --version

✔️ I see a version number

Git is ready. Skip ahead to checking the GitHub CLI below.

ⓧ Command not found

Install Git for your operating system.

macOS

• Install Git using Homebrew by running:

brew install git

Windows

• Install Git using WinGet by running:

winget install --id Git.Git -e --source winget

Linux

• Install Git using apt by running:

sudo apt update && sudo apt install git -y

After the install finishes, close your terminal and reopen it so the PATH update takes effect.

• Confirm Git is now available by running:

git --version

You should see a version string like git version 2.x.x.

• Check if the GitHub CLI is already installed by running:

gh --version

✔️ I see a version number

The GitHub CLI is ready. Move on to the next substep.

ⓧ Command not found

Install the GitHub CLI for your operating system.

macOS

• Install the GitHub CLI using Homebrew by running:

brew install gh

Windows

• Install the GitHub CLI using WinGet by running:

winget install --id GitHub.cli --source winget

Linux

• Install the GitHub CLI using apt by running:

(type -p wget >/dev/null || sudo apt install wget -y) && sudo mkdir -p -m 755 /etc/apt/keyrings && wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null && sudo apt update && sudo apt install gh -y

After the install finishes, close your terminal and reopen it so the PATH update takes effect.

• Confirm the GitHub CLI is now available by running:

gh --version

You should see a version string like gh version 2.96.0 or newer.

Still seeing command not found?

Make sure you closed and reopened your terminal after installing. The PATH only updates in new terminal sessions.

On Windows, try opening a new PowerShell window as Administrator. On macOS, confirm Homebrew is installed by running brew --version first.

help me troubleshoot why git or gh is not found after installing

💡 Windows users: switch to Git Bash now

The Git install you just ran includes Git Bash, a terminal that understands Linux-style commands. From this point forward, use Git Bash instead of PowerShell for every terminal command in this project.

• Press the Windows key, type Git Bash, and press Enter to open it.

Commands like mkdir -p and ls -a work in Git Bash but not in PowerShell. Using Git Bash keeps every command in this project identical across macOS, Linux, and Windows.

Set up your code editor

You need a code editor to create and edit your project files. If you already have one installed, confirm it opens. If not, pick one of the three options below.

• Open your code editor now (VS Code, Cursor, or Google Antigravity).

✔️ I have a code editor open

Your editor is ready. Move on to the next substep.

ⓧ I don’t have one yet

Pick one of these free editors and install it:

• VS Code (recommended) — lightweight, widely used, works with almost every language. Download from code.visualstudio.com.
• Cursor — a VS Code fork with built-in AI chat and inline code generation. Download from cursor.com.
• Google Antigravity — an agent-first VS Code fork that can plan, write, and verify code autonomously. Download from antigravity.google/download.

• Run the installer and follow the prompts.
• Press Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
• Type the name of your editor and press Enter to open it.

Authenticate gh and create your organization

The GitHub CLI needs permission to act on your behalf. You will log in via your browser, then create the organization that will own your repository.

What prompts will gh auth login show?

This command is interactive. It asks three questions in your terminal:

• Where do you use GitHub? Select GitHub.com.
• What is your preferred protocol for Git operations? Select HTTPS.
• How would you like to authenticate? Select Login with a web browser.

It will display a one-time code and open your browser. Paste the code on the GitHub page to complete authentication.

• Authenticate the GitHub CLI by running:

gh auth login

• Follow the prompts as described above. When your browser opens, paste the one-time code and authorize the app.
• Confirm authentication succeeded by running:

gh auth status

You should see your GitHub username and the host github.com listed with a green checkmark or success indicator.

Authentication failed or timed out?

If the browser did not open automatically, copy the URL shown in the terminal and paste it into your browser manually.

If you see a token error, run gh auth login again. The previous attempt may have expired before you completed the browser step.

help me fix gh auth login failing or timing out

Now create a free GitHub organization. This is the shared account that will own your repository instead of your personal account.

• Open your browser and navigate to https://github.com/organizations/plan.
• Select the Free plan.
• Enter a name for your organization (for example, your-name-eng).
• Enter your email address when prompted.
• Skip inviting other members and complete the setup flow.

What is a GitHub organization?

A GitHub organization is a shared account that groups repositories and manages access for teams. Using an org keeps your project separate from your personal repos and mirrors how professional teams structure their work.

The free plan includes unlimited private repositories, Issues, and Projects at no cost.

• Confirm the org was created by running:

gh org list

You should see your new organization name (e.g., your-name-eng) in the output.

Run the day-zero gate

The day-zero gate is a set of checks that must all pass before you move on. If any check fails, you fix it here rather than discovering it mid-build.

Before you run the commands below, predict what you expect to see. Will all three succeed? What output do you expect from each?

• Run all three gate checks:

git --version
gh auth status
gh org list

What should I see?

• git --version prints a version string like git version 2.x.x.
• gh auth status shows your authenticated GitHub username and confirms github.com as the host.
• gh org list lists your organization name.

All three must succeed. If any command fails, fix it before continuing.

🙋‍♀️ One of the gate checks failed?

If git --version fails, scroll up to the install instructions and try again. Make sure you reopened your terminal after installing.

If gh auth status shows no account, re-run gh auth login and complete the browser flow.

If gh org list shows nothing, confirm you completed the organization setup at github.com/organizations/plan and that you are logged in as the same GitHub account.

help me figure out which day-zero gate check is failing and how to fix it

Optionally, if you plan to use Ollama for AI drafting later, check that it is available.

• Check if Ollama is installed by running:

ollama --version
ollama list

✔️ I see a version and model list

Ollama is ready. If you see gemma3 in the model list, you are all set for AI drafting later.

ⓧ Command not found or no models listed

That is fine. Ollama is optional. You can use any flat-rate AI client (such as Claude Pro or ChatGPT Plus) for the drafting steps later. No single AI engine blocks the project.

Your tools are ready and your organization is live on GitHub. Next up, you will design before you build: writing a requirements brief, decision records, and a build plan that the rest of the project executes against.

Design Before Build

Your tools are installed, authenticated, and your organization is live on GitHub. Now comes the part most people skip: the design.

Real teams design before they build. In this step, you produce the requirements brief, three decision records, the loop diagram, and the build plan before any files get committed. If you skip this, you cannot tell whether the final result is correct because there is no spec to check against.

In this step, get ready to:

• Write a requirements brief that spells out what "done" looks like.
• Document three engineering decisions in MADR format before building anything.
• Draw the shipping loop as a diagram and budget the build into five timed steps.

Write the requirements brief

The requirements brief reads back the assignment as acceptance criteria. If you cannot state what "done" looks like before you start, you cannot score the result at the end.

• Move to your Desktop by running this command:

cd ~/Desktop

• Create your project folder and its doc directories by running these commands:

mkdir -p global-problem-card/docs/decisions
cd global-problem-card

What did those commands do?

The -p flag tells mkdir to create all nested directories at once. You now have global-problem-card/docs/decisions/ ready for your design files.

• Confirm the directory structure exists by running:

ls docs

You should see decisions listed.

• Open the global-problem-card folder in your text editor.
• Create a new file at docs/brief.md and paste the following content:

# Requirements Brief

## Assignment

Ship a one-page Global-Problem Card through a complete GitHub workflow.

## Acceptance Criteria

1. The card (`card.md`) contains all three rubric items:
   - The problem stated in plain words a non-engineer understands.
   - The sourced number with a citation link to the primary source, verified as current.
   - An explicit, unhedged line stating what this card does not fix.
2. The repository lives inside the GitHub organization, not a personal account.
3. Both issues are closed by the pull request that merges the card (PR body carries each issue number).
4. A first release is tagged v1.0.0.
5. The AI draft scored 3/3 against `docs/rubric.md` before the card was merged.
6. All four signature artifacts are present:
   - Validated working system (merged card, closed issues, tagged release).
   - Stakeholder presentation (two-line readout to a non-engineer).
   - Teach-back (loop walk plus decision defense under follow-up).
   - After-action review (four questions, including what broke).
7. The README explains the repo so someone arriving tomorrow can follow the loop.

What does this file do?

The brief is your contract with yourself. Each numbered item is a condition you will check at the very end. If any item fails, the project is not done.

Notice item 5: the AI draft must score 3/3 against the rubric before it ships. That is the quality gate the rest of the loop depends on.

• Save docs/brief.md.
• In your terminal, confirm the file exists by running:

ls docs/brief.md

You should see docs/brief.md printed.

File not found?

• Make sure you saved the file inside the docs/ folder, not in the project root.
• Check that your terminal is inside the global-problem-card directory. Run pwd to confirm.

help me find where my brief.md file ended up

Write three MADR decision records

A MADR (Markdown Any Decision Records) file captures one engineering choice: what you decided, what you rejected, why, and what would make you reverse the call. Writing these before you build forces you to think through alternatives instead of defaulting to whatever comes first.

• Create a new file at docs/decisions/0001-card-format.md and paste the following content:

# Use Plain Markdown for the Global-Problem Card

## Context and Problem Statement

The card needs a format that is readable, diffable, and renderable on GitHub without extra tooling. What format should the card use?

## Decision Drivers

- Must render on GitHub without a build step
- Must be diffable in pull request reviews
- Must not require any paid tool or plugin
- Must work cross-platform without conversion

## Considered Options

- Plain Markdown
- HTML with inline CSS
- PDF generated from a template

## Decision Outcome

Chosen option: "Plain Markdown", because it renders natively on GitHub, diffs cleanly in PRs, and requires zero tooling beyond a text editor.

### Consequences

- Good, because any text editor can create and modify it
- Good, because GitHub renders it with formatting in the repo view
- Bad, because no visual styling (no brand colors, no layout control)
- Reversal trigger: if the card requires embedded interactive data visualizations, switch to HTML

What does a MADR record contain?

• Context and Problem Statement frames the decision as a question.
• Decision Drivers lists the constraints that matter.
• Considered Options names the alternatives you evaluated.
• Decision Outcome states what you chose and why.
• Consequences lists the good, the bad, and the reversal trigger that would undo this choice.

• Save docs/decisions/0001-card-format.md.
• Confirm it exists by running:

ls docs/decisions

You should see 0001-card-format.md listed.

• Create a new file at docs/decisions/0002-source-authority.md and paste the following content:

# Use the ITU Primary Source for the Connectivity Statistic

## Context and Problem Statement

The card cites a global statistic. Should we cite the original source directly or rely on news articles that quote it?

## Decision Drivers

- Citation must be verifiable by following a single link
- Source must be the data originator, not a relay
- Source must still be accessible when someone checks months later

## Considered Options

- ITU Facts and Figures 2025 press release (primary source)
- News article quoting the ITU figure (secondary source)
- Academic paper citing ITU data (tertiary source)

## Decision Outcome

Chosen option: "ITU Facts and Figures 2025 press release", because it is the data originator, the URL is permanent, and the number is stated without editorial framing.

### Consequences

- Good, because the reader can verify the number in one click
- Good, because no intermediary can misquote or round the figure
- Bad, because if ITU restructures their site, the URL may break
- Reversal trigger: if ITU removes the page and no archive exists, fall back to the ITU Statistics page (itu.int/en/ITU-D/Statistics/) which states the same figure

Why cite the ITU directly?

News articles often round or editorialize numbers. The ITU is the data originator for global connectivity statistics. Citing the primary source means anyone can verify the number in one click, with no intermediary changing the figure.

• Save docs/decisions/0002-source-authority.md.
• Create a new file at docs/decisions/0003-ai-drafting.md and paste the following content:

# Use a Local or Flat-Rate AI Client for Drafting

## Context and Problem Statement

The card text and issue text should be AI-drafted for speed, but no step should depend on a metered service or require a credit card.

## Decision Drivers

- No metered API cost (no per-token billing)
- Must work offline or on a flat-rate subscription already paid
- Must not block the workflow if one engine is unavailable

## Considered Options

- Ollama with Gemma 3 (local, open-weight, free)
- Flat-rate AI client already subscribed (e.g., Claude Pro, ChatGPT Plus)
- Manual drafting (no AI)

## Decision Outcome

Chosen option: "Ollama with Gemma 3 as primary, flat-rate client as fallback", because it costs nothing, runs locally, and the fallback ensures no single engine blocks the workflow.

### Consequences

- Good, because zero marginal cost per draft
- Good, because works offline once the model is pulled
- Bad, because Ollama requires ~5GB disk for the model and may be slow on low-RAM machines
- Reversal trigger: if the machine cannot run Ollama (insufficient RAM or disk), switch to the flat-rate client immediately

Why document the AI decision?

Recording the AI choice up front prevents scope creep. If Ollama is too slow or unavailable, the decision record already names the fallback. No scrambling mid-build.

• Save docs/decisions/0003-ai-drafting.md.
• Confirm all three decision records exist by running:

ls docs/decisions

You should see all three files listed: 0001-card-format.md, 0002-source-authority.md, and 0003-ai-drafting.md.

Missing a decision file?

• Confirm you saved each file inside docs/decisions/, not inside docs/ directly.
• Check the filename matches exactly, including the four-digit prefix (0001, 0002, 0003).

help me find my missing decision record files

Draw the loop diagram and write the build plan

The loop diagram shows the full path from issue to release as one picture. The build plan then budgets that path into five timed steps so you know exactly how long each phase gets.

• Create a new file at docs/loop-diagram.md and paste the following content:

# GitHub Shipping Loop

```
Issue --> Branch --> Commit --> Push --> PR --> Merge --> Release
  |                                      |        |          |
  |  (planned work)           (review)   |  (closes issues)  |
  +--------- Board: Todo ---------------+--- Board: Done ----+
```

## In Plain Words

1. An issue describes one piece of planned work.
2. A branch is your safe copy of the files to change.
3. A commit saves a snapshot of your changes with a message.
4. A push sends your branch to GitHub.
5. A pull request asks to merge your branch into main.
6. A merge accepts it and closes the referenced issues.
7. A tagged release is a named, frozen version anyone can download.

What does this diagram show?

The top row is the sequence of actions. The bottom row is the Project board tracking state. Work starts in Todo when you open the issue, and moves to Done when the merge closes it. Every step you take in the next phase maps to one node in this diagram.

• Save docs/loop-diagram.md.
• Create a new file at docs/plan.md and paste the following content:

# 30-Minute Build Plan

Drawn from the loop diagram. Five steps, each budgeted 6 minutes.

| Step | Action | Budget |
|------|--------|--------|
| 1 | Create repo, board, issues | 6 min |
| 2 | AI-draft card + docs | 6 min |
| 3 | Score draft, edit to 3/3 | 6 min |
| 4 | Branch, PR, merge | 6 min |
| 5 | Tag release, README, verify | 6 min |
| **Total** | | **30 min** |

Why budget each step at 6 minutes?

Equal budgets make it obvious when one phase is running long. If step 3 (scoring and editing) takes 12 minutes, you know the AI draft was weaker than expected and the rubric caught real problems. That is useful data for the after-action review.

• Save docs/plan.md.

Before you verify, predict: how many files should ls show inside docs/? Remember that decisions/ is a directory, not a file.

• Run this to see everything inside docs/:

ls docs
ls docs/decisions

The first command shows four items: brief.md, decisions, loop-diagram.md, and plan.md. The second command shows three files: 0001-card-format.md, 0002-source-authority.md, and 0003-ai-drafting.md. That is seven Markdown files total across both directories.

Seeing fewer than seven files?

• Run pwd and confirm you are inside global-problem-card/ on your Desktop.
• Check that each file was saved in the correct subfolder. A common mistake is saving 0001-card-format.md directly inside docs/ instead of docs/decisions/.
• If a file landed in the wrong place, move it with mv docs/0001-card-format.md docs/decisions/.

help me sort out my file structure

You now have a complete design package: a brief that defines done, three decisions that justify how, a diagram that shows the path, and a plan that budgets the time. Next up, you will stand up the actual GitHub rails and let AI draft the card from your template.

Stand Up the Rails and AI-Draft

Your plan exists, your decisions are recorded, and your budget is set. Nothing has shipped yet because the rails are not built. This step stands up the infrastructure that carries the card through the loop.

You will create the private repository inside your organization, open the Project board and both issues as planned tickets, then fire AI prompts to draft the card from the template.

In this step, get ready to:

• Create the private repo in your org with all pre-staged files.
• Open the Project board and both issues before writing a single line of the card.
• AI-draft the card from the template using your local or flat-rate AI client.

Create the private repo and add the pre-staged files

The repository is the container for everything you ship. Creating it inside your organization (not your personal account) mirrors how real teams isolate project ownership.

• Navigate to the project folder you created in Step 2 and turn it into a GitHub repository by running these commands:

cd ~/Desktop/global-problem-card
git init
gh repo create [[ORGNAME="your-org-name"]]/global-problem-card --private --source=. --remote=origin

What do these commands do?

git init turns the existing folder into a local git repository. --source=. tells the GitHub CLI to create the remote repo from your current directory instead of cloning a fresh one. --remote=origin adds the new GitHub repo as the remote named origin. Your design files from Step 2 are already here, so no copying is needed.

• Confirm the repo is private and lives inside the org by running:

gh repo view --json owner,visibility

You should see "visibility": "private" and an owner login matching your org name.

Seeing your personal username as owner?

You likely omitted the org prefix in the gh repo create command. Delete the repo with gh repo delete global-problem-card --yes and re-run the create command with your org name before the slash.

help me fix my repo ownership

• Create the additional directories for templates and issue templates by running:

macOS

mkdir -p templates .github/ISSUE_TEMPLATE

Windows

mkdir templates, .github\ISSUE_TEMPLATE

Linux

mkdir -p templates .github/ISSUE_TEMPLATE

• Create the .gitattributes file to normalize line endings across operating systems by running:

echo "* text=auto" > .gitattributes

• Confirm the directories and .gitattributes exist by running:

ls -a

You should see .gitattributes, templates, .github, and docs in the output.

Now you will create the pre-staged template files. Open each file in your text editor and paste the content shown.

• Create templates/card-template.md with the following content:

# [Headline: State the Problem in Five Words or Fewer]

## The Problem

[State the problem in plain words. No jargon. A non-engineer must understand this paragraph on first read.]

## The Number

**[Exact figure from the primary source, verified as current before quoting.]**

Source: [Authority Name], *[Publication Title and Year]*.
[URL to the primary source page where the number appears]

## What This Card Does Not Fix

[One direct sentence. No hedging. State exactly what this card cannot do. Then state what it is: practice in shipping sourced, honest work through real engineering rails.]

What is this template for?

This is the four-part structure every Global-Problem Card must follow. The placeholders in brackets tell your AI exactly what to fill in. The rubric scores against these four parts.

• Create templates/sample-problem.md with the following content:

# Sample Problem: Global Internet Connectivity

## The Sourced Fact

About 2.2 billion people remain offline in 2025.

## The Primary Source

International Telecommunication Union, *Facts and Figures 2025*.
https://www.itu.int/en/mediacentre/Pages/PR-2025-11-17-Facts-and-Figures.aspx

Published: 2025-11-17.

## Verification Instruction

Visit the URL above before quoting. Confirm the figure is still 2.2 billion. If ITU has published a newer edition, use the current number and update the citation.

## The Honest Limit (Example)

"This card does not connect a single offline person."

This is one sentence, direct, with no qualifiers. It does not say "may not" or "alone cannot." It states a fact about what the artifact does not do.

What is this sample for?

This gives your AI the sourced fact, the primary authority, and an example of the honest-limit line. It is the raw material the AI uses to fill the card template.

• Confirm both template files exist by running:

ls templates/

You should see card-template.md and sample-problem.md listed.

• Create .github/ISSUE_TEMPLATE/card-issue.md with the following content:

---
name: Global-Problem Card
about: Track one card from draft to shipped
title: "Write Global-Problem Card (3/3 rubric)"
labels: card
---

## Acceptance Criteria

- [ ] `card.md` states the problem in plain words (rubric item 1)
- [ ] `card.md` includes sourced number with citation verified as current (rubric item 2)
- [ ] `card.md` includes explicit, unhedged honest-limit line (rubric item 3)
- [ ] Card scores 3/3 against `docs/rubric.md` before merge

• Create .github/ISSUE_TEMPLATE/docs-issue.md with the following content:

---
name: Signature Artifacts
about: Track the teach-back, readout, and AAR
title: "Deliver teach-back, readout, and AAR"
labels: docs
---

## Acceptance Criteria

- [ ] `docs/teach-back.md` walks the issue-to-release loop
- [ ] `docs/teach-back.md` defends three decisions with reversal triggers
- [ ] `docs/readout.md` is two lines for a non-engineer
- [ ] `docs/aar.md` answers four questions (planned, happened, change, broke)

What are issue templates?

When someone opens a new issue in your repo, GitHub offers these templates as starting points. The acceptance criteria checklist inside each template makes it clear what "done" looks like before work begins.

• Confirm both issue templates exist by running:

ls .github/ISSUE_TEMPLATE/

You should see card-issue.md and docs-issue.md listed.

• Create docs/rubric.md with the following content:

# Scoring Rubric: Global-Problem Card

Score each item pass or fail. The card ships only at 3/3.

| # | Item | Pass | Fail |
|---|------|------|------|
| 1 | Problem in plain words | A non-engineer understands it on first read. No jargon, no acronyms without expansion. | Contains technical terms, passive constructions, or assumes domain knowledge. |
| 2 | Sourced number with citation | Exact figure from a primary source. Citation link resolves to the originator's page. Figure verified as current. | Number is rounded, unsourced, from a secondary relay, or the link is broken. |
| 3 | Honest-limit line | One direct sentence stating what this card does not fix. No hedging ("may not", "alone cannot", "while this"). | Line is hedged, buried, conditional, or missing entirely. |

## Scoring

- 3/3: ship the card.
- Below 3/3: edit the failing item(s) and re-score. Do not ship until 3/3.

Why a rubric before the draft?

The rubric defines "done" objectively. Without it, you cannot tell whether the AI draft is ready to ship. You will score your draft against this rubric in the next step.

• Stage all your files and push them to GitHub to establish the main branch by running these commands:

git add .
git commit -m "Add design docs, templates, rubric, and issue templates"
git push -u origin main

You should see output confirming the push to origin/main. Your repo now has a default branch with all the setup files.

Why push before creating issues?

The push establishes the main branch on GitHub. Without a default branch, later commands like gh pr create --base main would fail. Pushing now also means your design docs, templates, and rubric are already visible on GitHub before you open the issues that reference them.

🙋‍♀️ Push rejected?

• If you see error: src refspec main does not match any, run git branch -M main to rename your default branch to main, then try the push again.
• If you see a permission error, confirm gh auth status shows you are logged in and that the repo owner matches your org.

help me fix a push failure to my new repo

Create the Project board and open both issues

Real teams plan work on a board before executing it. You open both issues as tickets in Todo so the board shows the work was planned before it was built.

• In your browser, navigate to your organization's page on GitHub.
• Click the Projects tab.
• Click New project.
• Select Board as the layout.
• Name the project Global-Problem Card and click Create.

Why a Board layout?

The Board layout shows columns (Todo, In Progress, Done) that map directly to the loop diagram you drew in Step 2. Each issue moves left to right as you complete the work. This makes the planned-to-done journey visible to anyone viewing the project.

• Back in your terminal, create both issues by running these commands:

gh issue create --title "Write Global-Problem Card (3/3 rubric)" --body "Acceptance: card.md contains (1) problem in plain words, (2) sourced number with citation, (3) explicit honest-limit line. Rubric: docs/rubric.md" --repo [[ORGNAME="your-org-name"]]/global-problem-card

gh issue create --title "Deliver teach-back, readout, and AAR" --body "Acceptance: docs/teach-back.md walks issue-to-release loop and defends three decisions. docs/readout.md is two lines for a non-engineer. docs/aar.md answers four questions." --repo [[ORGNAME="your-org-name"]]/global-problem-card

What do these issues represent?

Issue #1 tracks the card itself. Issue #2 tracks the signature artifacts (teach-back, readout, after-action review). Both must be closed by the pull request when you merge in a later step.

• In the GitHub web UI, return to your Global-Problem Card project board.
• Click + Add item in the Todo column.
• Search for and add both issues to the Todo column.

• Verify both issues are open by running:

gh issue list --repo [[ORGNAME="your-org-name"]]/global-problem-card

You should see two open issues listed: Write Global-Problem Card (3/3 rubric) and Deliver teach-back, readout, and AAR.

Not seeing both issues?

Check that the --repo flag matches your org name exactly. If you omitted it, the issue may have been created on a different repo. Run gh issue list without --repo from inside the global-problem-card folder to check the current repo.

help me find my missing issues

AI-draft the card from the template

The rails are up. Two issues sit in Todo on the board. Now you fire AI prompts to produce a first draft. The AI drafts first. You score and edit next. No draft ships without passing the rubric.

• Open your AI client (Ollama with Gemma 3 locally, or your flat-rate AI client).
• Copy the full contents of templates/card-template.md and templates/sample-problem.md into your AI prompt.
• Ask the AI to fill in the four parts of the card template using the sample problem as source material. Tell it to produce a headline, the problem in plain words, the sourced number with the ITU citation, and the honest-limit line.
• Save the AI output as card.md in the root of your global-problem-card folder.

Use multiple prompts for multiple drafts

You do not need to get everything in one prompt. Fire separate prompts to draft the card, the two-line readout text, and the teach-back section outline. Save each draft locally. Speed comes from letting the AI propose everything, then scoring it all at once.

• In a second prompt, ask the AI to draft a two-line readout explaining the card to a non-engineer. Save the output for later (you will formalize it as docs/readout.md in a later step).
• In a third prompt, ask the AI to draft an outline for the teach-back section: walking the loop from issue to release, and defending the three decisions. Save this output for later.

Before you continue, do you expect your AI-drafted card.md to pass the rubric at 3/3 on the first try?

• Verify card.md exists by running:

cat card.md

You should see your AI-drafted card with a headline, problem statement, sourced number, and an honest-limit line. The draft exists. Whether it scores 3/3 is the next step's job.

Card is empty or missing?

Make sure you saved the AI output to a file named exactly card.md (not card.txt or Card.md) in the root of the global-problem-card folder, not inside a subfolder.

help me save my AI draft correctly

The rails are standing. Your board has two tickets in Todo, your AI has produced a first draft, and nothing has merged yet. Next up, you will score that draft against the rubric and edit it until it hits 3/3.

Score the Draft Against the Rubric

Your AI produced a draft of card.md in the last step. A draft that exists is not the same as a draft that ships. The rubric is the gate between "looks reasonable" and "actually correct."

In this step, you score the AI draft against docs/rubric.md, discover where it falls short, edit until the card passes 3/3, and write the remaining three signature artifacts.

In this step, get ready to:

• Score the AI draft against the three-item rubric.
• Edit card.md to pass 3/3.
• Write the remaining signature artifacts: teach-back, readout, and after-action review.

Score your AI draft against the rubric

The rubric in docs/rubric.md has three items. Each one passes or fails independently. The card ships only at 3/3.

• Open card.md in your text editor.
• Open docs/rubric.md side by side for reference.
• Read through your AI draft and score each rubric item:

• Item 1: Problem in plain words. Does your "The Problem" section avoid jargon? Would a non-engineer understand it on first read?
• Item 2: Sourced number with citation. Is the exact figure stated? Does the URL point to the ITU primary source, not a news article?
• Item 3: Honest-limit line. Is there one direct sentence stating what this card does not fix? No hedging words like "may not", "alone cannot", or "while this"?

Before you score item 3, predict: do you think your AI wrote a direct, unhedged honest-limit line, or did it soften the statement with qualifiers?

Read the "What This Card Does Not Fix" section of your draft now.

Your AI almost certainly hedged it. You will likely see something like "While this card alone may not fully address the connectivity gap..." or "This card cannot single-handedly solve..." with conditional language buried throughout. That is not 3/3. The rubric explicitly fails hedged, buried, or conditional lines.

Why does AI always hedge this line?

Language models are trained on text that qualifies claims. When asked to state a limitation, they default to diplomatic phrasing ("may not", "alone cannot") because that pattern dominates their training data.

The rubric is designed to catch exactly this failure mode. The honest-limit line must be direct: "This card does not connect a single offline person." No qualifiers. That directness is what makes it honest rather than performative.

Edit the card to 3/3

The draft failed item 3. Now you fix it. The AI proposes, you dispose.

• In card.md, find the "What This Card Does Not Fix" section.
• Delete whatever hedged language your AI wrote there.
• Replace it with a direct, unhedged statement. The target:

## What This Card Does Not Fix

This card does not connect a single offline person. It is a one-page artifact shipped through engineering rails to build the habit of clear, sourced, honest delivery. The problem is real. The card is practice.

What makes this line pass the rubric?

"This card does not connect a single offline person." One sentence. No "may not." No "alone cannot." No "while this." It states a fact about what the artifact does not do. The sentences that follow explain what the card IS (practice), which anchors the limit without softening it.

• Next, verify your citation URL. Open https://www.itu.int/en/mediacentre/Pages/PR-2025-11-17-Facts-and-Figures.aspx in your browser.
• Confirm the page still states 2.2 billion people remain offline. If ITU has published a newer figure, update your card to match.
• Check the "The Problem" section for any jargon or passive constructions. A non-engineer must understand it on first read.
• Edit your full card.md to match this target content:

# 2.2 Billion People Are Still Offline

## The Problem

Almost a third of the world has no internet access. These 2.2 billion people are concentrated in low- and middle-income countries, cut off from education, employment, healthcare information, and civic participation that the connected world takes for granted.

## The Number

**2.2 billion people remain offline in 2025.**

Source: International Telecommunication Union, *Facts and Figures 2025*.
https://www.itu.int/en/mediacentre/Pages/PR-2025-11-17-Facts-and-Figures.aspx

Verify this figure is current against the latest ITU report before citing it elsewhere.

## What This Card Does Not Fix

This card does not connect a single offline person. It is a one-page artifact shipped through engineering rails to build the habit of clear, sourced, honest delivery. The problem is real. The card is practice.

What does this card do?

The card has four parts, each serving a rubric item. The headline grabs attention. "The Problem" explains the issue in plain language (rubric item 1). "The Number" provides the verified, sourced statistic with its primary-source citation (rubric item 2). "What This Card Does Not Fix" is the honest-limit line (rubric item 3).

• Save card.md.
• Re-score against docs/rubric.md. Confirm all three items pass: plain language (pass), sourced number with live citation (pass), direct honest-limit line (pass). That is 3/3.

Still scoring below 3/3?

Check item 1: read the "The Problem" section aloud. If any word would need explaining to a friend who is not an engineer, replace it.

Check item 2: click the ITU URL in your card. If it does not load or shows a different number, update the citation.

Check item 3: search your honest-limit section for the words "may", "alone", "while", "cannot fully", or "single-handedly." Any of those is a fail. Rewrite to be direct.

Help me fix my card to pass 3/3 on the rubric.

Write the remaining signature artifacts

The card is 3/3. Now you write the three remaining signature artifacts that complete your delivery: the teach-back, the stakeholder readout, and the after-action review.

• Create docs/teach-back.md with the loop walkthrough and decision defense. Start with the opening and loop sections:

# Teach-Back: The Shipping Loop

## What This Is

A one-page walk of the loop from issue to release, written so someone who has never seen this repository can run the same workflow. Also defends the three decisions under follow-up.

## The Loop

1. **Open an issue** on the Project board. The issue describes what you will deliver and how you will know it is done. Move it to Todo.
2. **Create a branch** from main. Name it after the work (e.g., `ship-card`). This keeps main clean while you work.
3. **Commit your files** to the branch. Each commit has a message explaining what changed.
4. **Push the branch** to GitHub so it exists remotely.
5. **Open a pull request** from your branch into main. In the PR body, write `Closes #1, Closes #2` so merging automatically closes the issues.
6. **Review the PR.** Check the rendered Markdown in Files Changed. Confirm the card scores 3/3.
7. **Merge the PR.** This moves your changes into main, closes the referenced issues, and deletes the branch.
8. **Tag a release** (e.g., v1.0.0). This creates a frozen, named version anyone can download or reference.
9. **Update the board.** Move the closed issues to Done. The board now shows the full journey: planned, worked, shipped.

What does the teach-back prove?

The teach-back is signature artifact #3. It proves you can walk someone else through the entire loop from issue to release. If you can teach it, you understand it. If you can defend the decisions under follow-up questions, you own the reasoning.

• Add the verification and decision-defense sections to the same file:

## How to Verify Completion

- `gh issue list --state closed` shows both issues closed.
- `gh release view v1.0.0` shows the tagged release.
- The board shows all items in Done.
- The README explains the repo to a stranger.

## Defending the Three Decisions

When asked, defend each decision by naming what it beat, the tradeoff you accepted, and what would make you reverse it:

- **Why Markdown?** Beat HTML and PDF. Tradeoff: no styling. Reverse if the card needs interactive data visualizations.
- **Why ITU primary source?** Beat news articles and academic papers. Tradeoff: depends on ITU keeping the URL live. Reverse if the URL dies with no archive.
- **Why local AI (Ollama)?** Beat flat-rate client and manual drafting. Tradeoff: needs disk space and RAM. Reverse if the machine cannot run it; switch to flat-rate client so no single engine blocks the day.

What does each decision defense include?

Each defense names three things: the alternative it beat, the tradeoff you accepted by choosing it, and the specific trigger that would make you reverse the decision. This structure means you are not just justifying your choice. You are stating the conditions under which it stops being the right choice.

• Save docs/teach-back.md.

✔️ Awesome, I've got everything!

Great. Make sure you have saved the file before moving on.

ⓧ I'd like to double check the full code

Your docs/teach-back.md is longer than 30 lines. Scroll up and confirm both parts are present in order: the "What This Is" and "The Loop" sections from part 1, followed by the "How to Verify Completion" and "Defending the Three Decisions" sections from part 2.

• Create docs/readout.md with the two-line stakeholder presentation:

# Stakeholder Readout

2.2 billion people are offline in 2025, per the International Telecommunication Union. This card documents that number, its source, and what a one-page artifact does not pretend to fix. The problem is real; the card is practice in shipping sourced, honest work through real engineering rails.

What is the readout for?

The stakeholder readout is signature artifact #2. It explains the card to a non-engineer in two lines. If you cannot summarize your work in two lines, you do not yet understand what you built. This is the artifact most often dropped in real projects.

• Save docs/readout.md.
• Create docs/aar.md with the after-action review template:

# After-Action Review

## What was planned?

Ship a one-page Global-Problem Card through a complete GitHub workflow (org, repo, board, issues, PR, release) in 30 minutes, producing all four signature artifacts.

## What happened?

[Fill in after completing the project. Describe what actually occurred.]

## What would you change?

[Fill in after completing the project. Note what you would do differently next time.]

## What broke?

[Fill in after completing the project. Be honest. If nothing broke, say so and note what came closest.]

Why are three sections left as placeholders?

The after-action review (signature artifact #4) asks four questions. You can answer "What was planned?" now because the brief defines it. The other three questions (what happened, what you would change, what broke) can only be answered honestly after you finish the full loop. You will fill them in at the end of the project.

• Save docs/aar.md.
• Confirm all four signature artifact files exist by running:

ls docs/teach-back.md docs/readout.md docs/aar.md card.md

You should see all four file paths listed with no errors.

Seeing 'No such file or directory'?

Make sure you are in the global-problem-card directory. Run pwd to check. If you are in the wrong folder, run cd ~/Desktop/global-problem-card and try again.

If a specific file is missing, create it and paste the content from the instructions above.

Help me find my missing signature artifact files.

Your card scores 3/3. All four signature artifact files exist locally: the validated card, the teach-back, the readout, and the after-action review. The quality gate is passed. Next up, you ship everything through the full loop: branch, pull request, merge, and tagged release.

Ship and Close the Loop

Your card scores 3/3 against the rubric. Every item passes. But the card is not shipped yet.

A finished artifact sitting on your local machine is invisible to anyone else. It needs to travel the full loop: branch, commit, PR, merge, and tagged release. That is what makes it real and what closes the two open issues on your board.

In this step, get ready to:

• Branch, commit, and push your card and docs to GitHub.
• Open a pull request that closes both issues on merge.
• Write the README, tag a v1.0.0 release, and update the board.

Create a feature branch, commit, and push

All your work lives on a feature branch so main stays clean until the PR is reviewed and merged.

• Create the branch, stage all your files, commit, and push to GitHub by running these commands:

git checkout -b ship-card
git add card.md docs/
git commit -m "Add Global-Problem Card and supporting docs"
git push --set-upstream origin ship-card

What do these commands do?

• git checkout -b ship-card creates a new branch named ship-card and switches to it.
• git add card.md docs/ stages the card and the entire docs/ folder for commit.
• git commit -m "..." saves a snapshot of the staged files with a message describing the change.
• git push --set-upstream origin ship-card sends your branch to GitHub and links your local branch to the remote one.

• You should see output confirming the branch was pushed, ending with a line showing the remote URL for the new branch.

Push rejected or permission denied?

• Make sure you are inside the global-problem-card folder. Run pwd to check.
• Confirm the repo belongs to your org, not your personal account. Run gh repo view --json owner and check the owner matches your org name.
• If gh auth status shows you are not logged in, re-run gh auth login and try the push again.

Help me debug a push failure to my GitHub org repo.

Open a pull request and merge

The pull request is where the loop connects back to the planned issues. The PR body references both issues so merging automatically closes them.

• Open the pull request by running this command:

gh pr create --title "Ship Global-Problem Card v1.0.0" --body "Closes #1, Closes #2. Card scores 3/3 against rubric. All four signature artifacts included." --base main

Why does the PR body say Closes #1, Closes #2?

GitHub automatically closes referenced issues when a PR merges if the body contains Closes #N. This links the work (the PR) to the planned tickets (the issues) so merging proves the plan was executed.

• You should see output confirming the PR was created, including a URL to view it on GitHub.
• Open that URL in your browser.
• Click the **Files changed** tab and confirm your card.md renders correctly with all three rubric items visible.

• Merge the PR by running this command:

gh pr merge --squash --delete-branch

What does this command do?

• --squash combines all your commits into a single clean commit on main.
• --delete-branch removes the ship-card branch from both your machine and GitHub after the merge completes.

• You should see a confirmation message indicating the PR was squashed and merged, and that the branch was deleted.

Merge failed or branch not deleted?

• If the merge fails with a conflict, run git pull origin main on your ship-card branch, resolve conflicts, commit, push, and try merging again.
• If the branch was not deleted automatically, you can remove it manually with git branch -d ship-card locally.

Help me fix a PR merge failure in my GitHub CLI workflow.

Write the README, tag the release, and update the board

The merge closed both issues. Before you tag a release, pull main locally and write the README. A tagged release freezes a snapshot, so everything needs to be in place first.

• Pull the merge commit to your local main branch by running:

git pull

Now write the README so someone arriving tomorrow can follow the whole thing.

• Open README.md in your text editor and replace its contents with this first section:

# Global-Problem Card

A one-page sourced artifact shipped through real engineering rails to practice the delivery loop.

## Why This Problem

About 2.2 billion people are still offline, per the International Telecommunication Union. Nothing here connects any of them. The problem forces the card to be sourced rather than a slogan, and honest rather than aspirational. The honest limit is written on the card itself, not hidden.

## What This Repository Contains

- `card.md` -- The Global-Problem Card (2.2 billion offline, ITU 2025)
- `templates/` -- Card template, sample problem, issue templates, and scoring rubric
- `docs/brief.md` -- Requirements brief with acceptance criteria
- `docs/decisions/` -- Three MADR decision records (format, source, AI)
- `docs/rubric.md` -- Three-item scoring rubric (pass at 3/3 or edit)
- `docs/loop-diagram.md` -- ASCII diagram of the GitHub shipping loop
- `docs/plan.md` -- 30-minute build budget (five steps, 6 min each)
- `docs/teach-back.md` -- One-pager walking the loop and defending decisions
- `docs/readout.md` -- Two-line stakeholder presentation
- `docs/aar.md` -- After-action review (four questions)

• Continue README.md by adding this content directly below what you just pasted:

## The Four Signature Artifacts

1. Validated working system: merged card, closed issues, tagged v1.0.0 release.
2. Stakeholder presentation: `docs/readout.md`.
3. Teach-back: `docs/teach-back.md`.
4. After-action review: `docs/aar.md`.

## How to Run This Loop Yourself

1. Open an issue describing your card
2. Branch from main, write, commit, push
3. Open a PR referencing the issue (`Closes #N`)
4. Merge, tag a release
5. Update the board

See `docs/teach-back.md` for the full walkthrough.

## Releases

- v1.0.0 -- First Global-Problem Card. Both issues closed by PR. Card scores 3/3. All four signature artifacts delivered.

## Cross-Platform Note

This project runs on macOS, Windows, and Linux. Git, the gh CLI, and `.gitattributes` with `* text=auto` cover all three. The clean-clone timed run is still owed on all three operating systems. This was authored on Windows 11 with WSL2. macOS and Linux are reasoned from the same tools, not yet timed. That difference is stated rather than blurred.

What does the README cover?

• It explains why this specific problem was chosen (sourced and honest, not a slogan).
• It lists every file in the repo so a stranger can navigate it.
• It names all four signature artifacts and links to where they live.
• It gives a five-step guide so someone else can run the same loop.

• Save README.md.
• Commit and push the README directly to main by running these commands:

git add README.md
git commit -m "Add README with repo guide and loop walkthrough"
git push

• You should see the push succeed with output confirming the commit was sent to origin/main.

• Tag the v1.0.0 release by running this command:

gh release create v1.0.0 --title "v1.0.0" --notes "First Global-Problem Card. Card scores 3/3. Both issues closed by PR. All four signature artifacts delivered."

You should see output confirming the release was created, including a URL to view it on GitHub.

Before you run the final check, predict: will both issues show as closed, or will one still be open?

• Verify everything shipped by running these commands:

gh release view v1.0.0
gh issue list --state closed

You should see the release details for v1.0.0 and both issues listed as closed. That confirms the full loop completed: planned work became a merged artifact with a tagged release.

Release not found or issues still open?

• If the release is not found, confirm you ran gh release create v1.0.0 successfully earlier. You can re-run it if needed.
• If an issue is still open, check that your PR body contained Closes #1, Closes #2 exactly. You can close it manually with gh issue close 1 or gh issue close 2.
• Make sure you are running these commands from inside the global-problem-card folder so the CLI knows which repo to query.

Help me verify my release and closed issues in the GitHub CLI.

✔️ Awesome, I've got everything!

Great. Double check you saved README.md and that both verification commands showed success.

ⓧ I'd like to double check the full README

Scroll up and confirm your README.md contains both chunks in order: the first chunk starts with # Global-Problem Card and ends with the contents list. The second chunk starts with ## The Four Signature Artifacts and ends with the Cross-Platform Note. Confirm no content is missing between the two halves.

Secret mission

Ship a Second Card as v1.1.0

The rails are built. Can you prove they are reusable? Source a different global problem, verify its number against the primary authority, and ship a second card through the exact same loop as v1.1.0.

Clean Up Your Resources

Clean Up Your Resources

Decide whether to keep your resources running, pause them to come back later, or delete them entirely. This project runs entirely on GitHub Free and local tools, so there are no ongoing costs.

Resources you used:

• Local global-problem-card project folder on your Desktop.
• GitHub private repository global-problem-card inside your organization.
• GitHub Project board ("Global-Problem Card").
• GitHub organization (the one you created in Step 1).
• gh CLI authentication session.
• Git (installed in Step 1).
• gh CLI (installed in Step 1).

Keep everything running

No action needed. Choose this if you plan to use your GitHub organization, repository, and tools for future projects.

• Your repository, board, and releases stay intact for reference.
• Git and the gh CLI remain installed and ready for your next project.
• Your gh CLI stays authenticated so you can use it immediately next time.

Pause - I'll come back to this later

Sign out of the gh CLI to clear your authentication session, but keep your files and GitHub resources intact.

• Sign out of the gh CLI by running:

gh auth logout

• Your local project folder, repository, board, and organization all stay intact.
• When you return, run gh auth login to re-authenticate.

Delete - I don't want to use this again

Remove all project resources and start fresh. Follow these steps in order.

Delete the local project folder:

macOS

rm -rf ~/Desktop/global-problem-card

Windows

Remove-Item -Recurse -Force ~\Desktop\global-problem-card

Delete the GitHub repository:

• Go to your global-problem-card repository on GitHub.
• Click Settings in the top navigation bar.
• Scroll to the bottom to the Danger Zone section.
• Click Delete this repository and follow the confirmation prompts.

Delete the Project board:

• Navigate to your organization page on GitHub.
• Click Projects in the organization navigation.
• Open the "Global-Problem Card" project.
• Click the three-dot menu, then Settings.
• Scroll to the bottom and click Delete project.

Delete the GitHub organization:

• Navigate to your organization page on GitHub.
• Click Settings in the organization navigation.
• Scroll to the Danger Zone section at the bottom.
• Click Delete this organization and follow the confirmation prompts.

Sign out of the gh CLI:

gh auth logout

Uninstall Git and the gh CLI (optional):

macOS

brew uninstall gh
brew uninstall git

Windows

winget uninstall --id GitHub.cli
winget uninstall --id Git.Git

These tools are useful for many projects, so only uninstall them if you are certain you will not use them again.

Nice Work!

Nice Work!

You just shipped a sourced, honest Global-Problem Card through the exact engineering rails a real team uses for any deliverable. The card is small. The loop you proved is not.

Here is what you built and what you now own:

• Shipped a Global-Problem Card through a complete GitHub workflow: organization, repository, Project board, issues, branch, pull request, merge, and tagged release.
• Wrote three MADR decision records documenting engineering choices before the build, each naming the alternative it beat, the tradeoff it accepted, and the trigger that would reverse it.
• Used AI to draft and a rubric to gate quality. The AI proposes, you dispose. No draft shipped below 3/3.
• Secret Mission: Proved the rails are reusable by shipping a second card as v1.1.0.

Ready to quiz yourself?