Build a Cross-Platform Go Doctor

Build a Go doctor for local tools, model readiness, and release handover.

Introduction

30 Second Summary

Your first morning with a customer can disappear while you prove a laptop is ready. A verbal promise gives the next engineer nothing they can rerun.

In this project, you will build a cross-platform readiness doctor in Go that verifies the toolchain plus a local qwen3:8b model through Ollama. Your private GitHub handover will carry the proof from issue to release.

What You'll Build

You will demo one readiness command that finishes with fifteen PASS lines followed by 15 checks, 0 failed.

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

Cross-platform proof: Run the same doctor on Windows, macOS, or Linux to see a fifteen-check readiness suite pass.
Controlled failure evidence: Watch the node line fail with a non-zero exit code before the restored run returns to fifteen passes.
Private delivery evidence: Show a closed issue, a Done project card, a merged pull request, and a v0.1.0 release containing your recording.
Secret Mission: Keep the same node line while making it enforce Node 24.

Are there any prerequisites?

You need a GitHub account. Step 1 checks every required tool before you install anything.

Before We Start

Before the hands-on work starts, lock in the customer outcome and required evidence. The finished private handover proves cross-platform machine readiness with a Go doctor that produces fifteen PASS lines, a 15 checks, 0 failed summary, a controlled Node failure, and an issue-to-release trail.

Check Tools and Copy the Project

A readiness doctor is only credible when the machine underneath it has been checked. Your untouched starting point also becomes evidence that later changes belong to you.

Installing before checking wastes customer time. Altering the supplied files before the baseline removes the proof you need later.

In this step, get ready to:

Check every required tool before installing anything.
Prepare the local model lane plus your GitHub identity.
Commit the supplied project unchanged to a private repository.

Keep the setup timeboxed

The plan gives this setup nine minutes. Your final README records the real elapsed time if missing tools push the setup beyond ten minutes.

Check every tool before installing

A version check reveals what the customer machine already has. Run every check before opening an installer.

macOS

Press Cmd+Space to open search.
Type Terminal into the search field.
Press Enter to open a fresh terminal.
Confirm the shell identifies zsh.

Windows

Press the Windows key to open search.
Type PowerShell 7 into the search field.
Press Enter to open a fresh terminal.
Confirm the terminal identifies PowerShell 7.

Linux

Press the system search key to open application search.
Type Terminal into the search field.
Press Enter to open a fresh terminal.
Confirm the shell identifies bash or zsh.

What are you checking?

Go runs the fixed doctor design.
Node provides the runtime checked by the controlled failure test.
Rust is part of the required customer toolchain.
Git records the untouched baseline.
GitHub CLI publishes the private handover.
go-task runs the supplied doctor tasks.
Ollama serves the local model without a metered API.
Docker or Podman supplies the single container engine.

Check the seven required commands by running this block:

go version
node --version
rustc --version
git --version
gh --version
task --version
ollama --version

What do these checks prove?

Each command asks one installed tool to identify its version. A missing command marks that tool for setup before any project work begins.

Node must report major version 24. The other checks must answer successfully.

The project needs exactly one running container engine. Pick the engine installed on the tested machine.

Docker

Start Docker through your operating system's application search.
Check the running Docker engine by running this command:

docker version

What does this check prove?

The command checks the selected Docker engine. A successful response proves the engine is available to the supplied doctor.

Podman

Start Podman through your operating system's application search.
Check the running Podman engine by running this command:

podman version

What does this check prove?

The command checks the selected Podman engine. A successful response proves the engine is available to the supplied doctor.

✔️ Every check answers with Node 24

Good. The existing toolchain is ready without unnecessary installation.

Continue to the local model checks below.

ⓧ Node is older than 24

Find the Node 24 section in the supplied docs/setup.md.
Use only the installation path given in that section.
Verify the installer with the checksum or signature specified there.
Open a fresh terminal after the installation finishes.
Repeat the Node version check by running:

node --version

What should this confirm?

The new terminal should report Node major version 24. This proves the supported release is active on your path.

ⓧ One or more commands are missing

Missing tools are expected on some customer machines. The supplied setup guide keeps each installation tied to a vendor-published integrity check.

Find each missing tool's section in the supplied docs/setup.md.
Use only the installation path given in that section.
Verify each installer with the checksum or signature specified there.
Avoid any installation script that you have not read.
Open a fresh terminal after each installation.
Repeat the matching version check in the fresh terminal.
Start your selected container engine before repeating its check.

Why verify installers?

OWASP A03:2025 Software Supply Chain Failures covers risks introduced while software is built or distributed. A checksum or signature gives you evidence that an installer matches the vendor's published artifact.

Still missing a command?

Confirm that you opened a new terminal after installation. An older terminal can keep the previous path.

Check that you used the section for your tested operating system in docs/setup.md.

Help me diagnose a tool that is still missing after I followed docs/setup.md.

Configure the local lane and identity

Local execution keeps every model request on the tested machine. The handover also needs an authenticated GitHub account plus a real Git identity.

Inspect the locally available Ollama models by running:

ollama list

What should the list contain?

The local model list must contain qwen3:8b. This is the only model used by the project.

Use only the qwen3:8b pull line from the supplied docs/setup.md if the model is missing.
Repeat the local model check by running:

ollama list

What does the second list prove?

You should now see qwen3:8b in the local list. The model is available without a cloud API key.

Apply OLLAMA_CONTEXT_LENGTH with the value 8192 by following the matching server procedure in docs/setup.md.
Handle DOCTOR_MODEL exactly as the matching operating system section specifies.
Run the local-lane confirmation from docs/setup.md.

The confirmation should show that the Ollama server uses the required context length. It should also show that the doctor resolves qwen3:8b through the documented model setting.

Check the current GitHub CLI authentication by running:

gh auth status

What does authentication status show?

The command displays the active GitHub account plus its authentication state. An authentication problem makes this check fail.

✔️ GitHub authentication succeeds

Your GitHub CLI session is ready to create the private repository.

Continue to the Git identity checks below.

ⓧ GitHub authentication is required

The login command starts an interactive authentication flow. Follow the prompts for your own GitHub account.

Start GitHub CLI authentication by running:

gh auth login

What does this command do?

GitHub CLI guides you through authenticating the terminal session. Keep credentials out of project files.

Confirm the completed authentication by running:

gh auth status

What should change?

The status check should now identify an active authenticated account. That account owns the private handover.

Check the global Git author name plus email by running:

git config --global user.name
git config --global user.email

Why does Git need this identity?

Git stores this author identity in your commits. Both commands must print your real configured values.

Use the matching configuration lines from docs/setup.md if either value is blank.
Repeat both identity checks by running:

git config --global user.name
git config --global user.email

What should the repeated checks show?

The first line should show your real author name. The second line should show your real author email.

Authentication or identity still failing?

Keep GitHub authentication separate from Git author identity. The CLI session proves account access while the Git settings label commits.

Help me diagnose my GitHub CLI or Git identity setup.

Copy and publish the untouched baseline

The first commit is your control sample. It must contain only the supplied artifacts with their original names plus contents.

Move the terminal to your Desktop by running this command:

cd ~/Desktop

Why start on the Desktop?

The home shortcut resolves to your user folder. Starting from its Desktop keeps machine-ready easy to find outside another repository.

Create machine-ready as a new repository on main by running:

mkdir machine-ready
cd machine-ready
git init
git branch -M main

What do these commands create?

The first command creates the machine-ready folder.
The second command moves your terminal into that folder.
The third command initializes its Git history.
The final command names the starting branch main.

Check the terminal prompt for the machine-ready folder.

You should see that your current terminal location ends with machine-ready. The repository is ready for the supplied baseline.

Folder already exists?

Stop if the existing folder contains unrelated work. Move that folder elsewhere before creating the clean baseline.

Help me create a clean machine-ready folder without deleting existing work.

Use your operating system's file manager to copy the supplied docs folder into machine-ready before any other artifact.
Inspect machine-ready/docs in the same file manager.

First copy checkpoint

You should see these five unchanged design documents:

docs/requirements.md.
docs/decisions.md.
docs/architecture.md.
docs/limits.md.
docs/setup.md.

Copy the supplied doctor folder into machine-ready.
Copy the supplied scripts folder into machine-ready.
Inspect both copied folders in your file manager.

Source and script checkpoint

The copied folders should preserve these exact paths:

doctor/go.mod.
doctor/main.go.
doctor/modelcheck.go.
scripts/mustfail.ps1.
scripts/mustfail.sh.

Copy the supplied Taskfile.yml, .gitattributes, plus README.md into machine-ready.
Inspect the top level of machine-ready in your file manager.

Top-level checkpoint

You should see all three top-level files with their original names. The eol=lf rule in .gitattributes keeps repository text normalized to LF.

Keep the baseline private

Do not add real keys or customer data. A private repository still needs clean credential hygiene.

The git commit command opens your configured editor for a message. Choose a real message that describes the untouched supplied baseline.

Stage the supplied artifacts plus create the initial commit by running:

git add .
git commit

What does this commit prove?

The first command stages the copied baseline. The second command records those supplied artifacts before any doctor changes.

Review the commit summary in your terminal.

You should see only the supplied project paths in the initial commit. No learner-authored source file should appear yet.

Commit blocked?

A missing author identity means the earlier Git configuration did not apply to this terminal. Repeat the identity checks before retrying the commit.

Help me diagnose why the initial Git commit is blocked.

✔️ Awesome, I've got everything!

Great. Your initial commit now preserves the supplied project before any implementation work.

ⓧ I'd like to double check the full code

Compare your committed tree with this complete baseline checklist. Every file must remain identical to the supplied copy.

.gitattributes is the exact supplied Git attributes file. It includes eol=lf.
README.md is the exact supplied README skeleton.
Taskfile.yml contains the exact supplied task definitions. These include doctor plus mustfail.
docs/architecture.md contains the exact supplied architecture.
docs/decisions.md contains the exact supplied decisions.
docs/limits.md contains the exact supplied limits.
docs/requirements.md contains the exact supplied requirements.
docs/setup.md contains the exact supplied setup guidance.
doctor/go.mod is the exact supplied Go module file.
doctor/main.go is the exact supplied baseline source. It contains the existing node check plus the check, output, plus runCmd behavior.
doctor/modelcheck.go is the exact supplied model source. It contains the getJSON, ollamaURL, plus chatModel behavior.
scripts/mustfail.ps1 is the exact supplied PowerShell must-fail script.
scripts/mustfail.sh is the exact supplied shell must-fail script.

Before you publish, do you expect the remote repository to contain anything beyond this single baseline commit?

Create the private GitHub repository plus push main by running:

gh repo create machine-ready --private --source=. --push

What does this command publish?

GitHub CLI creates machine-ready under your authenticated account. The private visibility flag protects the handover while the source plus push flags publish the current repository.

You should see the new repository URL after the command succeeds. Its main branch should contain the single untouched baseline commit.

Repository creation failed?

Repeat gh auth status if the command reports an authentication problem. Confirm that another repository named machine-ready does not already exist under your account.

Help me diagnose why the private repository was not created or pushed.

Your machine is checked plus your untouched baseline is private on GitHub. Next, you will connect the acceptance criteria to Issue 1 before running the incomplete twelve-line doctor.

Open the Ticket and Run the Baseline

Your private machine-ready repository now contains the untouched supplied project on GitHub. Every required tool has already answered on your tested operating system.

A high-performing forward-deployed engineer links the acceptance criteria to a visible baseline before changing code. You will tie the six criteria to Issue 1 before recording how the supplied doctor currently behaves.

In this step, get ready to:

Create Issue 1 from the supplied acceptance criteria before moving its Project card to In Progress.
Create the doctor branch before tracing the supplied Go files in Cursor.
Run the unchanged doctor before recording its visible baseline.

Create the issue and Project

An issue gives the six acceptance criteria one visible home. A linked GitHub Project shows that the work has moved from a requirement into active delivery.

Use your text editor to open docs/requirements.md inside the machine-ready repository.
Copy the six acceptance criteria exactly as supplied.
Return to the terminal from the previous step.
Start creating Issue 1 by running this command:

gh issue create --title "Machine ready: the doctor"

What does this command do?

The gh command creates an issue in the private repository connected to your current folder.
The --title flag fixes the issue title as Machine ready: the doctor.
GitHub CLI prompts you for the issue body because the command does not supply one.

Paste the six copied acceptance criteria into the body prompt.
Submit the issue from the interactive prompt.
Confirm that the terminal prints a URL for Issue 1.

Issue creation not completing?

Confirm that your terminal is inside the local machine-ready repository. Authentication or repository-location problems can prevent GitHub CLI from choosing the correct private repository.

If the prompt is still waiting, make sure you submitted the issue body after pasting all six criteria.

Help me diagnose why GitHub CLI cannot create Issue 1 in my private machine-ready repository.

Open the Projects area under your GitHub account in a browser.
Create one private Project for the machine-ready handover.
Link the private Project to the machine-ready repository.
Add Issue 1 to the linked Project.
Set the Issue 1 card status to In Progress.
Confirm that the Project shows Issue 1 in In Progress.

Create the branch and trace the supplied doctor

A Git branch separates the upcoming doctor work from the untouched baseline on main. Creating the branch changes your working context without changing any supplied file.

Create the doctor branch before switching to it by running this command:

git switch -c doctor

What does this command do?

The switch command changes the active branch. The -c option creates doctor before switching to it.

Confirm that the terminal reports a successful switch to the new doctor branch.

Branch already exists?

A branch-creation failure can mean that doctor already exists locally. Confirm that you did not create it during an earlier attempt before choosing how to continue.

Help me determine why I cannot create and switch to the doctor branch.

The supplied Go files already contain the central doctor behavior. Cursor can help you trace that design before the first baseline run.

Press Cmd+Space on macOS. Press the Windows key on Windows. Open your application launcher on Linux.
Type Cursor into the search field.
Press Enter to open Cursor.
Use Cursor's folder picker to select the local machine-ready repository.

Keep this explanation read-only

The agent's job is to explain the supplied architecture before you run it. Keep doctor/settings.go absent so the baseline remains valid.

Start a new agent conversation in Cursor.
Ask the agent to explain doctor/main.go part by part without editing any file.
Ask the agent for one trace covering these symbols: check, settings, output, runCmd.
Ask the agent to explain doctor/modelcheck.go part by part without editing any file.
Ask the agent for one trace covering these elements: getJSON, ollamaURL, chatModel, the existing model checks, the failure behavior.
Reject any suggestion that creates doctor/settings.go.

Run the unchanged baseline

The unchanged doctor is your control run. Its output shows what the supplied architecture already proves before learner-owned checks enter the package.

Switch back to the terminal from earlier.

Before you run it, consider whether the supplied baseline already covers every readiness requirement.

Reveal the unchanged baseline by running this command:

task doctor

What does this command do?

The task executable reads Taskfile.yml before running its supplied doctor task. This gives you the project's intended entry point without changing the Go files.

You will see twelve check lines. This shortfall is intentional because the three learner-owned checks are still absent.

Count the baseline output to confirm that it contains exactly twelve check lines.
Confirm in Cursor that doctor/settings.go does not exist.
Keep the complete baseline output visible in the terminal.

Baseline not reaching twelve lines?

Confirm that the terminal is inside machine-ready on the doctor branch. Running from another folder can prevent task from finding the supplied task definition.

Confirm that Ollama is running with qwen3:8b available locally. The supplied model checks need the configured local lane to answer.

Help me troubleshoot why the unchanged doctor baseline does not print twelve check lines.

You have captured the exact gap the ticket needs to close. The branch now has a trustworthy starting point without altering the supplied architecture.

Next, you will add the three customer-readiness checks before proving that all fifteen pass.

Add Readiness Checks

The twelve-line baseline proves that the supplied doctor runs on your machine. It also makes the missing customer-readiness coverage visible.

The supplied central check list must remain unchanged. Go package initialization lets a new file register the three checks before the doctor runs.

In this step, get ready to:

Create doctor/settings.go with exactly three learner-owned readiness checks.
Prove that all fifteen checks pass with exit code zero.
Commit only doctor/settings.go as the code change.

Create the registration file

Every Go file in the same package participates in package initialization. An init function in a new file can extend the doctor without changing doctor/main.go.

Switch back to Cursor from the previous step.
Select the doctor folder in the file tree.
Use the file tree's new-file control to create settings.go inside the doctor folder.

You'll see settings.go beside main.go plus modelcheck.go. The two supplied files stay untouched.

Why use init registration?

Package initialization runs before normal execution. Your new file can register its checks through the existing settings value before the doctor processes that list.

This preserves the supplied architecture. It also isolates the learner-owned checks in one reviewable file.

Implement the three checks

The three checks turn the acceptance criteria into repeatable machine evidence. Each check needs a stable name plus a useful result through the existing check behavior.

Match the package declaration used by the two supplied Go files.
Add only the imports required by your implementation.
Define an init function that registers exactly three checks through the existing settings value.
Implement git LF endings so it verifies that ../.gitattributes contains eol=lf. Use runCmd to call git with ls-files plus --eol. Return a failure if the result contains i/crlf.
Implement ollama port so it calls getJSON(ollamaURL()+"/api/version"). Report the returned version in the successful result.
Implement github signed in so runCmd calls gh with auth plus status. Report the first output line in the successful result.
Leave the supplied central check list in doctor/main.go unchanged.
Save doctor/settings.go.

Before you run the doctor, which three new lines do you expect to join the twelve-line baseline?

Test the registration plus all three implementations by running:

task doctor

What does this command prove?

The supplied task builds the doctor from every Go file in the doctor folder. Package initialization registers your checks before the existing execution loop begins.

A successful run proves that your file compiles. It also proves that the three checks satisfy their live machine requirements.

You'll see fifteen check lines. Every line shows PASS.

The summary reads 15 checks, 0 failed. The process returns exit code zero.

You have closed the baseline gap with machine-verifiable readiness evidence.

Doctor not fully passing?

If only twelve check lines appear, confirm that doctor/settings.go is saved. Confirm that its init function registers through the existing settings value.
If git LF endings fails, recheck the path to ../.gitattributes. Recheck the search for i/crlf in the EOL inspection result.
If an environment check fails, return to the successful local model or authentication check from setup. Use the detail returned by your check to identify which prerequisite changed.

Help me debug my three Go readiness checks without writing doctor/settings.go for me.

Commit the readiness checks

A narrow commit gives reviewers one focused change to inspect. This commit should contain only the learner-authored readiness file.

Stage only doctor/settings.go by running:

git add doctor/settings.go

What does this command do?

This Git command selects doctor/settings.go for the next commit. The supplied files remain outside the commit.

Expect the next command to open your configured editor for a commit message.
Start the commit by running:

git commit

What happens next?

Git opens your configured editor because the command does not supply a message. Closing the editor with a non-empty message creates the commit.

Enter a real commit message that describes the three readiness checks.
Save the commit message.
Close the editor.

You'll see Git report a new commit. Its change summary covers doctor/settings.go.

That is the implementation secured: the doctor branch now carries one focused commit with fifteen passing checks.

Commit editor still open?

Make sure the message contains real text. Save the file through your editor before closing its window.

Help me finish the Git commit editor flow.

Your doctor now proves the complete readiness baseline. Next, you will force a controlled Node failure to show that the same doctor also catches a broken requirement.

Prove Failure and Complete the README

Your three new readiness checks have turned the supplied baseline into a fifteen-check doctor. Every line now passes, so the healthy path is proven.

Customer trust also depends on negative testing. You will prove that the doctor rejects a controlled failure in the existing node check with a non-zero exit code.

The finished README.md preserves the failure proof beside the restored passing run. That evidence gives the next engineer a handover they can verify.

In this step, get ready to:

Test the doctor against a controlled bad condition.
Capture the passing proof from a restored normal run.
Commit a completed README handover.

Run the supplied negative test

The supplied must-fail harness gives the doctor a known-bad condition. Its job is to test the failure contract as one unit.

Before you run the negative test, do you think the harness will prove both the failing check and the exit behavior?

Run the supplied negative test in the current terminal with this command:

task mustfail

What Did the Negative Test Prove?

The existing node line reports FAIL.
The doctor returns a non-zero exit code.
The harness ends with MUST-FAIL OK: the node line failed and the exit code was not zero.

That controlled failure is valuable proof. Your doctor now demonstrates that it can reject a machine that does not meet the supplied condition.

Capturing every line from terminal scrollback can be fiddly. Keep the first line through the final harness result together as one evidence block.

Return to Cursor.
Select README.md from the Explorer sidebar.
Find the supplied section for the must-fail evidence.
Switch back to the same terminal.
Select the complete negative-test output through the final MUST-FAIL OK: the node line failed and the exit code was not zero.
Copy the selected output.
Return to Cursor.
Paste the output into the designated must-fail section.

Why Keep the Complete Output?

The failing check proves detection. The non-zero exit behavior proves that automation can treat the machine as unready.

The final harness line connects both results in one reproducible test. Keeping the entire run preserves that chain of evidence.

Save README.md.

Missing the Must-Fail Result?

Confirm Taskfile.yml still contains the supplied mustfail task.
Confirm scripts/mustfail.ps1 still matches the supplied PowerShell script.
Confirm scripts/mustfail.sh still matches the supplied shell script.

Help me diagnose why the supplied must-fail harness did not produce its required final result.

Restore the passing proof

A negative test only earns trust when the original healthy state still passes afterward. Run the normal doctor again in the same terminal to rule out a lingering test condition.

Before you run the normal doctor, do you expect every check to recover?

Restore the normal readiness proof by running this command in the same terminal:

task doctor

What Should You See?

All fifteen check lines report PASS.
The summary reads 15 checks, 0 failed.
The doctor process exits with code zero.

You have now proved both sides of the contract. The doctor rejects the controlled failure before returning to fifteen clean passes.

Select the complete restored doctor output.
Copy the selected output.
Return to the open README.md file in Cursor.
Paste the output into the supplied restored-run section.
Save README.md.

Does the Restored Run Still Fail?

Read the name of each failing line to identify the readiness condition that did not recover.
Restore the local service or setting named by that line.
Repeat the normal doctor run in the same terminal.

Help me understand why my normal doctor run still fails after the controlled must-fail test.

Complete and commit the README

The two captured runs prove the doctor's behavior. The remaining README fields explain where the proof was collected and how another engineer can reproduce it.

Enter the operating system you actually tested in the supplied field of the open README.md file.
Enter your real elapsed project minutes in the supplied timing field.

You should now see your tested environment beside the real time the work took.

Mark every operating system you did not run as reasoned, not tested.
Complete the existing clean-clone quickstart so a stranger can run the doctor from a clean clone.

The README should now distinguish direct evidence from cross-platform reasoning. Its quickstart should lead a new engineer to the same doctor proof.

Confirm the must-fail output contains the FAIL node line.
Confirm the must-fail output ends with MUST-FAIL OK: the node line failed and the exit code was not zero.
Confirm the restored output contains fifteen PASS check lines.
Confirm the restored output reaches 15 checks, 0 failed.

Keep the Supplied Talk Track Intact

The supplied four-point talk track explains the project's existing decisions. Leaving those points unchanged keeps the written handover aligned with the recording you make later.

Switch to docs/decisions.md in the Explorer sidebar.
Confirm each decision names the alternative it beat.
Confirm each decision states what would reverse it.
Return to README.md.
Confirm the supplied four-point talk track remains unchanged.
Save README.md.

The completed README is now the engagement's evidence package. Git can record it as a focused handover change.

Stage the completed README by running this command in the terminal:

git add README.md

What Does This Command Do?

The git add command stages only README.md for the next commit. The supplied source files remain outside this handover commit.

Before you create the commit, do you expect its file summary to name only README.md?

The commit command may open your configured message editor. A specific message makes the evidence easy to identify in the branch history.

Commit the staged README by running this command:

git commit

Finish the Commit Message

The command records the staged README as a new snapshot on the doctor branch. Your configured editor may request the commit message before the command completes.

Enter a real message that describes the failure proof plus the README handover if your configured editor opens.
Save the commit message.
Close the configured editor.

When the command completes, the terminal confirms a new commit on doctor with README.md in its file summary.

Commit Did Not Complete?

Confirm README.md was saved before you staged it.
Complete the message in your configured editor if the terminal is still waiting.
Close the editor after saving the message.

Help me complete the README handover commit without changing any supplied source files.

Your controlled failure and restored fifteen-pass proof are now committed. Next, you will turn the doctor branch into a reviewed private release.

Merge, Release, and Report

The local handover now contains the passing doctor proof. It also contains the controlled failure proof in README.md.

Customer work becomes complete when GitHub holds the reviewed change. The ticket must close through the merge. The recording must ship with a release. Your engagement lead also needs an honest status.

In this step, get ready to:

Push the doctor branch and create the pull request from the supplied template.
Merge the pull request before closing the delivery trail in the linked GitHub Project.
Publish release v0.1.0 with the recording before reporting the final status.

Move the handover into review

The commits on your local doctor branch need to reach the private repository before GitHub can review them. The pull request connects those commits to Issue 1.

Push the committed doctor branch to the private repository by running this command:

git push -u origin doctor

What does this command do?

This sends the committed branch to the private repository. GitHub can now use it as the source of a pull request.

You should see a successful push with no rejected updates.

Push rejected?

Confirm that the terminal is still inside the verified machine-ready repository.
Confirm that the current branch is doctor.
Repeat the GitHub authentication status check from setup if authentication has expired.

Help me diagnose the rejected push.

GitHub CLI creates the pull request interactively. It prompts for the title before letting you confirm the body.

Enter a concise title that names the doctor readiness checks when prompted.
Use the supplied pull request template for the body when prompted.
Confirm that the final line of the body is Closes #1.
Create the pull request by running this command:

gh pr create

How does the issue link work?

The supplied template keeps the review evidence consistent. The final Closes #1 line connects the merge to Issue 1.

Follow the pull request URL printed in the terminal.
Confirm that the pull request uses the doctor branch.
Confirm that the pull request targets main.
Confirm that the body ends with Closes #1.

You should see the committed doctor checks and completed handover ready for review.

Pull request missing the template?

Confirm that you created the pull request in the private machine-ready repository.
Copy the supplied pull request description into the body if the interactive flow did not load it.
Restore Closes #1 as the final line before merging.

Help me correct the pull request without changing the commits.

Complete the review trail

Merging completes the review. The private repository retains the commit history if you need to inspect the change later.

The closing line in the pull request gives the merge a second job. It closes Issue 1 as part of the same delivery event.

The next action changes main. The repository history keeps a record of the accepted change.

Merge the current pull request by running this command:

gh pr merge

What happens after the merge?

This moves the reviewed branch changes into main. The closing line connects that completed merge to Issue 1.

Follow any terminal prompts using the merge method accepted for this private repository.
Return to the pull request page from earlier.
Confirm that the pull request is merged.
Return to Issue 1 in the private repository.
Confirm that Issue 1 is closed.
Return to the linked private GitHub Project.
Move the Issue 1 card to Done.

You should now see a merged pull request. Issue 1 should be closed. Its Project card should be in Done.

Issue 1 still open?

Confirm that the pull request was merged successfully.
Confirm that Closes #1 remains in the pull request body.
Confirm that Issue 1 belongs to the same private repository.

Help me trace why the merge did not close Issue 1.

Deliver the final evidence

The release turns the repository evidence into a named handover milestone. The recording lets another engineer hear the reasoning behind the supplied decisions.

Switch back to the completed README.md from earlier.
Rehearse the unchanged supplied four-point talk track.
Start a two-minute timer on your phone.
Record the supplied four-point talk track on your phone.
Stop the recording within two minutes.

Your recording now explains the decisions behind the evidence. That makes the handover usable without a live walkthrough.

Select Releases in the private GitHub repository from earlier.
Start a release from the repository's Releases page.
Create the tag v0.1.0 in the release form.
Attach the two-minute recording to the release.
Publish the release.

You should see release v0.1.0 published with the recording available as an attachment.

Why release the recording?

The tag gives this completed handover a fixed version. The attached recording keeps the technical proof beside the reasoning that supports it.

The engagement lead needs the current state without having to reconstruct it from the repository. Your report should separate proven passes from any remaining failure.

Include the restored doctor output from README.md in the engagement lead status.
List the checks that passed.
State that the restored run contains no remaining FAIL lines.
Give the clearance time as already cleared by the restored run.
Send the completed status to the engagement lead.

Before you verify the handover, do you expect every delivery surface to show the same completed state?

Check the pull request page for the merged state.
Check Issue 1 for the closed state.
Check the linked private Project for the Done card.
Check release v0.1.0 for the attached recording.
Check the sent engagement lead status for the output and clearance details.

You should see the doctor changes merged into main. The pull request is merged. Issue 1 is closed. Its card is in Done. Release v0.1.0 contains the recording.

That completes the handover. Another engineer can now inspect the proof and hear why the implementation decisions were made.

Secret mission

Enforce the Node 24 Minimum

Your doctor currently proves that Node is present. Strengthen the existing node line so it validates the required major version without breaking the failure harness.

Clean Up Your Resources

Your cleanup choice is to keep the handover available, pause its local processes, or delete its resources. This project costs 0.00 USD because no card or metered service was used.

Resources you used:

The local handover folder named machine-ready, including the doctor, supplied files, and completed README.md evidence.
The private GitHub repository named machine-ready, including the closed issue, merged pull request, release v0.1.0, and recording.
The private GitHub Project containing the completed Issue 1 card in Done.
The local Ollama model named qwen3:8b.

Keep everything running

Keeping the handover requires no action. Choose this option when you want the released evidence ready for another demonstration.

Your local machine-ready folder remains available for running the doctor.
Your private repository continues to preserve the closed issue, merged pull request, release, and recording.
Your private Project continues to show the completed delivery card in Done.
Your local qwen3:8b model remains ready for the Local lane.
These resources remain available without ongoing metered costs.

Pause - I'll come back to this later

Pausing preserves every handover artifact while stopping the local processes used during the demonstration. Your files and private delivery evidence remain available when you return.

Use the matching Ollama shutdown line in docs/setup.md to stop the local model server.
Use the matching shutdown line in docs/setup.md to stop the container engine you selected in Step 1.
Keep the local machine-ready folder for later doctor runs.
Keep the private repository as the released handover.
Keep the private Project as the issue-to-release record.

Delete - I don't want to use this again

Deletion is permanent. This option fits when the handover and its released evidence are no longer required.

Use the cleanup section in docs/setup.md to locate the exact qwen3:8b removal line.
Run the qwen3:8b removal line exactly as supplied.
Repeat the local model-list check from Step 1.

You should no longer see qwen3:8b in the local model list.

Use the cleanup section in docs/setup.md to run the exact Ollama shutdown line.
Use the cleanup section in docs/setup.md to run the exact shutdown line for your selected container engine.
Select your operating system below to remove the local machine-ready folder.

macOS

Use Finder to locate the machine-ready folder where you created it.
Move the machine-ready folder to Trash.
Empty Trash to remove the folder permanently.

Finder should no longer show the machine-ready folder in its original location.

Windows

Use File Explorer to locate the machine-ready folder where you created it.
Move the machine-ready folder to the Recycle Bin.
Empty the Recycle Bin to remove the folder permanently.

File Explorer should no longer show the machine-ready folder in its original location.

Linux

Use your file manager to locate the machine-ready folder where you created it.
Move the machine-ready folder to your system trash.
Empty your system trash to remove the folder permanently.

Your file manager should no longer show the machine-ready folder in its original location.

Delete the private machine-ready repository from its repository settings on GitHub.
Complete the repository deletion confirmation.
Return to your GitHub repository list to confirm machine-ready is absent.
Delete the linked private GitHub Project from its project settings.
Complete the Project deletion confirmation.
Return to your GitHub Projects list to confirm the private Project is absent.

Deleting the repository also removes its closed issue, merged pull request, release, recording, and remote handover evidence.

Nice Work!

You did it! You shipped a private machine-readiness handover that gives another engineer concrete proof.

What you learned:

Built a cross-platform Go readiness doctor that proves a customer machine is ready. The successful run prints fifteen PASS check lines. Its summary reads 15 checks, 0 failed. The process finishes with an exit code of zero. The local qwen3:8b lane runs through Ollama without a metered service.
Proved the doctor can catch a controlled failure through negative testing. The forced Node check returns non-zero. The harness prints MUST-FAIL OK: the node line failed and the exit code was not zero. The restored run passes again. README.md preserves both complete outputs with the tested operating system. It also records the real minutes.
Delivered a private issue-to-release handover. The merged pull request closes Issue 1 on GitHub. The linked Project card is in Done. Release v0.1.0 includes the two-minute recording. The engagement lead has the doctor output plus an honest clearance status.
Secret Mission: Strengthened the existing Node check so Node 24 or newer passes. Malformed or older version output produces an explanatory FAIL without a crash. The check name stays the same. The forced-failure contract remains intact.

Ready to quiz yourself?