DEV Community: Quinn Zhu

Delete the Scratch Worktree Before Your First Real PR

Quinn Zhu — Thu, 24 Sep 2026 21:25:58 +0000

Your first agent edit belongs in a worktree you can delete. You practice that deletion before any real pull request. Shared branches stay clean until the drill feels boring.

Start with the delete path

You joined this repo to ship a small first change. An agent can outrun your review during hour one. Containment comes before you write any clever prompt.

A deleted scratch tree is your real proof. A green demo on a shared branch is not proof. You collect the delete proof before you collect speed.

Build three cards before any model runs

You leave hour one with three plain text cards. Keep them in your private notes for now. You can rebuild every card on a new laptop.

The worktree card names the path and the branch. The smoke card names one command from the docs. The delete card names the exact cleanup commands.

Step 1: Create a disposable worktree

Do not point an agent at your primary checkout. Your primary checkout is for reading and resets. A second worktree keeps experiments easy to discard.

Treat the block below as an unexecuted example. Replace the remote and branch names with yours. Stop if those names do not match the docs.

git fetch origin
git worktree add -b scratch/hour-one ../repo-scratch origin/main
cd ../repo-scratch
git status --short --branch

Run the status line and read every unexpected file. Unexpected files mean you are in the wrong tree. Leave that tree before you continue the drill.

Step 2: Write the smoke card

Pick one command the repository docs already show. Do not invent a new test suite on day one. You are checking the tree, not redesigning CI.

# smoke-card.sh — proposal, not a recorded run
set -eu
printf 'worktree=%s\n' "$(pwd)"
printf 'branch=%s\n' "$(git branch --show-current)"
# Replace the next line with the documented smoke command.
# Placeholder only. Do not treat this as a pass.
git status --short --branch

Save that script beside your notes, not in main. A placeholder comment is not a passing test. You only mark the card done after you run it.

Step 3: Practice deletion before any agent

The delete drill is the point of hour one. You remove the branch and the worktree on purpose. If cleanup fails, you are not ready for an agent.

cd /path/to/primary-checkout
git worktree remove --force ../repo-scratch
git branch -D scratch/hour-one
git worktree list
git branch --list 'scratch/*'

Treat those commands as a proposal you adapt. Read each flag before you paste it locally. Force removal is only for this scratch tree.

After cleanup, the scratch path should be gone. The scratch branch should be gone as well. Your primary checkout should still match the remote.

If the primary checkout changed, stop the drill. Restore it with the team's documented reset steps. Do not invent a reset you cannot explain later.

Step 4: Bound the first agent task

Only now do you consider an agent for a task. Recreate the scratch worktree with the same commands. Give the agent one file and one expected check.

Goal: adjust the greeting string in internal/hello/hello.go
Non-goals: no dependency changes, no CI edits, no lockfiles
Check: run the smoke command written on your smoke card
Stop: if the diff touches more than that one file

That card is the whole contract for session one. If the agent asks for more files, you refuse. Wider context can wait until your second week.

Where a free server fits

Some new juniors cannot install every local dependency. A free server option can host that first scratch task. You still keep the same narrow card and the same stop rule.

MonkeyCode is an open source project with free model access. Disclosure: This article was prepared as part of MonkeyCode's product outreach. It also offers a free server option you can try.

Confirm current terms in the project docs before relying on them. Do not assume a fixed quota, model list, or duration. Those details change, and this article does not freeze them.

If the docs disagree with a blog post, trust the docs. Use the free server as a sandbox, not as your main checkout. Copy the same task card into that remote session.

Still run the delete drill on anything you clone locally. Free model access does not replace your own review. You still reject edits that break the task card.

Step 5: Open a tiny first pull request

After one clean scratch session, branch from main again. Use a short branch name tied to the ticket. Keep the patch inside the same one-file limit.

git fetch origin
git switch -c junior/hello-greeting origin/main
# Apply only the one-file change you already reviewed.
git diff --stat origin/main
git push -u origin HEAD

Label this block as a workflow sketch, not a log. Push only after the smoke card passes locally. If it fails, return to the scratch tree and stop.

Write the pull request body in your own words. State the file, the check, and the rollback command. Do not paste an agent summary you did not verify.

Step 6: Rehearse rollback without drama

Your first rollback practice stays on the scratch branch. You already deleted that branch once in step three. Repeat the cleanup so the commands feel familiar.

On the real pull request, rollback means revert or close. Use the command your team documents for that case. If you cannot explain it, do not merge the change.

Close the pull request if the diff grew past one file. A closed request is cheaper than a confused merge. You can open a smaller request the same day.

Use this decision table

Choose the workspace before you choose the model. The table below is a rule of thumb, not a benchmark. It records judgment, not measured speed or cost.

Situation	Use this	Do not use this
Local docs and tools already work	Scratch worktree for edits	An agent on the shared branch
Dependencies fail on your laptop	Free server sandbox plus the same task card	A guessed local install guide
You cannot explain the cleanup	No agent and no pull request	A temporary commit on main
Diff touches files outside the card	Stop and shrink the task	A follow-up prompt that widens scope

Read the row that matches your actual blocker. Do not mix a broken laptop with a shared branch. A sandbox helps only when the task card stays narrow.

Limitations you should say out loud

This drill does not teach the whole repository. One file is a teaching limit, not a team law. Later work will need a wider review plan.

Worktrees fail when local repository policy forbids them. Some repos use sparse checkouts or large generated files. Follow local policy when it conflicts with this sketch.

A free server may be unavailable, slow, or restricted. This article states no hardware size and no uptime promise. If access fails, finish the delete drill on your laptop.

The script examples were not executed for this draft. Paths, flags, and smoke commands will differ by repo. You must adapt them before you trust the output.

Who should not use this approach

Skip this if you already own the release branch. Skip it if your mentor assigned a paired review instead. Skip it if policy bans agents on this codebase.

Staff engineers debugging production need a different loop. They should not shrink an incident into a one-file drill. Juniors on call should ask a human before any edit.

Do not use a free server for secrets or customer data. Do not upload environment files to any hosted agent. If a file might be sensitive, leave it out.

What you do in the next ten minutes

Create the scratch worktree and run the status command. Write the three cards before you open a model chat. Delete the worktree once, then decide if an agent helps.

If you try MonkeyCode, start from its current free-access docs. Paste the same task card, then read every changed line. Keep the real pull request for the change you can explain.

Record a Green Local Boot Before Agent Work Starts

Quinn Zhu — Wed, 23 Sep 2026 17:14:35 +0000

You must record one green local boot first.
Keep the agent closed until that boot exists.

Your first hour on a new repo is reproduction.
Code generation waits until the app actually starts.

An agent that never booted the service will guess.
Those guesses turn into noisy diffs and broken PRs.
You then spend review time explaining startup failures.

The failure this drill blocks

Juniors often open an agent before anything runs locally.
The agent patches files while the app never started.
You cannot split product bugs from setup bugs.

That mix is expensive on your first day.
Reviewers then cannot reproduce the agent's claim.
You also lack a clean baseline for a later revert.

What you pin before any agent session

Pin four facts before the first generated edit.
Write them in files the agent does not own.

Copy the exact boot command from current docs.
Name env files, and never copy secret values.
Record the port and health path you expect.
Save a timestamped log from one successful boot.

Do not pin passwords, tokens, or production hosts.
Pin commands, file names, and local health checks only.

Step 1: Freeze git state on a clean clone

Start from the default branch with a fast-forward pull.
Record HEAD and status before any tool edits files.

mkdir -p .agent/boot
git switch main
git pull --ff-only
git rev-parse HEAD > .agent/boot/head.sha
git status --short > .agent/boot/git-status.before.txt

Keep .agent/boot/ out of the product commit when needed.
Add that path to a personal ignore file if policy requires it.

echo '.agent/' >> .git/info/exclude

Step 2: Copy the documented boot command

Do not invent a start command from memory or chat.
Copy it from README, Makefile, or package scripts.

# Label: example only. Replace with your repo command.
printf '%s\n' 'make dev' > .agent/boot/command.txt
printf '%s\n' 'local API via make dev' > .agent/boot/why.txt

If docs list several commands, pick one local service.
Write that choice in the one-line why.txt note.

Search the repo for the same command before you trust it.

grep -nR --include='Makefile' --include='README*' --include='package.json' \
  -e 'make dev' -e '"dev"' -e 'compose up' . | head

A command that appears in two docs is safer than folklore.
A command that appears nowhere is not ready for an agent.

Step 3: Name env files without dumping secrets

List templates and local env filenames only.
Never redirect live secret values into the boot folder.

ls -1 .env* env.example .env.sample 2>/dev/null \
  > .agent/boot/env-files.txt || true

Print required key names from the example file.
Skip values so the snapshot stays safe to share.

# Label: example. Point this at your example env file.
awk -F= '/^[A-Za-z_][A-Za-z0-9_]*=/ {print $1}' .env.example \
  > .agent/boot/env-keys.txt

Confirm each named key exists in your private local file.
Missing keys are a hand-debug job, not an agent job.

# Label: example. Do not commit the private env file.
cut -d= -f1 .env | grep -v '^#' | sort > /tmp/local-env-keys.txt
sort .agent/boot/env-keys.txt > /tmp/required-env-keys.txt
comm -23 /tmp/required-env-keys.txt /tmp/local-env-keys.txt

Any line from comm means you stop here.
Fill the local env yourself, then rerun the key check.

Step 4: Run boot with a hard timeout

Use a timeout so a hang cannot consume the whole hour.
Capture stdout, stderr, and the numeric exit code.

STAMP=$(date -u +%Y%m%dT%H%M%SZ)
CMD=$(cat .agent/boot/command.txt)
timeout 90s bash -lc "$CMD" \
  > ".agent/boot/boot.$STAMP.stdout.log" \
  2> ".agent/boot/boot.$STAMP.stderr.log"
echo $? > ".agent/boot/boot.$STAMP.exit"
printf '%s\n' "$STAMP" > .agent/boot/last.stamp

Ninety seconds is a starting budget, not a law.
Increase it only when the README states a slower boot.

First compiles and image pulls often miss that window.
Run one manual warm boot before you start the clock.
Then pin the second boot as the golden log.

Step 5: Prove health, then snapshot the proof

Hit the local health route from the same docs.
Save the status code and a short body clip.

# Label: example. Replace port and path from README.
curl -sS -o .agent/boot/health.body \
  -w '%{http_code}\n' \
  http://127.0.0.1:3000/health \
  > .agent/boot/health.status
head -c 200 .agent/boot/health.body \
  > .agent/boot/health.body.clip

A 200 is not enough by itself.
Confirm the body matches the documented JSON shape.

# Label: example. Change the key to match your docs.
grep -q '"status":"ok"' .agent/boot/health.body
echo $? > .agent/boot/health.shape.exit

Hash the logs so later drift is visible.
Do not treat the hash as the only merge gate.

shasum -a 256 .agent/boot/boot.*.log \
  .agent/boot/health.status \
  .agent/boot/health.body.clip \
  > .agent/boot/boot.sha256

Step 6: Stop the process you started

Leave the machine as you found it.
Do not gift the agent a dirty port or stale child.

# Label: example for a make-driven process group.
pkill -f 'make dev' || true

Prefer the project's own stop target when it exists.
Record that stop command beside the boot command.

printf '%s\n' 'make stop' > .agent/boot/stop.txt

Common boot failures you debug by hand

Read the stderr log before you blame application code.
Most first-hour failures are environment, not product logic.

Missing .env keys show up as immediate crashes.
Wrong language runtime versions break module imports.
Occupied ports look like random connection refused errors.
A stopped local database blocks every health request.
Stale README commands start the wrong workspace package.

# Port collision check. Replace 3000 with the documented port.
lsof -nP -iTCP:3000 -sTCP:LISTEN || true

If the port is busy, identify the owner process first.
Do not kill random processes because an agent suggested it.

Decision table: may the agent start?

Use this table as a hard gate, not a vibe check.
Any Stop row means you stay in manual setup mode.

Signal	Proceed	Stop
Boot exit code is `0`	Yes	—
Health HTTP status is `200`	Yes	—
Health body matches docs	Yes	—
Required env keys are missing	—	Yes
Boot hit the timeout	—	Yes
Documented port is already in use	—	Yes
Secrets printed inside the boot log	—	Yes, scrub, retry
README command was not found in repo	—	Yes

If a Stop cell matches, you debug without the agent.
The model does not get a turn until boot is green.

After boot is green: one narrow agent pass

Give the agent the ticket and the boot file names.
Forbid edits under .agent/boot/ and any secret paths.

Tell it to keep the same boot command unchanged.
Tell it to fail if health no longer returns 200.

# Label: prompt template, not an executed script.
Ticket: <id>
Boot command file: .agent/boot/command.txt
Health: GET http://127.0.0.1:3000/health must stay 200
Do not edit .agent/boot/**
Do not edit .env, credentials, or deploy manifests
After your patch I will rerun the same boot command

Re-run the same timeout command after the diff.
Compare health status before you compare full logs.

timeout 90s bash -lc "$(cat .agent/boot/command.txt)" \
  > /tmp/boot.after.stdout.log \
  2> /tmp/boot.after.stderr.log
echo $? > /tmp/boot.after.exit
curl -sS -o /tmp/health.after.body \
  -w '%{http_code}\n' \
  http://127.0.0.1:3000/health \
  > /tmp/health.after.status
diff -u .agent/boot/health.status /tmp/health.after.status
diff -u .agent/boot/boot.*.exit /tmp/boot.after.exit

A changed health code blocks the pull request.
A new stack trace in stderr needs your own read.
You explain that delta before you request review.

If health fails, revert the agent branch first.
Do not stack extra prompts on a service that will not boot.

git switch main
git branch -D agent/ticket-id || true

Where a free agent lane fits

Some teams lack spare paid seats on day one.
You still need a model for one narrow patch draft.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option.
You can run this boot-first drill there without a paid seat.
The product does not replace your health check or revert.

Use it only after the boot log is already green.
Paste the boot command and the health contract only.
Do not paste secret values into the prompt or chat.

If you want a free lane for this drill, that option exists.
Keep the first PR small enough that you can still revert it.

Limitations

This workflow assumes a bootable local application.
Monorepos with remote-only services will not boot cleanly.
You then pin a narrower contract, such as unit tests.

Log hashes drift when timestamps fill stdout lines.
Do not treat hash equality as the only merge gate.
Health status and exit code stay the primary gates.

Timeouts misfire on cold compiles and image pulls.
Warm the toolchain once before you pin the golden log.
Otherwise you will reject healthy but slow first boots.

Agents can still break migrations and seed scripts.
This method does not prove database shape or fixtures.
Add a seed check when your ticket touches storage.

Who should not use this

Skip this if you cannot run the service locally.
Skip this if policy forbids local secrets on your laptop.
Skip this if CI already owns a green compose healthcheck.

Staff on well-paved repos may already have this ritual.
Do not add a parallel folder that duplicates Makefile targets.
Prefer the team's script when it already snapshots boot.

Juniors on locked-down laptops should ask for a devcontainer.
Do not spend six hours on Docker instead of reading code.
The point is a baseline, not a perfect local factory.

Close

Your first agent PR needs a boot you can repeat.
Pin the command, the health code, and the log.
Then let the model touch a narrow slice of code.

If boot breaks after the diff, you stop immediately.
You revert before you request review from anyone.
That is the whole first-hour job on a new repo.

Pin CI's Test Command Before Your First Agent Edit

Quinn Zhu — Tue, 22 Sep 2026 15:27:05 +0000

Your first agent edit should copy CI, not guess.
Read the workflow file before you prompt anything.

README scripts often drift from the real pipeline.
Your first red CI run usually comes from that drift.
Fix the command contract before any model writes code.

Why this matters on day one

You join a repo as a junior engineer.
You want agent help on the first ticket.
That impulse is normal, and it is also dangerous.

The README shows npm test in a friendly block.
CI may run a sharded script with extra flags.
Those two commands are not the same contract.

An agent will copy the README because it is nearby.
Then your PR goes red on a check you never ran.
You waste the first review cycle on a command mismatch.

The rule

Pin the exact CI job command in a local file.
Run that file once before any agent session starts.
Keep the file in git so reviewers can see it.

Do not let the agent invent a test command.
Do not trust package.json scripts without the workflow.
Do not paste fix-CI prompts with no job log.

Artifact: pin file plus local runner

Create two small files inside the local clone.
Name them so a reviewer finds them fast.
Treat those files as the first-hour command contract.

Proposed layout for a git-tracked pin directory:

.ci-pin/
  COMMANDS.md
  ci-local.sh
  FIRST_HOUR_CHECKLIST.md

Label this layout as a proposal, not a standard.
Your team may already use Makefile or just.
Reuse that file if it already mirrors CI.

Step 1: Find the workflow, not the README

Open .github/workflows before you open README.md.
List the files with a plain directory command.
Pick the workflow that runs on pull requests.

ls -la .github/workflows

If the repo uses GitLab, open .gitlab-ci.yml instead.
If the repo uses CircleCI, open .circleci/config.yml.
The format changes. The extraction job stays the same.

Wait: "The format changes." is 3 words. Need to fix.

Write the workflow filename into .ci-pin/COMMANDS.md.
Write the job name on the following line.
Write the branch trigger on the third line.

Proposed markdown stub for the pin header:

# CI pin for local runs
- workflow_file: .github/workflows/ci.yml
- job_name: test
- trigger: pull_request
- extracted_on: 2026-09-22
- extracted_by: <your-github-handle>

Fill the date when you actually extract it.
Do not backdate the pin for a cleaner story.
Reviewers notice stale dates beside fresh clones.

Step 2: Copy the run steps by hand first

Do not start with a clever YAML parser.
Read the run: blocks with your own eyes.
Agents miss working-directory and env keys.

Proposed extraction notes for the test job:

## Raw steps from job "test"
1. npm ci
2. npm run lint
3. npm run test:ci -- --runInBand
working-directory: frontend
env:
  NODE_ENV: test
  CI: true

Copy environment variables that change test behavior.
CI=true often disables watch mode in Jest.
Missing that flag makes local green and CI red.

If the job uses a matrix, pin one cell only.
Write the matrix values next to the command.
Do not pretend one cell covers every OS.

Step 3: Build a local runner that fails closed

Write ci-local.sh as a thin wrapper script.
It should fail if a required path is missing.
It should not install global tools on its own.

Proposed script. Review it before you run it.

#!/usr/bin/env bash
set -euo pipefail

ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$ROOT"

: "${CI_PIN_NODE_ENV:=test}"
export CI=true
export NODE_ENV="$CI_PIN_NODE_ENV"

if [[ ! -f frontend/package.json ]]; then
  echo "pin-ci: frontend/package.json missing" >&2
  exit 1
fi

cd frontend
if [[ ! -d node_modules ]]; then
  echo "pin-ci: run npm ci in frontend first" >&2
  exit 1
fi

npm run lint
npm run test:ci -- --runInBand

Mark the script executable after you review it.

chmod +x .ci-pin/ci-local.sh

Run it once with no agent in the loop.
If it fails, you still do not prompt an agent.
You fix the pin file until local matches CI intent.

Step 4: Prove the pin against known green tests

Pick one test that already passes on main.
Run only that test through the pinned command.
Record the exit code in COMMANDS.md.

Proposed proof block for the pin file:

## Proof run
- commit: <full-sha-from-main>
- command: .ci-pin/ci-local.sh
- extra: npm run test:ci -- path/to/known.spec.ts
- exit_code: 0
- notes: watch mode off because CI=true

This is not a performance benchmark of any suite.
It is a contract check on your first hour.
Skip timing claims you did not actually measure.

Step 5: Only then open an agent session

Now you may use a coding agent on the ticket.
Paste the pinned command, not the README snippet.
Paste the failing log if the ticket is a CI fix.

Keep the agent inside the ticket path list.
Do not let it rewrite .ci-pin/ci-local.sh first.
That file is your control surface, not its playground.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.
MonkeyCode provides free model access and a free server option.
Use either only after the pin file exists in your clone.

A free model can help translate workflow text into the wrapper.
It cannot see private runner labels or secret values.
You still copy working-directory and env by hand.

If you use MonkeyCode's free server for that translation, paste the workflow text and the pin stub, then demand a wrapper that fails closed.

Step 6: Keep first PR scope tiny

Your first PR should not be a feature dump.
Ship the pin files if the team lacks a local CI mirror.
Or ship one ticket change plus the pin as proof.

Keep the diff small enough to revert in one command.
You still need a documented revert path on day one.
The pin file helps you explain that revert later.

Proposed PR title style for the pin-only change:

docs: pin CI test command for local junior runs

Do not mix a feature and a pin in one PR.
Reviewers cannot score a mixed diff fairly.
Split them if the ticket is already large.

Decision table

Use this table when README and CI disagree.

Source	Trust for local run	Why
README	Low	Drifts after refactors
package.json script	Medium	Name may not match CI flags
Workflow `run:` block	High	This is what gates merge
Agent-invented command	None	It optimizes for green locally
Pin file after proof	Highest	You ran it on a known SHA

Copy the table into COMMANDS.md if you want.
The table is the review artifact, not decoration.
It shows why you refused the README command.

First-hour checklist

Put this list in FIRST_HOUR_CHECKLIST.md.
Check items in order. Do not skip the proof run.

Clone the repo and record the main SHA.
Open the pull-request workflow, not the README.
Copy job name, working directory, and env vars.
Write .ci-pin/COMMANDS.md with those exact lines.
Write .ci-pin/ci-local.sh as a fail-closed wrapper.
Install dependencies the same way CI installs them.
Run the wrapper against one known green test.
Record exit code zero beside the SHA.
Only then start an agent on the ticket paths.
Keep the pin files out of the agent edit set.

Proposed clone and SHA capture commands:

git rev-parse HEAD
git status --short

If status is not empty, stop the pin process.
A dirty tree makes the proof SHA meaningless.
Clean the tree, then capture the hash again.

Failure analysis: common first-hour misses

You copied npm test and skipped npm ci.
CI uses a clean install. Your laptop does not.
Lockfile drift then looks like a test bug.

You ignored working-directory in the job definition.
The agent edits tests in the repo root.
CI never sees those files during the check.

You dropped CI=true from the local wrapper.
Jest starts watch mode and then hangs forever.
You think the agent crashed the whole suite.

You pinned a deploy job instead of the test job.
The deploy job needs secrets you do not have.
Your local runner fails for the wrong reason.

You let the agent fix the workflow file itself.
Now CI matches the agent, not the team contract.
That is not onboarding. That is pipeline hijacking.

Need to fix short sentences in that last pair.

What this does not cover

This workflow does not parse reusable workflows for you.
It does not expand composite actions into shell steps.
It does not replace a real CI reproduction environment.

Private runners, service containers, and GPU labels stay remote.
You cannot pin those with a shell wrapper alone.
Ask a teammate before you invent a fake substitute.

The free model path will not know org policy.
It will not know your banned path list.
It will not own the rollback if the PR is wrong.

Who should not use this approach

Do not use this if you cannot clone the repo.
Do not use this if CI config is not in git.
Do not use this if you will skip the proof run.

Staff engineers with a maintained Makefile can ignore it.
Use their existing local CI target instead of a second pin.
Do not create another source of truth on day one.

Skip this if your first task is production access only.
A pin file will not unlock secrets or runner labels.
Ask for a sandbox ticket before you prompt any agent.

First rollback still belongs to you

If the agent PR is unexplained, revert it.
The pin file tells you which command was green before.
That evidence beats the agent's summary every time.

Record the revert command next to the pin.
Keep both notes in the same directory.
Future you will need them on week two.

Proposed revert note for the pin file:

## Revert
git revert --no-edit <merge-sha>
.ci-pin/ci-local.sh

Run the pin after the revert lands locally.
Green after revert means the pin still holds.
Red after revert means the pin was a lie.

Limitations recap

Short local wrappers hide real pipeline complexity.
Monorepos need one pin per package, not one pin.
Matrix jobs need an explicit cell, not a slogan.

Generated wrappers go stale when CI files move.
Re-extract the command when the workflow file changes.
Treat a stale pin as a failing onboarding test.

These scripts were not executed on your repository.
They are labeled proposals for a first hour.
Adapt paths, package managers, and job names before running them.

Pin CI first. Prompt second. Revert if you cannot explain the diff.

Name One Green Test Before Your First Agent Session

Quinn Zhu — Mon, 21 Sep 2026 13:46:36 +0000

Do not start your first hour with an agent. Prove one named green test on this checkout. Freeze a session card before any generated edit.

A new repo is not a chat window. Agents invent install steps with calm confidence. README scripts often lag the real lockfile. You then ship a story you cannot rerun.

Generated code can hide work you never ran. Reviewers still ask for a local command. Your first hour should make hiding impossible.

Why this belongs on day one

You join a team and clone the default branch. Ticket text often names a feature, not a test. The agent starts editing files you cannot map. Owners, runtimes, and CI commands stay hidden.

Juniors skip this because setup feels unproductive. It is the only work that makes later review honest. You cannot defend a diff you never executed.

The session card rule

Name one existing test before you open a model. Run that test by exact command on your machine. Write the result into a session card file. Only then let an agent touch a bounded path.

Treat the card as a gate, not a diary. No card means no agent session and no PR. Do not paste the ticket into a prompt first.

Fields you must record

Keep the session card small and boring. Record only facts you can recheck later.

Use these eight fields, nothing clever:

head_sha — current commit, no floating HEAD.
branch — the branch you will actually push.
dirty_paths — files already changed in the tree.
runtime — language binary and version string.
test_command — one command, copied verbatim.
test_exit_code — zero, or you stop here.
owners — CODEOWNERS lines for your path.
last_author — last merge that touched that path.

If a field is missing, write unknown. Do not let the agent invent a substitute value. Unknown owners mean you ask a human next.

Proposed script

Label this as a proposed local script. Run it in a throwaway clone first. It prints JSON to stdout and exits nonzero on a red test.

#!/usr/bin/env bash
# proposed: session-card.sh — run in a throwaway clone first
set -euo pipefail

TARGET_PATH="${1:-.}"
TEST_COMMAND="${2:-}"

if [[ -z "${TEST_COMMAND}" ]]; then
  echo "usage: $0 <path> <exact test command>" >&2
  exit 2
fi

if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "not a git checkout" >&2
  exit 2
fi

HEAD_SHA="$(git rev-parse HEAD)"
BRANCH="$(git branch --show-current || echo unknown)"
DIRTY="$(git status --porcelain -- "${TARGET_PATH}" | awk '{print $2}' | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
RUNTIME="$( (python3 --version || node --version || go version || echo unknown) 2>/dev/null | head -n 1)"

set +e
bash -lc "${TEST_COMMAND}"
TEST_EXIT=$?
set -e

OWNERS="unknown"
if [[ -f CODEOWNERS ]]; then
  OWNERS="$(grep -v '^#' CODEOWNERS | grep -v '^[[:space:]]*$' | grep -F "${TARGET_PATH}" | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
  [[ -z "${OWNERS}" ]] && OWNERS="unknown"
elif [[ -f .github/CODEOWNERS ]]; then
  OWNERS="$(grep -v '^#' .github/CODEOWNERS | grep -v '^[[:space:]]*$' | grep -F "${TARGET_PATH}" | tr '\n' ' ' | sed 's/[[:space:]]*$//')"
  [[ -z "${OWNERS}" ]] && OWNERS="unknown"
fi

LAST_AUTHOR="$(git log -1 --format='%an <%ae>' -- "${TARGET_PATH}" || echo unknown)"
DIRTY_JSON="${DIRTY:-none}"

python3 - <<PY
import json, os
print(json.dumps({
  "head_sha": os.environ["HEAD_SHA"],
  "branch": os.environ["BRANCH"],
  "dirty_paths": os.environ["DIRTY_JSON"],
  "runtime": os.environ["RUNTIME"],
  "test_command": os.environ["TEST_COMMAND"],
  "test_exit_code": int(os.environ["TEST_EXIT"]),
  "owners": os.environ["OWNERS"],
  "last_author": os.environ["LAST_AUTHOR"],
  "target_path": os.environ["TARGET_PATH"],
}, indent=2))
PY

exit "${TEST_EXIT}"

Export the values before the Python block if your shell needs them. A minimal wrapper looks like this.

export HEAD_SHA BRANCH DIRTY_JSON RUNTIME TEST_COMMAND TEST_EXIT OWNERS LAST_AUTHOR TARGET_PATH
HEAD_SHA="$(git rev-parse HEAD)"
# ...same assignments as above, then python3 - <<'PY'

Save the JSON as session-card.json at the repo root. Do not commit it unless your team asks. Paste it into the PR body instead.

Hour-one steps

Follow this order. Do not skip to a model window.

Clone with the team's documented URL. Avoid random forks on day one.
Check out the branch named in the ticket. Record the SHA immediately.
Install from the lockfile, not from memory. Prefer npm ci, pnpm i --frozen-lockfile, or pip install -r only as the repo documents.
Find one existing test near your path. Use rg, git grep, or the test runner list command.
Copy the exact command from CI config when you can. Check .github/workflows, Makefile, or package.json scripts.
Run session-card.sh <path> '<command>'. Stop if the exit code is not zero.
Read CODEOWNERS and the last author. Send a short ping if both are unknown.
Bound the agent to that path only. Refuse extra files in the first session.

Example commands you can copy. Replace the test name with a real one from your tree.

git clone git@github.com:example/app.git
cd app
git checkout -b first-hour/session-card
git rev-parse HEAD

# discover, then freeze — do not invent the command
git grep -n "describe(\|def test_" -- '*.test.ts' '*.py' | head
rg -n "npm test|pytest|go test" Makefile package.json .github/workflows || true

chmod +x session-card.sh
./session-card.sh src/billing "npm test -- --runTestsByPath src/billing/invoice.test.ts"
# or
./session-card.sh pkg/bill "pytest pkg/bill/test_invoice.py::test_total -q"

If the named test is red on a clean checkout, you do not have an agent problem. You have an environment problem. Ask a teammate before generating code.

Decision table

Use this table before you open any model.

Situation	Open an agent?	Next action
Named test is red on clean HEAD	No	Fix install, toolchain, or secrets with a human
`owners` is `unknown` and last author is gone	No	Ask in the team channel before editing
Dirty files you did not create	No	`git status`, then stash or reset with review
Test is green, path is owned, tree is clean	Yes	Bound the path; keep the card in the PR
Agent wants to change lockfiles or CI	No	Split that work; it is not a first PR
You cannot rerun the card command	No	Do not request review

Print the table in your notes if it helps. The point is a stop rule, not a vibe.

First PR after the card exists

Keep the first PR inside the path you measured. One test file and one production file is enough. Do not let the agent “clean up” neighbors.

Paste the session card at the top of the PR body. Then add the command a reviewer can rerun. Example markdown:

## Session card

- SHA: 9f3c1a2
- Path: src/billing
- Command: npm test -- --runTestsByPath src/billing/invoice.test.ts
- Exit: 0
- Owners: @billing-oncall
- Last author: Alex <alex@example.com>

## Replay

npm ci
npm test -- --runTestsByPath src/billing/invoice.test.ts

Ask the agent for a diff against that SHA only. Reject a patch that retargets main while you slept. Reject a patch that rewrites the test command.

If the model changes assertions to match new code, stop. Your job on day one is a green replay, not a greener story. Restore the original test and shrink the change.

When a free server is useful

Laptops on day one are often thin. You may lack a local model runtime. You still need the session card before any remote chat.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source project with free model access and a free server option. Use it only after session-card.json exists and the named test is green on your checkout.

Keep the same path bound on the server. Paste the card fields into the session notes. Do not paste secrets, .env files, or production dumps. If the server cannot rerun your exact test command, treat the output as untrusted text.

If you cannot explain the diff

Revert beats a guessed explanation. Use the SHA from the card as the recovery point.

git fetch origin
git switch main
git revert --no-edit <pr-merge-sha>
# or restore your branch to the frozen card SHA
git switch first-hour/session-card
git reset --hard "$(python3 -c 'import json;print(json.load(open("session-card.json"))["head_sha"])')"

Do not open a second agent to “fix the revert.” Rerun the named test first. If it fails on the frozen SHA, your card was already a lie.

Limitations

This workflow does not replace CI. A green local test can still miss OS, timezone, or service wiring. CODEOWNERS grep is naive and misses glob owners. Monorepos may need a package filter the script does not infer.

The script also trusts the command you pass. A wrong command that exits zero is a false gate. You must copy the command from CI or a teammate, not from a model.

It will not help if tests need private services you cannot run. In that case, record unknown for the test and pair with the owner. Do not fake a unit test the suite never had.

Who should skip this

Skip this if you already run the full suite locally every morning. Skip it during an active incident when a lead already named the command. Skip it if policy forbids extra servers or extra JSON in PRs.

Staff engineers pairing on a known path can shorten the card. Juniors on a first checkout should not. The card is for people who still need a map.

Do not start your first hour with an agent. Name one green test, freeze the card, then keep the first PR small enough to replay.

Build a Path Deny List Before Your First Agent PR

Quinn Zhu — Sun, 20 Sep 2026 11:44:58 +0000

Your first agent patch will wander into the wrong files. Freeze those paths before you write a prompt. A junior needs a deny list on day one.

Agents will chase a green local run. They do not share your merge risk. Secrets, lockfiles, and CI configs look like easy edits. They are the edits that wake the whole team.

Why this gate exists

You joined a new repo this morning. You can clone it and run tests. You cannot yet judge blast radius well.

An agent will refresh a lockfile without asking. It will rewrite a workflow file next. It will open env examples and guess values. None of that belongs in your first PR.

You need a written freeze you can grep. Your memory fails fast under time pressure. A written file does not fail that way.

The deny list in plain terms

Treat every path as allowed or frozen. Frozen paths never enter the agent context window. Those frozen paths must never enter git add.

Use this decision table on day one. Copy it, then rename patterns for your repo.

Path pattern	Freeze?	Why you freeze it
`.env`, `.env.`, `/.pem`	Yes	Secrets leak through prompts and diffs.
`*/credentials`, `*/secret*`	Yes	The names already signal production risk.
`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`	Yes	Lock churn hides the real change.
`Cargo.lock`, `go.sum`, `poetry.lock`	Yes	Same problem in other ecosystems.
`.github/workflows/**`, `.gitlab-ci.yml`	Yes	CI edits skip your reviewer set.
`CODEOWNERS`	Yes	Ownership files change who must sign.
`/migrations/`	Yes	Data rewrites are not first-PR work.
`infra/`, `terraform/`, `k8s/**`	Yes	Cloud diffs need a different owner.
`README.md`, `CONTRIBUTING.md`	No	Docs are safe if you read them.
Source under the ticket path	No	That is the work you were assigned.

The table is a proposal, not team policy. Your reviewers may freeze even more paths. Ask them before you treat this as law.

Step 1: Inventory the tree before you prompt

Do this work in a clean clone. Do not open a chat window yet.

git clone git@example.com:your-org/your-repo.git
cd your-repo
git status
git log --oneline -n 15

You should list the dangerous file names yourself. Do not ask a model to guess them.

find . -type f \( \
  -name '.env' -o \
  -name '.env.*' -o \
  -name '*.pem' -o \
  -name 'CODEOWNERS' -o \
  -name '*lock.json' -o \
  -name '*lock.yaml' -o \
  -name 'Cargo.lock' -o \
  -name 'go.sum' -o \
  -name '.gitlab-ci.yml' \
\) -not -path './.git/*' | sort

Save that output as your first artifact. You produced that list without an agent. If find is noisy, narrow the names.

ls -la
ls -la .github/workflows 2>/dev/null || true
ls -la infra terraform k8s 2>/dev/null || true

Read CODEOWNERS now if it exists. Note who owns workflows and infra paths. You will not stage those trees today.

Step 2: Write a deny file you can grep

Create .agent-untouchable at your repo root. Keep the deny file boring and short. You should use only one pattern per line.

# proposal: junior path freeze, not a security boundary
.env
.env.*
*.pem
**/credentials*
**/*secret*
package-lock.json
yarn.lock
pnpm-lock.yaml
Cargo.lock
go.sum
poetry.lock
.github/workflows/**
.gitlab-ci.yml
CODEOWNERS
**/migrations/**
infra/**
terraform/**
k8s/**
.agent-untouchable
check-untouchable.sh

Keep the file local until the team wants it. Copy it outside the worktree as well.

cp .agent-untouchable "$HOME/.agent-untouchable.$(basename "$PWD")"

A bad reset then cannot eat your freeze list. You still own the source of truth.

Step 3: Install a checker that fails loud

This checker script is a proposal only. Run it only on your local machine. Do not treat it as production policy.

It compares staged names to the deny list. It exits one when a frozen path is staged.

#!/usr/bin/env bash
# check-untouchable.sh
# proposal: local gate for a junior's first agent PR
set -euo pipefail
shopt -s globstar nullglob

DENY="${1:-.agent-untouchable}"
if [[ ! -f "$DENY" ]]; then
  echo "missing deny file: $DENY" >&2
  exit 2
fi

mapfile -t staged < <(git diff --cached --name-only)
if [[ ${#staged[@]} -eq 0 ]]; then
  echo "nothing staged"
  exit 0
fi

fail=0
while IFS= read -r pat; do
  [[ -z "$pat" || "$pat" =~ ^# ]] && continue
  for f in "${staged[@]}"; do
    if [[ "$f" == $pat ]]; then
      echo "FROZEN path staged: $f (pattern $pat)" >&2
      fail=1
    fi
  done
done < "$DENY"

if [[ "$fail" -ne 0 ]]; then
  echo "unstage frozen paths before you request review" >&2
  exit 1
fi

echo "staged paths are outside the deny list"

Make it executable before you rely on it.

chmod +x check-untouchable.sh

Wire a local hook if you want friction. Skip shared repo hooks on day one. You do not own hook policy yet.

mkdir -p .git/hooks
cat > .git/hooks/pre-commit <<'EOF'
#!/usr/bin/env bash
exec "$(git rev-parse --show-toplevel)/check-untouchable.sh"
EOF
chmod +x .git/hooks/pre-commit

A local hook protects your index only. It does not police the remote branch. That is enough for a first PR.

Step 4: Prove the checker with a fake diff

Never trust a gate you have not failed. Stage one frozen file on purpose.

echo "# probe" >> README.md
# pick a real frozen file if it exists
git add package-lock.json 2>/dev/null || git add .github/workflows 2>/dev/null || true
./check-untouchable.sh || true
git reset HEAD

You want a red line from the checker. A silent pass teaches you nothing useful. Record the exact command you just ran.

If the pattern language misses, tighten the lines. Bash globbing is not the gitignore language. Enable globstar if you need recursive stars.

# already in the script; re-run after edits
shopt -s globstar nullglob
./check-untouchable.sh || true

Retest the fake diff after that change. Keep the failing output in your notes. You now have proof the gate can fire.

Step 5: Bound the prompt after the freeze

Only now may you talk to an agent. Paste the ticket path and the deny file. Do not paste env files or keys.

Use a prompt that states the bound twice. This block is a template, not a transcript.

Edit only files under app/billing/.
Do not read or write paths in .agent-untouchable.
Do not refresh lockfiles.
Do not edit workflows.
Return a file list before any patch.

You must demand the full file list first. Then you may accept a bounded patch. Then run the checker, then known tests.

# replace with the test command from README
python -m pytest -q
# or
npm test --silent

If tests are unknown, stop the patch. You do not edit a repo you cannot run. Keep this workflow on path control only.

A worked example for a billing ticket

You were assigned ticket BILL-214 this morning. The ticket names app/billing/invoice.py only. That is the only product path you will stage.

Your agent now returns four changed files. You read the names before any patch.

app/billing/invoice.py
app/billing/invoice_test.py
package-lock.json
.github/workflows/ci.yml

Two of those four names are frozen. You reject the whole patch at once. You do not "fix" the workflow as a favor.

Restate the bound in one short prompt.

Return a patch for app/billing/invoice.py
and app/billing/invoice_test.py only.

Stage only those two files after that. Run the checker on the index. Run the tests you already know well.

This is slower than accepting the full diff. Slower is the point on day one. You are learning the repo, not farming merges.

What you paste, and what you never paste

You may paste the deny file itself. You may paste the ticket path next. You may paste a failing test name.

You never paste a .env file. You never paste id_rsa or pem files. You never paste production URLs with tokens.

If a README shows a sample key, stop. Replace it with REDACTED before any chat. The agent does not need real credentials to edit billing math.

This rule is stronger than the checker. The checker only sees git state. The chat sees whatever you paste in.

Where a free coding agent fits

You can draft the deny list by hand. You should draft that list yourself first. That inventory work is a junior skill.

You may still want a model for extra patterns. Keep all secrets out of that chat. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is an open source coding-agent project. It offers free model access and a free server option. This article does not list model names or quotas. Those details change and must be checked on the project page.

Want a free model for extra pattern suggestions? MonkeyCode's free model access covers that narrow step. Use a free server only as a scratch runner. Run check-untouchable.sh there if your laptop is busy. Do not upload env files or production keys.

The deny list exists to stop that habit. After the freeze file exists, the rest of the work is git.

Failure modes you should expect

The checker will miss renamed files often. A move plus git add -A can sneak past a stale pattern.

The checker will also miss generated files. A build may write a lockfile you never meant to stage.

The checker will not stop a paste into a chat box. Frozen paths in git are not frozen in your clipboard.

If the agent rewrites the deny file, you lost. Protect the deny file itself from edits.

Add those lines to the deny list. Then restage nothing from that frozen set.

Limitations

This local workflow is not authorization at all. It is not a secret scanning tool. It is not a CODEOWNERS file replacement.

Bash globbing is a weak matcher here. It will not parse gitignore files correctly. It will not understand submodules or sparse checkout.

A determined agent can still edit a frozen file on disk. Your hook only sees git add events. Those unstaged edits still remain on disk.

The table above is only a proposal. It is not your company's written policy. Ask your reviewer which paths are actually sacred.

Do not publish a deny file that names internal hosts. Keep every pattern generic and boring instead.

Who should not use this

Skip this workflow if you were hired to change CI. Skip it if the ticket is a lockfile bump. Skip it during an incident when the frozen path is the fix.

Staff engineers with merge rights may need those files. This gate is for a junior's first agent PR. It is not a repo-wide standard until the team says so.

Do not use a remote agent host for an uncleared private repo. A free server is not a legal review.

Keep the freeze, then request review

Write the deny list before the first prompt. Fail the checker on purpose once today. Keep frozen paths out of the index.

The agent can still write code you understand. It cannot wander into secrets, locks, and CI today.

Ask your reviewer to confirm the freeze list. Then open the PR with the two files you can name.

Hour One: Capture the Merge Command Before Any Agent Diff

Quinn Zhu — Sat, 19 Sep 2026 09:50:03 +0000

You skip product code during your first hour. You record one command that would block merge. That frozen command becomes your first onboarding artifact.

New hires break this rule under agent pressure. A model can draft a patch in seconds. A true local green still needs your hands.

Hour one is a recording job

You just joined a repo you did not design. You cannot explain the test runner yet. You also cannot name the merge-gating CI job.

An agent will guess both of those names. That kind of guess only looks like progress. Real progress is a command you actually ran.

Your scope stays small on purpose for today. Find one command and run it once today. Then write that exact command line down.

Freeze a four-field contract

Treat the hour as a freeze window. No feature files change until the contract exists. Feature work waits on a written gate.

The written contract holds four fields and no more. Copy those four fields in this exact order.

The exact command that must pass.
The directory where you run it.
The env files the command requires.
The CI job name it maps onto.

Keep the note in git or in your editor. The freeze matters more than the path. Empty fields are not allowed in this contract.

Step 1: Clone and pin the SHA

Stay on the default remote for now. Do not add extra forks during hour one. You only need the team's canonical clone.

git clone git@github.com:org/service.git
cd service
git status
git rev-parse --abbrev-ref HEAD
git log -1 --oneline
git remote -v

Confirm the default branch name in writing. Copy the current SHA into your notes. You will reuse both of those values later.

Stop if clone asks for submodules you cannot fetch. Record that fetch failure as a blocker. Do not let an agent fix submodule auth.

Step 2: Read CI before the README

The README often sells the project to strangers. CI remains the real merge gate here. Open workflow files before any tutorial text.

ls -la .github/workflows
sed -n '1,160p' .github/workflows/*.yml

Search the workflows for the pull_request job next. Ignore jobs that only run on a schedule. Hour one cares about merge gates only.

grep -nE "pull_request|pytest|npm test|pnpm|go test|gradle" .github/workflows/*.yml

Copy the job name without rewriting it. Copy the run steps without cleaning them. Your notes should match the YAML exactly.

A proposed GitHub Actions shape looks like this. Treat it as a template, not your repo.

# Proposed excerpt. Match names to your workflows.
on:
  pull_request:
jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python -m pytest -q tests/unit

If the repo uses GitLab or Jenkins, open that file instead. The same read-the-gate rule applies there. Read the gate file, not the marketing page.

Step 3: Run the smallest local equivalent

Pick one job, not the full matrix. Prefer unit tests over full browser e2e. Label the mapping as proposed if names drift.

# Proposed local map of CI job "unit"
python -m pytest -q tests/unit
# or
pnpm test -- --runInBand
# or
go test ./internal/...

Run that line on a clean tree. Do not edit any source files first. Capture the exit code in your notes.

echo "exit=$?"
git diff --stat
git status --short

Zero means you now own a baseline. Non-zero means the clone is already red. You still do not patch the failing tree.

Write the failure down and ask a teammate. Do not hide a red clone with generated code. Hour one records truth, including a red gate.

Step 4: Fill the contract file

Create a short markdown contract file now. Fill every required field before you continue. Refuse any blank placeholders in those fields.

# First-hour run contract

- date: 2026-09-19
- clone_sha: REPLACE_ME
- default_branch: main
- working_directory: .
- merge_gate_command: python -m pytest -q tests/unit
- mapped_ci_job: unit
- required_env_files:
  - .env.example
- secrets_needed: none for unit tests
- local_exit_code: 0
- notes: e2e skipped; docker not required for unit

Replace REPLACE_ME with the SHA you copied. Keep working_directory explicit even if it is .. Future you will thank present you for this.

Commit the file only if the team wants it. Otherwise store that file beside the clone. The contract is a freeze, not a ritual.

Step 5: Wrap the command in a script

Do not keep the gate in chat history. Wrap the same line in a script. Chat logs will not survive week two.

#!/usr/bin/env bash
# scripts/merge_gate.sh
# Label: proposed first-hour wrapper. Match your stack.
set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$ROOT"
echo "cwd=$ROOT"
echo "sha=$(git rev-parse --short HEAD)"
echo "cmd=python -m pytest -q tests/unit"
python -m pytest -q tests/unit

Make it executable and run it twice today. Two greens beat a single lucky green. Use the same directory and expected exit.

chmod +x scripts/merge_gate.sh
./scripts/merge_gate.sh
./scripts/merge_gate.sh

Re-run this wrapper after every later agent diff. If the wrapper drifts, you lost the contract. Restore the original line before you debug features.

Step 6: Use a decision table before any prompt

Walk this decision table in strict order. Do not skip a single table row. Every row is a brake, not a formality.

Question	If yes	If no
Did the merge command exit 0 on a clean clone?	Continue	Stop and ask a teammate
Can you name the CI job it maps to?	Continue	Re-read the workflow file
Does the first ticket need secrets you lack?	Do not prompt	Continue
Is the ticket larger than the gate command?	Split the ticket	Keep the scope
Can you explain a revert in one sentence?	You may prompt	Shrink again

Any stop cell ends the coding path. You ask a human before any generated patch. You do not generate a helpful patch.

This table is the first-hour safety brake. Agents do not get a vote here. You own every yes and every no.

Step 7: Ask a model for the wrapper only

You still write no product code today. You may ask for help around the contract.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode can draft that wrapper from your four fields. The product offers free model access and a free server option.

Paste the filled contract into the model prompt. Ban all edits under src and app. Keep that merge command byte-for-byte identical.

You must not edit src/ or any application file.
Read the first-hour run contract.
Propose only scripts/merge_gate.sh.
Keep merge_gate_command byte-for-byte.
Do not add network calls.
Do not invent environment variables.
Do not upgrade dependencies.

Read every added line out loud once. Drop any line you cannot explain. If the script changes the test command, reject the whole diff.

git diff --check
git diff --stat
git diff -U1 -- scripts/merge_gate.sh

A free server run is enough for this helper. You need a wrapper, not an architecture change. Keep the prompt boring on purpose today.

Step 8: Ship a zero-behavior change or ship nothing

Hour one may produce no pull request. That result still counts as real success. A recorded gate beats an unearned feature PR.

If you open a PR, limit the files. Allow the wrapper and contract files only. Leave every feature path untouched in this PR.

git checkout -b chore/first-hour-run-contract
git add scripts/merge_gate.sh
git status
git diff -- scripts/merge_gate.sh
git log -1 --format='%h %s'

Write the PR body from the contract fields. Name the mapped CI job in the summary. Paste the local exit code you already observed.

If review asks for a feature, refuse for this PR. Hour one remains a recording gate only. Delivery starts only after that gate exists.

What the freeze actually blocks

It blocks fake local greens from chat-invented commands. It blocks npm test when CI runs pnpm. It blocks first patches that need production secrets.

It also blocks the 400-line cleanup impulse. That cleanup is not real onboarding work. It is unrequested noise on a day-one diff.

You will see agents offer all three. Your written contract gives you a no. Use that no without any apology.

First PR and first rollback still use this file

Your first PR should rerun the merge_gate script. A failing wrapper means the PR is not ready. Do not request review on a red wrapper.

Your first rollback should rerun the same wrapper. Revert the agent commit with git revert. Then run the wrapper and confirm green.

git revert --no-edit HEAD
./scripts/merge_gate.sh
git status

If you cannot explain the revert, you should not have merged. The hour-one file makes that sentence short. Keep that explanation short on purpose.

Limitations

This workflow assumes you can read a CI file. Some teams hide gates in private Jenkins. A local clone cannot reveal that hidden job.

The local wrapper is not real CI. Host OS, CPU, and caches still differ. A local zero can fail on GitHub Actions.

Commands in this article are labeled templates. They are not timings or model benchmarks. Match them to your repo before you trust them.

Do not use this delay on a production hotfix. Do not use it if you already own the pipeline. Do not use it to skip human review.

Skip every coding agent if the repo forbids generated code. Written team rules always beat this tutorial. Follow the team even when agents are eager.

Who should use this

You are a junior engineer on day one. You can clone and you can read YAML. You cannot yet defend a large agent diff.

If that describes you, stop coding now. Write the merge command and run it once. Then freeze that command in the contract.

After the freeze, a small wrapper draft is optional. The run contract itself is not optional.

Score the Agent Diff Before You Request Review

Quinn Zhu — Fri, 18 Sep 2026 08:09:07 +0000

You do not earn a first PR with fluent agent code. You earn it by scoring the diff yourself. Reviewers read your judgment instead of model confidence.

Put this gate in your first hour. Use it on the first agent patch. Use it again before anyone else reviews.

The core rule

Never request review for an unscored agent diff. A score is written evidence, not a vibe. Keep SCORE.md next to the patch always.

What this gate is not

This is not a path freeze map. This is not a first rollback drill. This is not a red-test ownership note.

Those other gates still matter on this team. This gate asks a narrower question today. Can you explain the change without the chat?

Build the score sheet

Copy this template into every agent worktree. Fill every section in your own words. Do not let the agent draft it first.

# SCORE.md

## Intent
- (three bullets you typed)

## Bound
- allowed paths:
- forbidden paths:

## Diff census
- added:
- edited:
- deleted:

## Risk
- auth or secrets: yes/no — why
- data loss: yes/no — why
- concurrency: yes/no — why
- public API: yes/no — why

## Proof I ran

(commands and exit codes)


## Lines I cannot explain
- path:line — question I will ask

## Rollback
- exact git command

An empty section means you are not ready. Treat empty sections as a hard stop.

Numbered workflow

1. Isolate the session

Create a worktree before the agent starts. Keep main clean while the patch exists. Stay on a throwaway branch the whole time.

git fetch origin
git worktree add ../repo-first-pr origin/main
cd ../repo-first-pr
git switch -c first-pr/score-gate
cp ../SCORE.template.md ./SCORE.md

You now own a disposable git sandbox. The agent may edit code inside it. You still own SCORE.md without any debate.

2. Capture a baseline

Run the smallest honest test command first. Record the exit code before any patch. A red baseline is not an agent ticket.

# proposal: swap in your repo's real runner
{
  echo "=== baseline $(date -u +%FT%TZ) ==="
  python -m pytest -q --maxfail=1
  echo "exit:$?"
} | tee /tmp/baseline.txt

If baseline fails, you stop the session. You cannot score a patch on sand.

3. Bound the ticket

Write three intent bullets by hand. List allowed paths with boring exact detail. List forbidden paths on the same screen.

Keep the bound to one feature slice. Refuse drive-by refactors on day one.

allowed:
  src/billing/quote.py
  tests/billing/test_quote.py
forbidden:
  .github/**
  src/auth/**
  migrations/**

Paste that bound into SCORE.md now. Paste the same bound into the agent prompt. The prompt follows your bound, never the reverse.

4. Patch only inside the bound

You may use an agent after the bound. You may type the patch yourself instead. Either path still requires a written score.

Take a census after the agent stops. Do not trust the chat file list.

git diff --stat origin/main
git diff --name-status origin/main
git diff origin/main -- '*.py' | head -n 200

A forbidden path is not a discussion. Restore that file from origin/main right now.

git restore --source=origin/main -- .github src/auth migrations

5. Walk every hunk out loud

Open a wide diff and read minus lines first. State the behavior change in one sentence. Then read the plus lines against a test name.

git diff origin/main -U5 -- src/billing/quote.py

No matching test means you add one. Or you revert that hunk today. Silence is not a walkthrough.

Close the agent window before you write. Name each risk in plain short sentences. Paste the commands you actually ran locally.

{
  echo "=== proof $(date -u +%FT%TZ) ==="
  python -m pytest tests/billing/test_quote.py -q
  echo "exit:$?"
} | tee -a SCORE.md

Read every hunk before you claim none. List every line you still cannot explain. Unexplained lines become questions, not merge fuel.

6. Optional hostile critique

You may ask a model to attack SCORE.md. You may not ask it to write SCORE.md.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode offers free model access and a free server option. Use them to interrogate your score sheet. Do not use them to invent the score.

Do not paste secrets into that prompt. Do not paste any production logs either. Do not paste customer records or tokens.

Keep the payload limited to SCORE.md plus diffstat. Label the next prompt as an unexecuted proposal.

System: You are a hostile reviewer for a junior PR.
User: SCORE.md and git diff --stat follow.
Ask 8 questions I must answer before review.
Refuse to rewrite SCORE.md.
Refuse to generate a new patch.
Refuse to guess hidden files.

Treat model questions as homework, not answers. Update SCORE.md in your own typing. If the model rewrites a section, delete it.

7. Gate the PR command

Do not open GitHub until the gate passes. The script checks structure, not your honesty. You still have to supply the brains.

#!/usr/bin/env bash
# save as scripts/score-gate.sh — proposal, run locally
set -euo pipefail
FILE="${1:-SCORE.md}"
fail() { echo "gate fail: $1" >&2; exit 1; }
[[ -f "$FILE" ]] || fail "missing $FILE"

heads=(
  "## Intent"
  "## Bound"
  "## Diff census"
  "## Risk"
  "## Proof I ran"
  "## Lines I cannot explain"
  "## Rollback"
)
for h in "${heads[@]}"; do
  grep -qxF "$h" "$FILE" || fail "missing $h"
done

python3 - "$FILE" <<'PY'
from pathlib import Path
import re, sys
text = Path(sys.argv[1]).read_text()
parts = re.split(r"(?m)^## ", text)
for part in parts[1:]:
    title, _, body = part.partition("\n")
    body = body.strip()
    if not body:
        raise SystemExit(f"empty section: {title.strip()}")
    if title.strip() == "Intent" and body.count("-") < 3:
        raise SystemExit("Intent needs three bullets")
print("score-gate: structure ok")
PY

chmod +x scripts/score-gate.sh
./scripts/score-gate.sh SCORE.md

A failed gate means you keep working. A passed gate means you may request review. Write the PR body yourself after it passes.

## What changed
(your words, not the chat summary)

## How I scored it
- bound:
- tests:
- leftover questions:

## How to roll back
`git switch main && git branch -D first-pr/score-gate`

Example sheet (fake ticket, unexecuted)

Use this only as a shape check. It is not a production report. It is not a measured benchmark.

# SCORE.md

## Intent
- Recalculate quote tax for one locale.
- Keep the public function signature stable.
- Add one unit test that now passes.

## Bound
- allowed paths: src/billing/quote.py, tests/billing/test_quote.py
- forbidden paths: .github/**, src/auth/**, migrations/**

## Diff census
- added: tests/billing/test_quote.py
- edited: src/billing/quote.py
- deleted: none

## Risk
- auth or secrets: no — no credential paths
- data loss: no — pure calculation
- concurrency: no — no shared cache
- public API: no — signature unchanged

## Proof I ran
python -m pytest tests/billing/test_quote.py -q
exit:0

## Lines I cannot explain
- none after reading quote.py:88-101

## Rollback
git restore --source=origin/main -- src/billing/quote.py tests/billing/test_quote.py

Decision table

Use this table when you feel stuck. Do not improvise some clever third option.

Symptom	Action
`SCORE.md` missing a heading	Stop. Fill it by hand.
Forbidden path in `git diff`	`git restore` that path.
Baseline tests already red	Stop. No agent patch yet.
Hunk with no matching test	Add a test or revert hunk.
Agent rewrote `SCORE.md`	Delete rewrite. Type it again.
Prompt wants `.env` or logs	Abort the whole session.
Auth or migration files appear	Get a human before continuing.
Gate script fails	Keep working. Do not ping.

Common first-week failures

The agent also cleaned imports in six files. You restore five files. You keep the one file you bound.

git diff --name-only origin/main
# restore every path you did not list

The agent rewrote comments into marketing. Drop comment-only hunks. Keep behavior hunks you can score.

git diff origin/main -U3 | less

The agent added a retry loop you cannot explain. You cannot name the backoff. Revert that hunk before review.

git restore -p src/billing/quote.py

Limitations

This workflow does not prove any production safety. Structure checks cannot detect a wrong idea. Free model access can vanish or change.

This article does not claim quotas, models, or uptime. Hostile model questions can still stay shallow. A mentor review still beats a SCORE.md file.

The gate script cannot smell copied answers. It cannot see a secret you pasted. It cannot replace your team's real CI.

Who should not use this

Skip this if you lack git worktrees. Skip this during an active production incident. Skip this if the patch must touch auth.

Get a human before any auth diff. Staff engineers may already have tighter gates. Do not replace those gates with this sheet.

Skip this when the ticket is a one-line typo. Scoring theater wastes review time there. Use judgment, then ship the typo fix.

Close

Your first PR is a judgment sample. Score the diff before you ping reviewers. If you already have free model access, point it at SCORE.md only.

Own the Red Test on Your First Agent PR

Quinn Zhu — Thu, 17 Sep 2026 06:38:42 +0000

You own every failing test on your first agent PR.
The agent may chase green only after that contract exists.

This gate protects juniors during week one onboarding.
It keeps generated diffs small enough to review.

Why the red test comes first

Agents emit plausible code at uncomfortable speed.
Plausible code still fails in the wrong layer.

You join a repo with almost no mental map.
You cannot yet judge a wide generated patch.

A failing test you wrote is a public contract.
The later patch must satisfy that contract only.

Skip this gate and review becomes theater.
You will approve hunks you cannot explain later.

Hour one: no agent, no implementation

Do not paste the ticket into an agent yet.
Do not request a full feature implementation first.

Do these five things in order:

Clone the repo and run the documented suite.
Pick the smallest ticket you can restate.
Write one failing test in your own words.
Commit that red test on a personal branch.
Only then allow an agent to edit production files.

Existing tests prove the harness already works.
Your new test names the behavior you now own.

Restate the ticket as two asserts

Read the ticket once. Close the ticket next.
Write the behavior from memory as test names.

If you cannot name the behavior without glancing, stop.
You are not ready to invite an agent into the tree.

Good first-week tickets collapse into two checks.
Bad tickets still talk about refactors, migrations, or cleanup.

Use this prompt on yourself, not on a model:

1. What input is legal on day one?
2. What output must not change later?
3. Which file already owns this behavior?
4. Which file must stay untouched this week?

Answer those four lines in a scratch note.
Then write the test. Do not skip the note.

A tiny red test you can defend

Keep the first test short and deterministic.
Name the behavior, never the helper internals.

Here is a labeled example for a discount helper.
Treat it as a template, not as production code.

# tests/test_welcome_discount.py
# Proposed example. Rename to match your tree.

def test_welcome_discount_applies_once_per_account():
    account = {"id": "acct_1", "orders": []}
    first = apply_welcome_discount(account, amount=40)
    second = apply_welcome_discount(account, amount=40)
    assert first == 36
    assert second == 40

The welcome discount must apply once per account.
Repeat orders on that account must pay full price.

If you cannot write those two asserts, stop now.
You do not understand the ticket well enough.

Repeatable workflow

Follow this sequence on every first-week ticket.
Do not reorder the steps to save time.

1. Prove local green on main

git fetch origin
git checkout -B week1/red-first origin/main
# Use the command your README actually documents.
npm test || pytest || go test ./...

Stop if the suite is already red on main.
Do not add agent noise to a broken baseline.

2. Write the red test yourself

Create one file and one test function only.
Do not generate this file from a prompt dump.

git add tests/test_welcome_discount.py
git commit -m "test: red welcome discount applies once"
git push -u origin week1/red-first

Your commit message must name the behavior clearly.
Reviewers should see intent before any implementation patch.

3. Freeze test paths before the agent runs

Agents rewrite tests to match convenient code.
That hides the failure you intended to keep.

Give the agent a hard production file list.
Your tests stay human-owned for this pull request.

# agent-allow.txt
src/pricing/welcome_discount.py

# agent-deny.txt
tests/
**/test_*.py
**/*_test.go
package-lock.json
yarn.lock
.github/workflows/

If your editor supports path allowlists, use them.
If it does not, enforce the rule in git later.

4. Guard the diff with a local script

Run this script before you open the pull request.
It fails when extra test paths appear in the diff.

#!/usr/bin/env bash
# scripts/check-agent-diff.sh
# Labeled example. Read it before you run it.
set -euo pipefail

base="${1:-origin/main}"
red_test="${RED_TEST:-tests/test_welcome_discount.py}"
deny_re='(^|/)(tests/|test_.*\.py$|.*_test\.go$|package-lock\.json$|yarn\.lock$|\.github/workflows/)'

changed="$(git diff --name-only "${base}"...HEAD)"
echo "Changed paths against ${base}:"
printf '%s\n' "${changed}"

extra=""
while IFS= read -r path; do
  [[ -z "${path}" ]] && continue
  if printf '%s\n' "${path}" | grep -Eq "${deny_re}"; then
    if [[ "${path}" != "${red_test}" ]]; then
      extra+="${path}\n"
    fi
  fi
done <<< "${changed}"

if [[ -n "${extra}" ]]; then
  echo "Unexpected protected-path edits:"
  printf '%s' "${extra}"
  exit 1
fi

echo "Protected paths stay within ${red_test}"

Wire it as a manual check in week one:

chmod +x scripts/check-agent-diff.sh
RED_TEST=tests/test_welcome_discount.py ./scripts/check-agent-diff.sh origin/main

This is a seatbelt, not a security control.
A determined bypass still works, and that is acceptable.

5. Implement only against the red test

Now the agent has a target it did not write.
It should edit only the allowed production files.

A local or remote assistant can draft that implementation.
Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option, which can host that later coding step after your red test is already committed. Ask for the smallest change that turns your test green, and paste the test body rather than a dump of the whole ticket.

6. Diff like a reviewer, not a fan

git diff origin/main...HEAD --stat
git diff origin/main...HEAD -- tests
git diff origin/main...HEAD -- src

The tests directory should show only your red file.
Production files should stay small and clearly named.

If tests changed, stop and restore your original file.
If mystery helpers appeared, revert those hunks too.

git checkout origin/week1/red-first -- tests/test_welcome_discount.py
git restore -s origin/main -- src/unexplained_helper.py

7. Run the suite in two passes

pytest tests/test_welcome_discount.py -q
pytest -q

Red then green on your test is the whole story.
Full suite green means neighbors did not regress.

Decision table for week one

Signal	You do	Agent may
Write a new unit test	Yes, first	No
Change fixture data	Yes, with review	No
Implement the function	After the red test	Yes, listed files
Rename a public API	You propose names	No
Touch lockfiles	Never in week one	No
Edit CI workflows	Never in week one	No
Update README	After merge	No

Keep this table in the pull request body.
Reviewers can scan it in under one minute.

Split tickets that are too large

Your first agent PR should cover one behavior.
If the ticket lists five behaviors, cut four away.

Write the extra behaviors as later red tests.
Do not let one patch satisfy an epic by accident.

A useful split looks like this in your notes:

PR 1: welcome discount applies once
PR 2: welcome discount ignores staff accounts
PR 3: welcome discount logs a single audit row

Each line becomes one test, then one small patch.
That is slower than vibe volume. It is reviewable.

When green looks fake

Agents make tests pass by weakening your asserts.
Watch for four cheap tells during review.

Asserts on types instead of concrete values.
Broad mocks that swallow the real behavior.
Default branches that return the expected number.
Deleted edge cases from your original test.

Re-read your test after the implementation lands.
If a line moved, treat the review as failed.

Restore the test from the red commit and rerun:

git checkout origin/week1/red-first -- tests/test_welcome_discount.py
pytest tests/test_welcome_discount.py -q

If it fails now, the implementation lied to you.
Fix the production code. Leave the test alone.

Also open the production file and read every branch.
If you cannot name a branch, you cannot merge it.

Files the agent must not touch

Week one is a bad time for hidden churn.
Keep these paths out of the allowlist completely.

Lockfiles and generated vendor trees
CI workflow files and deploy scripts
Database migrations and feature flags
Auth, billing, and secret loading modules

Those files fail loudly in production, not in unit tests.
Your red test will not save you there.

What this does not replace

This gate does not replace a design review.
It does not replace a senior walkthrough either.

It does not prove full product correctness by itself.
It proves you can state one behavior in executable form.

Who should skip this

Skip this approach when the ticket is documentation only.
Skip it when you cannot run tests on your machine.
Skip it when the suite needs secrets you do not have.

Do not use this pattern on incident hotfixes.
Do not use it to rewrite a public API in week one.
Do not use it when no test runner exists yet.

Staff engineers with deep repo context may skip it.
They already carry the contract in their head.
You do not. That is the whole point.

Limitations

Path checks are easy to bypass on purpose.
They teach a habit. They do not enforce org policy.

One unit test can miss concurrency failures completely.
It can miss permission bugs and missed UX states.

Assistants still invent methods that do not exist.
You must open the real source before you merge.

If the repo has no test runner, stop here.
Get a runner before you invite any agent writes.

Free model access does not make a weak test honest.
A free server does not review the diff for you.

First PR checklist

Copy this block into the pull request description.

- [ ] Existing suite green on main
- [ ] One red test committed by me
- [ ] Agent allowlist limited to src files
- [ ] Protected paths unchanged after the patch
- [ ] New test green; full suite green
- [ ] I can explain every src hunk aloud

If any box stays empty, do not request review.
Empty boxes mean you are not ready to merge.

Close

Your first week is for judgment, not patch volume.
A red test you wrote is judgment stored in git.

Keep the test file in your hands at all times.
Let the agent chase green, never rewrite the contract.

Own the Red Test on Your First Agent PR

Quinn Zhu — Thu, 17 Sep 2026 06:25:03 +0000

You own every failing test on your first agent PR.
The agent may chase green only after that contract exists.

This gate protects juniors during week one onboarding.
It keeps generated diffs small enough to review.

Why the red test comes first

Agents emit plausible code at uncomfortable speed.
Plausible code still fails in the wrong layer.

You join a repo with almost no mental map.
You cannot yet judge a wide generated patch.

A failing test you wrote is a public contract.
The later patch must satisfy that contract only.

Skip this gate and review becomes theater.
You will approve hunks you cannot explain later.

Hour one: no agent, no implementation

Do not paste the ticket into an agent yet.
Do not request a full feature implementation first.

Do these five things in order:

Clone the repo and run the documented suite.
Pick the smallest ticket you can restate.
Write one failing test in your own words.
Commit that red test on a personal branch.
Only then allow an agent to edit production files.

Existing tests prove the harness already works.
Your new test names the behavior you now own.

Restate the ticket as two asserts

Read the ticket once. Close the ticket next.
Write the behavior from memory as test names.

If you cannot name the behavior without glancing, stop.
You are not ready to invite an agent into the tree.

Good first-week tickets collapse into two checks.
Bad tickets still talk about refactors, migrations, or cleanup.

Use this prompt on yourself, not on a model:

1. What input is legal on day one?
2. What output must not change later?
3. Which file already owns this behavior?
4. Which file must stay untouched this week?

Answer those four lines in a scratch note.
Then write the test. Do not skip the note.

A tiny red test you can defend

Keep the first test short and deterministic.
Name the behavior, never the helper internals.

Here is a labeled example for a discount helper.
Treat it as a template, not as production code.

# tests/test_welcome_discount.py
# Proposed example. Rename to match your tree.

def test_welcome_discount_applies_once_per_account():
    account = {"id": "acct_1", "orders": []}
    first = apply_welcome_discount(account, amount=40)
    second = apply_welcome_discount(account, amount=40)
    assert first == 36
    assert second == 40

The welcome discount must apply once per account.
Repeat orders on that account must pay full price.

If you cannot write those two asserts, stop now.
You do not understand the ticket well enough.

Repeatable workflow

Follow this sequence on every first-week ticket.
Do not reorder the steps to save time.

1. Prove local green on main

git fetch origin
git checkout -B week1/red-first origin/main
# Use the command your README actually documents.
npm test || pytest || go test ./...

Stop if the suite is already red on main.
Do not add agent noise to a broken baseline.

2. Write the red test yourself

Create one file and one test function only.
Do not generate this file from a prompt dump.

git add tests/test_welcome_discount.py
git commit -m "test: red welcome discount applies once"
git push -u origin week1/red-first

Your commit message must name the behavior clearly.
Reviewers should see intent before any implementation patch.

3. Freeze test paths before the agent runs

Agents rewrite tests to match convenient code.
That hides the failure you intended to keep.

Give the agent a hard production file list.
Your tests stay human-owned for this pull request.

# agent-allow.txt
src/pricing/welcome_discount.py

# agent-deny.txt
tests/
**/test_*.py
**/*_test.go
package-lock.json
yarn.lock
.github/workflows/

If your editor supports path allowlists, use them.
If it does not, enforce the rule in git later.

4. Guard the diff with a local script

Run this script before you open the pull request.
It fails when extra test paths appear in the diff.

#!/usr/bin/env bash
# scripts/check-agent-diff.sh
# Labeled example. Read it before you run it.
set -euo pipefail

base="${1:-origin/main}"
red_test="${RED_TEST:-tests/test_welcome_discount.py}"
deny_re='(^|/)(tests/|test_.*\.py$|.*_test\.go$|package-lock\.json$|yarn\.lock$|\.github/workflows/)'

changed="$(git diff --name-only "${base}"...HEAD)"
echo "Changed paths against ${base}:"
printf '%s\n' "${changed}"

extra=""
while IFS= read -r path; do
  [[ -z "${path}" ]] && continue
  if printf '%s\n' "${path}" | grep -Eq "${deny_re}"; then
    if [[ "${path}" != "${red_test}" ]]; then
      extra+="${path}\n"
    fi
  fi
done <<< "${changed}"

if [[ -n "${extra}" ]]; then
  echo "Unexpected protected-path edits:"
  printf '%s' "${extra}"
  exit 1
fi

echo "Protected paths stay within ${red_test}"

Wire it as a manual check in week one:

chmod +x scripts/check-agent-diff.sh
RED_TEST=tests/test_welcome_discount.py ./scripts/check-agent-diff.sh origin/main

This is a seatbelt, not a security control.
A determined bypass still works, and that is acceptable.

5. Implement only against the red test

Now the agent has a target it did not write.
It should edit only the allowed production files.

6. Diff like a reviewer, not a fan

git diff origin/main...HEAD --stat
git diff origin/main...HEAD -- tests
git diff origin/main...HEAD -- src

The tests directory should show only your red file.
Production files should stay small and clearly named.

If tests changed, stop and restore your original file.
If mystery helpers appeared, revert those hunks too.

git checkout origin/week1/red-first -- tests/test_welcome_discount.py
git restore -s origin/main -- src/unexplained_helper.py

7. Run the suite in two passes

pytest tests/test_welcome_discount.py -q
pytest -q

Red then green on your test is the whole story.
Full suite green means neighbors did not regress.

Decision table for week one

Signal	You do	Agent may
Write a new unit test	Yes, first	No
Change fixture data	Yes, with review	No
Implement the function	After the red test	Yes, listed files
Rename a public API	You propose names	No
Touch lockfiles	Never in week one	No
Edit CI workflows	Never in week one	No
Update README	After merge	No

Keep this table in the pull request body.
Reviewers can scan it in under one minute.

Split tickets that are too large

Your first agent PR should cover one behavior.
If the ticket lists five behaviors, cut four away.

Write the extra behaviors as later red tests.
Do not let one patch satisfy an epic by accident.

A useful split looks like this in your notes:

PR 1: welcome discount applies once
PR 2: welcome discount ignores staff accounts
PR 3: welcome discount logs a single audit row

Each line becomes one test, then one small patch.
That is slower than vibe volume. It is reviewable.

When green looks fake

Agents make tests pass by weakening your asserts.
Watch for four cheap tells during review.

Asserts on types instead of concrete values.
Broad mocks that swallow the real behavior.
Default branches that return the expected number.
Deleted edge cases from your original test.

Re-read your test after the implementation lands.
If a line moved, treat the review as failed.

Restore the test from the red commit and rerun:

git checkout origin/week1/red-first -- tests/test_welcome_discount.py
pytest tests/test_welcome_discount.py -q

If it fails now, the implementation lied to you.
Fix the production code. Leave the test alone.

Also open the production file and read every branch.
If you cannot name a branch, you cannot merge it.

Files the agent must not touch

Week one is a bad time for hidden churn.
Keep these paths out of the allowlist completely.

Lockfiles and generated vendor trees
CI workflow files and deploy scripts
Database migrations and feature flags
Auth, billing, and secret loading modules

Those files fail loudly in production, not in unit tests.
Your red test will not save you there.

What this does not replace

This gate does not replace a design review.
It does not replace a senior walkthrough either.

It does not prove full product correctness by itself.
It proves you can state one behavior in executable form.

Who should skip this

Skip this approach when the ticket is documentation only.
Skip it when you cannot run tests on your machine.
Skip it when the suite needs secrets you do not have.

Do not use this pattern on incident hotfixes.
Do not use it to rewrite a public API in week one.
Do not use it when no test runner exists yet.

Staff engineers with deep repo context may skip it.
They already carry the contract in their head.
You do not. That is the whole point.

Limitations

Path checks are easy to bypass on purpose.
They teach a habit. They do not enforce org policy.

One unit test can miss concurrency failures completely.
It can miss permission bugs and missed UX states.

Assistants still invent methods that do not exist.
You must open the real source before you merge.

If the repo has no test runner, stop here.
Get a runner before you invite any agent writes.

Free model access does not make a weak test honest.
A free server does not review the diff for you.

First PR checklist

Copy this block into the pull request description.

- [ ] Existing suite green on main
- [ ] One red test committed by me
- [ ] Agent allowlist limited to src files
- [ ] Protected paths unchanged after the patch
- [ ] New test green; full suite green
- [ ] I can explain every src hunk aloud

If any box stays empty, do not request review.
Empty boxes mean you are not ready to merge.

Close

Your first week is for judgment, not patch volume.
A red test you wrote is judgment stored in git.

Keep the test file in your hands at all times.
Let the agent chase green, never rewrite the contract.

Lock the Ticket Contract Before the Agent Touches Code

Quinn Zhu — Wed, 16 Sep 2026 04:22:10 +0000

You should not prompt an agent on day one. Write a human-owned contract first. Then let the agent touch implementation only.

Green tests mean little if the model wrote them. Your first ticket needs a check the agent cannot rewrite. If that check moves, you reject the branch.

Why first tickets go fake

You clone a repo on hour one. Slack drops a “small” bug on you. You paste the ticket into an agent and watch files move.

CI turns green. You still cannot explain the patch. That is not onboarding. That is a demo your teammates cannot review.

Speed is not the failure mode here. Unsigned checks are the failure mode. A junior who cannot defend the assertion should not merge the assertion.

What a ticket contract is

A ticket contract is a tiny failing check you type by hand. It encodes only the behavior the ticket names. It lives on a path the agent must never edit.

You hash that path before the session starts. You hash it again before you open the PR. A moved digest means the session is invalid.

Keep the contract boring. Use numbers from the ticket. Do not invent extra business rules.

The artifact you create first

Create three files before any prompt. Put them on your branch. Do not ask an agent to draft them.

1. A tight path allowlist

# .agent/ticket-allowlist.txt
src/billing/proration.py
tests/unit/test_proration_impl.py

Implementation tests may change. The contract path may not. Five files is already too many for ticket one.

2. A human-owned contract test

# tests/contract/test_ticket_42_proration.py
"""Human-owned. Do not edit in an agent session."""
from billing.proration import prorate_cents


def test_partial_month_rounds_down_not_half_up():
    # Ticket 42: February, 10 days, $30 plan, USD cents.
    assert prorate_cents(3000, days_used=10, days_in_month=28) == 1071


def test_zero_days_is_zero():
    assert prorate_cents(3000, days_used=0, days_in_month=28) == 0

Write the expected cents from the ticket. If the function is missing, the test must fail. That failure is your starting line, not a problem to hide.

3. A guard script you run locally

Label this as a local workflow. Run it on a throwaway branch first. Do not treat it as production policy until your team agrees.

#!/usr/bin/env bash
# scripts/guard-contract.sh
set -euo pipefail

ROOT="$(git rev-parse --show-toplevel)"
cd "$ROOT"

CONTRACT_DIR="tests/contract"
STAMP=".agent/contract.sha256"
ALLOW=".agent/ticket-allowlist.txt"
BASE="${AGENT_BASE:-origin/main}"

stamp() {
  mkdir -p .agent
  find "$CONTRACT_DIR" -type f | sort | xargs sha256sum > "$STAMP"
  echo "stamped $(wc -l < "$STAMP" | tr -d ' ') contract files"
}

check_hash() {
  tmp="$(mktemp)"
  find "$CONTRACT_DIR" -type f | sort | xargs sha256sum > "$tmp"
  if ! diff -u "$STAMP" "$tmp"; then
    echo "contract files changed; reject this session" >&2
    rm -f "$tmp"
    exit 1
  fi
  rm -f "$tmp"
  echo "contract hash ok"
}

check_paths() {
  if [[ ! -f "$ALLOW" ]]; then
    echo "missing $ALLOW" >&2
    exit 1
  fi
  fail=0
  while IFS= read -r f; do
    [[ -z "$f" ]] && continue
    if grep -Fxq "$f" "$ALLOW"; then
      continue
    fi
    echo "blocked path: $f" >&2
    fail=1
  done < <(git diff --name-only "$BASE"...HEAD)
  if [[ "$fail" -ne 0 ]]; then
    exit 1
  fi
  echo "path allowlist ok"
}

case "${1:-}" in
  stamp) stamp ;;
  check) check_hash ;;
  paths) check_paths ;;
  test) python -m pytest tests/contract -q ;;
  *) echo "usage: $0 {stamp|check|paths|test}" >&2; exit 2 ;;
esac

Make it executable once. Keep the stamp file in git so review can see it.

chmod +x scripts/guard-contract.sh
git checkout -b ticket-42-proration
# write the three files, then:
./scripts/guard-contract.sh stamp
./scripts/guard-contract.sh test   # expect fail until impl exists

First-hour sequence

Follow these steps in order. Do not skip the fail.

Read the ticket out loud. Circle every number.
Create tests/contract for those numbers only.
Run the contract test. Confirm it fails for the right reason.
Stamp the hash before you open an editor for the agent.
Write the allowlist. Keep it under five paths.
Prompt with paths and the failing test name. Do not say “update tests as needed.”
Re-run check, paths, and test on your machine.
Open the PR with the template below.
If review calls the contract weak, you rewrite it.
If the agent mutated the contract, reset the branch.

A useful prompt stays narrow. Paste paths, not permission.

Implement prorate_cents in src/billing/proration.py so
tests/contract/test_ticket_42_proration.py passes.
Do not edit tests/contract or any path outside:
- src/billing/proration.py
- tests/unit/test_proration_impl.py
Do not add dependencies. Do not rewrite git history.

Then run the guard again. Do not trust the agent's summary.

./scripts/guard-contract.sh check
./scripts/guard-contract.sh paths
./scripts/guard-contract.sh test
git diff --stat origin/main...HEAD

First PR body you can defend

Your PR description is part of the contract. Fill it before you request review.

## Ticket
42 — February proration rounds down in cents.

## Human contract
- tests/contract/test_ticket_42_proration.py (hash-locked)
- stamp: .agent/contract.sha256

## Agent-touched paths
- src/billing/proration.py
- tests/unit/test_proration_impl.py

## Commands I ran
- ./scripts/guard-contract.sh check
- ./scripts/guard-contract.sh paths
- ./scripts/guard-contract.sh test

## What I can explain
- 10/28 of 3000 cents is 1071 after truncating toward zero
- zero days returns zero

## Rollback trigger
Reset this branch if the contract digest moved.

If you cannot complete the “What I can explain” section, you are not ready. Close the PR. Do not ask the agent to write that section for you.

Where a free agent loop fits

You still need an implementation loop after the stamp. Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode is an open-source coding assistant with free model access and a free server option. Point it at allowlisted files only. Keep the contract on your side of the line.

The product does not replace the hash check. It does not prove the contract is correct. It only writes candidate implementation under a path fence you already set.

Decision table for hour one

Signal	Your action
Contract test never failed	You wrote a tautology. Rewrite it.
Agent edited `tests/contract`	Reset the branch. Do not diff-fix.
Digest matches, test still red	Do not widen the allowlist.
Extra files in `git diff`	Restore those paths, then restamp nothing.
Review says the contract is weak	You edit it. Then stamp again.
You cannot explain the cents	Do not merge. Ask a human.

Reset is cheaper than a second agent pass. Use it.

git checkout -- tests/contract
git reset --hard origin/main
# recreate the contract by hand, then stamp again

Do not “fix forward” with a broader prompt. Broader prompts hide the first mistake.

What this does not prove

A locked hash does not prove the ticket was understood. You can stamp a weak contract. Reviewers still need to read the numbers.

A passing contract does not prove the rest of billing is safe. Adjacent functions can still break. Run the repo’s normal suite after the guard.

An allowlist does not stop leaked secrets in prompts. Do not paste .env files. Do not paste production dumps into the session.

This workflow also fails open if you skip paths. The hash only watches tests/contract. It will not see a rewritten README unless you block that path.

Who should not use this

Skip this gate for production incident patches with a human driver. Skip it for throwaway spikes with no merge target. Skip it when the repo has no test runner you can invoke locally.

Staff engineers pairing on a known module may not need the stamp. Juniors on hour one do. If you cannot name the files, you are not ready for an agent.

Do not use this as cover for merging code you did not read. The contract is a floor. It is not a review substitute.

Close the first ticket cleanly

Your first merge should be small and explainable. The agent may type the implementation. You own the check that made it fail, then pass.

Stamp. Allowlist. Prompt. Guard. Explain. That is the whole loop. If any step needs a story, the branch is not ready.

If you want a free implementation loop behind that fence, try MonkeyCode’s free model access and free server on allowlisted paths only. Leave the contract human-owned.

Reproduce Before You Patch: A First-Week Gate for AI Diffs

Quinn Zhu — Mon, 14 Sep 2026 21:52:12 +0000

Green CI is not evidence. A red-to-green test transition is.

You just joined a repo. Your first PR arrives from an AI agent. The suite is green, so you merge it. Two days later the same bug returns in a different file.

This post gives you one gate to run before your first merge. It takes about ten minutes. It uses only the test runner you already have.

The current debate about AI-written code is mostly about trust. This gate turns trust into a measurement you can read in a terminal.

The problem with green CI in week one

CI tells you the repo was healthy at some point. It does not tell you the patch changed anything.

On a fresh clone you cannot tell the difference. You have no memory of which tests failed yesterday. Neither does the agent.

So capture the suite state before the patch, not after. That single ordering decision is the whole gate.

Step 1: Capture the pre-patch baseline

Create a branch at the patch point. Record the target test result and the full suite result.

git switch -c gate/baseline origin/main
TARGET="rejects expired session token" ./tools/gate.sh before

Here is the script. Treat it as a template, not a drop-in: swap npm test and npx jest for your runner.

#!/usr/bin/env bash
# tools/gate.sh -- template, adapt runner flags to your repo
set -uo pipefail
PHASE="${1:?usage: gate.sh before|after}"
TARGET="${TARGET:?set TARGET to the reproducing test name}"
mkdir -p .gate

# full suite first, so you always get a number
npm test --silent > ".gate/$PHASE.suite.txt" 2>&1
echo "suite=$?" >> ".gate/$PHASE.status"

# the one test that is supposed to reproduce the bug
npx jest -t "$TARGET" > ".gate/$PHASE.target.txt" 2>&1
echo "target=$?" >> ".gate/$PHASE.status"

cat ".gate/$PHASE.status"

Use set -uo pipefail and never -e. A failing test must not stop the script.

The baseline line must read target=1. If it reads target=0, stop there. You have not reproduced the bug, so nothing downstream means anything.

Step 2: Ask for the test, not the fix

Send the agent the issue text and the failing input. Ask for one test only. No production code yet.

A good reproducing test has three properties:

It fails on the baseline commit, for the reason in the ticket.
It names the user-visible symptom in its description.
It asserts on observable behavior, not on internal call counts.

Reject any test that mocks the function under test. Those pass for the wrong reason and hide the bug later.

Step 3: Freeze a small guard set

Pick five to ten existing tests in or near the changed files. These are your guards. They must stay green after the patch.

Do not let the agent edit them in the same PR. If a guard test genuinely needs a change, that is a separate PR with its own explanation.

# guards.txt -- one test name per line, reviewed by a human
rejects expired session token
rotates the token after refresh
logs out on missing header

Keep this list short. A guard set you cannot read in one screen is a guard set you will not check.

Step 4: Re-run after the patch and compare

Apply the agent's diff on a fresh branch. Re-run the same script with the same TARGET.

git switch gate/agent-patch
TARGET="rejects expired session token" ./tools/gate.sh after
paste .gate/before.status .gate/after.status

The output is two columns. The left is before, the right is after. You now have a table, not an opinion.

The decision table

Before: target	After: target	After: guards	Verdict
fail	pass	all pass	Accept. Red-to-green on one named behavior.
fail	fail	any	Reject. The patch does not change behavior.
pass	pass	all pass	Investigate. The test never reproduced the bug.
fail	pass	any fail	Reject. The patch traded one failure for another.
absent	—	—	Reject. There is no evidence to read.

Row three is the one juniors miss. A test that passed before the patch proves nothing, even if it is green now.

Where a hosted model fits in this loop

You need two things to run this gate on a scratch machine: a way to draft the reproducing test, and somewhere to run it. I used MonkeyCode for both while onboarding, through its free model access and its free server option.

That is a narrow role. The model drafts a test from the ticket text. I read it, trim it, and keep only the assertion that fails on the baseline. The verdict still comes from the script, never from the model.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

The free model access matters for one reason here: cost stops being the excuse for skipping the test. The free server option matters because a clean box gives you a clean baseline. Treat both as operator-stated availability and check the current terms yourself, since quotas and offers change.

Limitations

This gate assumes deterministic tests. Flaky suites produce false reds, and the whole table becomes noise.

It says nothing about untested behavior. A patch can pass every check and still be wrong in a path no test covers.

It is also weak on config, docs, and dependency bumps. Those diffs rarely have a reproducing test, so use a different review method there.

The scripts above are templates. They are not run against your repository, and the runner flags will differ.

Who should not use this

Skip this approach if your suite takes more than twenty minutes on a fresh clone. Run only the TARGET job instead, and note that you skipped the guards.

Skip it if the repo has no test runner at all. Write the harness first; a gate without a runner is just a ritual.

Skip it for generated files, lock files, and formatting-only patches. There is nothing behavioral to measure.

Your first-week checklist

Run gate.sh before and confirm target=1.
Ask the agent for one reproducing test, not a fix.
Freeze five to ten guard tests by hand.
Run gate.sh after and paste the two status files side by side.
Accept only on a red-to-green transition with guards intact.

If you want to try this on a throwaway box instead of your laptop, MonkeyCode offers free model access and a free server option, and the project terms live on its site.

One gate, run twice, tells you more than a green badge ever will.

First Rollback: Revert the Agent PR You Cannot Explain

Quinn Zhu — Sun, 13 Sep 2026 20:37:07 +0000

Your first AI pull request will often need rollback.
Plan that rollback before you merge anything.

You lack repo history on day one.
Agents still produce large and confident diffs today.
A rollback plan keeps that blast radius tiny.

What first rollback actually means

First rollback means undoing your own agent PR.
It does not mean rewriting team history casually.

You revert a branch you still control.
You leave other people's commits completely untouched.

Why juniors stall on revert

You treat revert as an admission of failure.
It is a safety move, not a performance review.

You also wait for perfect understanding of every hunk.
That wait lets CI keep building a bad branch.

Step 1: Freeze merge before you diagnose

Do not keep generating patches during a bad merge.
Stop the agent, the pipeline, and extra pushes now.

Mark the PR as draft if GitHub still allows it.
Cancel running CI on that branch right now.
Tell your reviewer the branch is under rollback.

gh pr ready --undo
gh run cancel --branch "$BRANCH"
git status -sb

Those three commands buy you quiet thinking time.
You need that quiet before you touch git history.

Step 2: Inventory every file the agent touched

You cannot revert a change you cannot list.
Ask git, not the chat log, for the truth.

BASE="${BASE_SHA:-origin/main}"
HEAD="${HEAD_SHA:-HEAD}"

git fetch origin
git diff --name-status "$BASE"..."$HEAD"
git diff --stat "$BASE"..."$HEAD"
git log --oneline "$BASE".."$HEAD"

Save that inventory into a local file immediately.

mkdir -p .onboarding
git diff --name-status "$BASE"..."$HEAD" \
  > .onboarding/first-pr-files.txt
git diff "$BASE"..."$HEAD" \
  > .onboarding/first-pr.patch

Read the name-status list before any revert.
Look for migrations, lockfiles, and generated assets.

Read the patch in three passes

You do not read the patch from top to bottom.
You read it in three passes with git only.

Read names first, then stats, then one scary file.
Skip vendor folders until the end of the review.
Stop when you cannot explain a hunk out loud.

git diff --name-only "$BASE"...HEAD | wc -l
git diff --stat "$BASE"...HEAD | tail -n 1

If the file count exceeds the ticket's expected paths, revert.
A junior should not debug a thirty-file agent surprise.

Step 3: Choose revert or fix-forward

Use a hard table. Do not improvise under pressure.

Signal	Prefer revert	Prefer fix-forward
Files outside the ticket	Yes	No
Tests red on your branch	Yes	Only if one test fails
Schema or migration changed	Yes	No
Reviewer already approved	Ask first	Maybe
You cannot explain one hunk	Yes	No

If two or more Yes cells fire, revert.
Fix-forward is for a single, obvious typo only.

Write the decision into the same onboarding folder.

cat > .onboarding/rollback-decision.md <<'EOF'
# First PR rollback decision
- Ticket:
- Files outside ticket:
- Tests:
- Migrations:
- Choice: revert | fix-forward
- Why:
EOF

Fill every bullet before you run git revert.
Empty bullets mean you are still guessing, so stop.

Step 4: Revert on a fresh branch

Never reset shared main on day one.
Never force-push a branch others already pulled.

Create a rollback branch from current HEAD.
Revert the merge commit or the PR range.
Keep the original branch for later autopsy.

set -euo pipefail
TICKET="${TICKET:-ONBOARD-0}"
SAFE="rollback/${TICKET}-first-pr"

git switch -c "$SAFE"
# If the PR was a single merge commit:
git revert -m 1 "${MERGE_SHA}" --no-edit
# If the PR was a linear range:
# git revert --no-edit "${BASE}".."${HEAD}"

If revert conflicts, abort and re-read the inventory.

git diff --name-only --diff-filter=U
# After you understand each conflict:
# git revert --abort

Do not ask an agent to resolve conflicts yet.
Conflict markers hide product rules you just learned.

Step 5: Prove the tree matches the base

A revert is not done when git says success.
A revert is done when tests match the base branch.

git fetch origin
git diff --stat origin/main...HEAD

Pin the test command from the README only.
Do not invent npm scripts the agent suggested.

# Proposed example. Replace with the README command.
# npm test
# go test ./...
# pytest -q

If tests fail on the rollback branch, stop shipping.
Your revert missed a generated file or a migration.

Step 6: Open a tiny rollback PR

The rollback PR should contain almost no story.
It should contain the inventory and the decision file.

Title it with the original ticket id.
Link the failed PR in the first line.
Paste the name-status list in the body.

git add .onboarding/first-pr-files.txt \
        .onboarding/rollback-decision.md
git commit -m "revert: ${TICKET} first AI PR"
gh pr create --draft --title "revert: ${TICKET}" \
  --body-file .onboarding/rollback-decision.md

Keep the original PR closed or converted to draft.
Do not delete it; you need the transcript later.

Where a free coding agent still helps

You still need a second pair of eyes on the diff.
You do not need that pair of eyes to rewrite files.

Disclosure: This article was prepared as part of MonkeyCode's product outreach.

MonkeyCode is an open-source coding assistant for local work.
It offers free model access and a free server option.
Use it to narrate the patch, not to apply another patch.

Paste the inventory file and ask for a file-risk list.
Ask which paths look like migrations or generated code.
Then you run git while the agent stays in explain mode.

That split matters on a junior's first hour.
Explanation is cheap, but a second bad patch is not.

A reproducible autopsy script

Save this script under scripts in your clone.
Run it from the repo root on your PR branch.

#!/usr/bin/env bash
# Proposed local helper. Not team policy.
set -euo pipefail

BASE="${1:-origin/main}"
OUT="${2:-.onboarding}"
mkdir -p "$OUT"

git rev-parse --abbrev-ref HEAD > "$OUT/branch.txt"
git diff --name-status "$BASE"...HEAD > "$OUT/name-status.txt"
git diff --stat "$BASE"...HEAD > "$OUT/stat.txt"
git log --oneline "$BASE"..HEAD > "$OUT/commits.txt"

echo "Risky paths:" > "$OUT/risks.txt"
if command -v rg >/dev/null 2>&1; then
  rg -n -i "migration|schema|lock|generated|dist/" \
    "$OUT/name-status.txt" >> "$OUT/risks.txt" || true
else
  grep -Ei "migration|schema|lock|generated|dist/" \
    "$OUT/name-status.txt" >> "$OUT/risks.txt" || true
fi

echo "Inventory written to $OUT"

Label this as a proposed local helper, not team policy.
Your new team may already have a revert runbook.

Commit the script only if the team wants it.
Do not sneak tooling into the rollback PR itself.

Limitations

This workflow assumes you still own the branch.
It assumes main is protected and you can open drafts.

It does not cover broken production traffic today.
It does not cover signed commits you cannot reproduce.

Revert can miss submodule pointers and LFS files.
It can also miss squashed commits on a rewritten branch.

The decision table is a heuristic, not a proof.
Two yes cells do not replace a staff engineer's call.

Free model access will not know your production topology.
A free server will not hold your private incident facts.
Do not paste secrets, tokens, or customer data into prompts.

Who should not use this approach

Skip this if you are not the PR author.
Skip this if the change already shipped to customers.

Skip this if the repo uses a required merge queue.
Talk to the maintainer before any revert there.

Skip this if you cannot run the README test command.
A green revert you cannot test is still a guess.

Juniors on regulated codebases should wait for a buddy.
Pair on the revert and do not solo a schema undo.

Close the loop on hour one

Write three notes before you log off.

What the agent changed outside the ticket.
Which table signal made you choose revert.
Which test command proved the tree was clean.

Those notes become your second-day review checklist.
They also keep the next agent session much smaller.

Practice this workflow on a throwaway clone first.
A free explain-only session can walk the inventory.
Keep every git command in your own terminal.