DEV Community: Quinn Zhu

Let the Existing Tests Choose Your First PR

Quinn Zhu — Tue, 27 Oct 2026 13:22:48 +0000

Your first pull request should be chosen by a test, not by curiosity.

Curiosity sends you to the files that are fun to read. Tests send you to the files that are safe to change. On day one you cannot tell those apart by reading alone.

This drill takes about an hour. It ends with one small PR and a baseline you can actually trust.

Step 0 — Fix your question in one sentence

Write the question down before you open a single source file.

A usable question looks like this: "Does invoice_total() include tax on refunds?" A useless one looks like: "How does billing work?" The first can be answered by a test. The second can absorb your whole week.

Keep the question where you will see it. A line at the top of your scratch branch is enough.

Step 1 — Map which tests already name your file

Pick one candidate file. Then let git tell you who already checks its behavior.

Save this as name-the-test.sh in your scratch clone:

#!/usr/bin/env bash
# name-the-test.sh — find the tests that already mention a file you want to change.
# usage: ./name-the-test.sh src/billing/invoice.py
set -euo pipefail

target="${1:?usage: name-the-test.sh <path/to/file>}"
stem="$(basename "${target%.*}")"

echo "--- test files mentioning '${stem}' ---"
git grep -l -i -- "${stem}" -- '*test*' '*spec*' '*__tests__*' || echo "(none)"

echo "--- tracked files in the same family ---"
git ls-files | grep -i -- "${stem}" | grep -i -e test -e spec || echo "(none)"

echo "--- last three commits touching the file ---"
git log -3 --date=short --format='%h %ad %s' -- "${target}"

Run it against three candidate files, not one. You want options, not a commitment.

./name-the-test.sh src/billing/invoice.py
./name-the-test.sh src/billing/refund.py
./name-the-test.sh src/billing/tax_rules.py

If a file returns zero test references, drop it. A file nobody tests is a file where your mistake is invisible.

Step 2 — Run only those tests, and save the output

Do not guess the test command. Copy it from the repository's own CI config.

grep -rn -A3 'run:' .github/workflows/ | grep -i -e pytest -e 'npm test' -e 'go test'

Then run the single file you found, and write the output to disk:

python -m pytest tests/billing/test_invoice.py -q 2>&1 | tee /tmp/baseline.txt
tail -n 5 /tmp/baseline.txt

That file is now your baseline. Green or red, you know the starting state. Most first-PR confusion comes from never having captured it.

If the run fails on import errors rather than assertions, stop. You have an environment problem, not a code problem.

Step 3 — Turn your question into one assertion

Add a single test that answers your Step 0 sentence. Not three tests. One.

def test_refund_total_excludes_tax():
    invoice = Invoice(amount=100, tax_rate=0.2, refunded=True)
    assert invoice.total() == 100

Run it. It should fail, and the failure message should be readable enough for a stranger.

If the assertion cannot be written without mocking five collaborators, your question is too big. Shrink it until the test fits on one screen.

Step 4 — Make the smallest change that flips the test

One rule keeps first PRs reviewable: at most three files change, and one of them is the test.

If the fix needs a fourth file, split the ticket. State the split in the PR description rather than expanding scope quietly. Reviewers forgive small PRs and small questions; they rarely forgive a surprise refactor.

Re-run the baseline file after the change. Compare with /tmp/baseline.txt and confirm you moved only the test you meant to move.

Step 5 — When your laptop cannot run the suite

Some first days die on environment setup. Python 3.6 on a work laptop, an ARM machine, a Windows shell against a Linux-only suite. The drill above stalls at Step 2 through no fault of yours.

This is where I keep a disposable workspace instead of a permanent one. MonkeyCode offers free model access and a free server option, which is enough for a single-file test run and a failure explanation. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Two habits make that safe:

Send the failure output, not the whole file. Paste the traceback and the test name into the model. Ask "what does this assertion say about the code?" not "rewrite this module."
Keep the free server ephemeral. Clone, run, copy the log back, throw the workspace away. Anything you would not put in a public gist does not belong there.

I am deliberately not quoting quota numbers or machine specs. Free tiers move, and a number printed in a blog post is stale within weeks. Check the project's own page on the day you need it.

The decision table

Situation	Local clone	Free server workspace
Suite runs in under 2 minutes	Use local	Unnecessary
Suite needs a Linux-only binary	Skip	Reasonable
Repo has secrets in `.env` fixtures	Use local only	Do not use
You only need one test file	Use local	Fine either way
You need a long-lived CI replacement	Build real CI	Not this
You want to read a stack trace with help	Use local	Acceptable

Treat the free server as a place to answer one question. The moment it becomes your only way to run tests, you have a dependency, not a tool.

What this drill does not do

name-the-test.sh is a grep heuristic. Dynamic imports, string-built module names, and reflection-based frameworks will hide tests from it. If it returns (none) for a file you know is covered, trust the code and check by hand.

It also assumes a test suite exists. Repositories with no tests need a different first hour, and that is a fair reason to ask your mentor before starting.

Finally, this drill will not teach you architecture. It teaches you where the safety net is. Reading the module top-to-bottom still has to happen, just not before you know which behavior someone already promised to protect.

If you try one thing from this post, try the ordered steps: question, grep, baseline, one assertion, one small diff. If your machine fights you on step two, the free server option is the lowest-stakes place to start.

Score the File, Not the Prompt: A Week-One Triage Table for AI-Assisted PRs

Quinn Zhu — Mon, 26 Oct 2026 11:54:16 +0000

Give the model a ticket only after you score the file.

Most juniors do it backwards. They paste the ticket, accept a patch, then try to understand it. On day one that order costs you your rollback.

This post gives you a small triage script, a decision table, and a baseline test loop. You run all three inside your first hour. The artifact is the point, not the opinion.

The risky window is week one

The tooling changed fast this year. Juniors now open real tickets with an agent in the loop from day two. That is fine, if you gate the loop with evidence.

My rule is simple. Score the file before you score the prompt. A patch is only as safe as the code it touches.

Step 1: Measure the blast radius

Run this on the file you plan to edit. It uses only git, grep, and find.

#!/usr/bin/env bash
# triage.sh - rate a file's blast radius before you take the ticket
set -euo pipefail

file="${1:?usage: triage.sh path/to/file [since]}"
since="${2:-90.days.ago}"
stem="$(basename "${file%.*}")"

churn=$(git log --since="$since" --format=%H -- "$file" | wc -l | tr -d ' ')
owners=$(git log --since="$since" --format=%ae -- "$file" | sort -u | wc -l | tr -d ' ')
refs=$(grep -RIl --exclude-dir=.git --include='*.ts' --include='*.js' --include='*.py' "$stem" . 2>/dev/null | wc -l | tr -d ' ')
tests=$(find . -path ./.git -prune -o -name "*${stem}*test*" -print 2>/dev/null | wc -l | tr -d ' ')

printf 'file=%s\nchurn=%s\nowners=%s\nreferences=%s\ntest_files=%s\n' \
  "$file" "$churn" "$owners" "$refs" "$tests"

Make it executable and run it on your candidate.

chmod +x triage.sh
./triage.sh src/billing/invoice.ts

Sample output from a small service I worked in:

file=src/billing/invoice.ts
churn=14
owners=5
references=9
test_files=2

Read it like this. High churn means the file moves under you. Many owners means no single reviewer knows the whole file. Many references means your typo becomes someone else's outage.

Treat the script as a rough instrument. It measures motion, not correctness. Zero test files is the loudest signal in the output.

Step 2: Turn the numbers into a decision

Do not negotiate with yourself. Map the score to one of three lanes.

Signals	Lane	Who edits	Evidence before PR
tests >= 1, owners <= 2, references <= 3	Green	You, with a model draft	Baseline test log, diff under 60 lines
tests >= 1, but owners >= 3 or references >= 6	Amber	Model drafts, you rewrite	Named reviewer, per-hunk explanation
tests = 0, or references >= 10, or churn is spiking	Red	Senior pairs with you	Written rollback plan first

Red does not mean forbidden. It means you do not learn on the expensive file. Take a green ticket first, then ask for the red one.

Step 3: Write the ticket contract in one paragraph

Before any prompt, write five lines in the ticket. File, function, expected behaviour, test command, and what must not change.

File: src/billing/invoice.ts
Function: applyDiscount()
Expected: rounding stays half-up, no new exports
Test: npm test -- invoice
Must not change: public signature, error messages

Now the model gets a boundary, not a wish. If it returns code that violates line five, you reject it in seconds.

Step 4: Prove the loop before the edit

Run the test command and save the output. This is your baseline, and it is the only honest reference you have.

npm test -- invoice 2>&1 | tee /tmp/base.log
grep -E 'passing|failing' /tmp/base.log

If the suite is already red, stop. A red baseline hides your regression inside someone else's failure.

After the patch, run the same command against the same log target. Compare counts, not vibes.

npm test -- invoice 2>&1 | tee /tmp/after.log
diff <(grep -E 'passing|failing' /tmp/base.log) \
     <(grep -E 'passing|failing' /tmp/after.log)

Identical counts plus your new test passing is a shippable result. Anything else is a conversation.

Step 5: Set the hunk budget and the rollback line

Cap the diff before you open the editor. Forty lines for a first ticket is plenty. Sixty is the ceiling on green files.

Write the revert command in the PR description. It takes ten seconds and saves an hour.

git revert --no-commit <sha>
git diff --cached --stat

If you cannot name the sha you would revert, you do not understand the patch yet. Read the diff again before you request review.

Where free model access and a free server actually help

A junior needs volume, and volume is where budgets bite. Explaining unfamiliar files, drafting a failing test, and re-reading your own diff are high-frequency, low-risk uses. This is exactly the workload free model access fits.

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

Two operator-supplied details matter here. The project offers free model access, and it offers a free server option. The operator also describes a free allowance of 10 million tokens; confirm the current terms yourself, because allowances change and I am not quoting a benchmark. I have not measured speed, model quality, or uptime, and I am not claiming any.

The free server option helps in one concrete way. Your laptop keeps its toolchain, and the build-and-test loop runs elsewhere. That is a real convenience when npm install fights your local Node version.

One rule, no exceptions. Do not paste secrets, customer data, or internal credentials into any hosted model. Read your employer's policy before your first prompt.

Limitations and who should skip this

This workflow is honest about what it cannot do.

Churn is not risk. A quiet file can still hold the payment path.
The script misses dynamic references: reflection, string lookups, config-driven wiring.
Test file counts lie in monorepos with shared fixtures.
Free tiers change. Re-verify terms on the day you rely on them.
A model draft is not a review. You still own every line you commit.

Skip this approach if your repo has no test command at all. Fix that first; a model will only make the chaos faster.

Skip it too if you cannot read the language fluently yet. Learn the file by hand for a week, then add the agent.

Your first-hour checklist

Run the script on two candidate files. Pick the green one. Write the five-line contract. Capture the baseline log. Draft with the model, then rewrite at least one hunk yourself.

That last step is the whole method. You are not shipping model output. You are shipping a change you can explain, test, and revert.

If you run the triage table on your own repo, keep your real thresholds in the PR description. The next junior will thank you for the numbers.

Rehearse the Rollback Before You Ship the Patch: A Day-One Git Drill

Quinn Zhu — Tue, 20 Oct 2026 10:04:29 +0000

Rehearse the Rollback Before You Ship the Patch

Your first pull request should be one you can undo in five minutes.

Most onboarding advice stops at "get the build running." That is step zero. The step that protects you is a rollback rehearsal. You practice undoing a patch while nobody is on call.

This drill uses git, a throwaway remote, and one small patch. You measure time-to-green on three undo paths. You leave with a table, not a feeling.

Why rehearse undoing work you have not shipped

Patches arrive fast now. Reviewing an agent patch is one skill. Undoing it is a different skill, and a calmer one.

If your team already merges agent-generated patches, you will be asked to revert one eventually. First-time reverts under pressure teach the wrong lesson. A sandbox branch teaches the right one.

The drill also exposes something useful about your new repo. You learn which test command is real, how long green takes, and where the seams are.

Step 0: Define "green" before you touch anything

Copy the exact command CI runs. Do not invent your own.

# .drill/test-command
./scripts/test.sh

If that command takes longer than ten minutes, subset it. A drill that costs an hour never gets repeated. Pick the fastest command that still fails when the patch breaks behavior.

Write the command down before the drill. Changing it midway invalidates every number you collect.

Step 1: Move the drill onto a disposable remote

Never rehearse in the repo your team deploys from. A scratch clone is the minimum. A scratch remote is better.

This is where a free server option fits. Treat it as a sandbox for throwaway branches. Assume it can vanish, and assume it is not a place for secrets.

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

MonkeyCode offers free model access and a free server option, and its team describes it as an open-source project. That is how you can generate the patch and host the scratch remote here. Delete every MonkeyCode mention and the git commands below still work unchanged.

Step 2: Generate one small, believable patch

Ask for a bounded change. A 30-line diff reverts cleanly. A 400-line diff teaches you conflict resolution, not rollback.

Prompt template you can reuse:

Change exactly one function in <file>.
Constraints: no new dependencies, no more than 30 changed lines.
Output a unified diff only, no prose.

Save the output as patch.diff. Reject it if it touches more than two files. Reject it again if it adds a dependency. Small patches keep the drill honest.

The patch does not need to be good. It needs to apply, pass tests, and be reversible. That is the whole bar.

Step 3: Script the rehearsal

Save this as rollback-drill.sh. Run it from anywhere except a worktree you care about.

#!/usr/bin/env bash
# rollback-drill.sh <repo-url> <patch-file>
set -euo pipefail

REPO_URL="${1:?repo url required}"
PATCH="${2:?patch file required}"
TEST_CMD="${TEST_CMD:-./scripts/test.sh}"

WORK="$(mktemp -d)"
OUT="$WORK/timings.md"
printf '| path | result |\n|---|---|\n' > "$OUT"

timed() { # timed <label>
  local label="$1" start end
  start=$(date +%s)
  if bash -c "$TEST_CMD" >"$WORK/$label.log" 2>&1; then
    end=$(date +%s)
    printf '| %s | %ss to green |\n' "$label" "$((end - start))" >> "$OUT"
  else
    printf '| %s | RED (see %s.log) |\n' "$label" "$label" >> "$OUT"
  fi
}

git clone --depth 50 "$REPO_URL" "$WORK/repo"
cd "$WORK/repo"
git config user.email drill@example.com
git config user.name drill

git switch --quiet -c drill/base
timed baseline

git switch --quiet -c drill/patch
git apply --3way "$PATCH"
git add -A
git commit --quiet -m "drill: apply patch"
timed patched

# Path A: revert the commit, history stays readable
git switch --quiet -c drill/revert drill/patch
git revert --no-edit HEAD >/dev/null
timed revert

# Path B: drop the commit entirely
git switch --quiet -c drill/reset drill/patch
git reset --hard --quiet drill/base
timed reset

# Path C: kill switch, code stays where it is
git switch --quiet drill/patch
export FEATURE_AGENT_PATCH=off
timed flag_off

cat "$OUT"
echo "logs in $WORK"

Two notes before you run it. Path C only means something if the patch sits behind a flag. If there is no flag, drop that block and record n/a in your table. And --depth 50 keeps a monorepo clone tolerable; remove it if your repo needs full history to build.

Step 4: Run each path three times

One run measures your laptop, not your repo. Three runs show you the noise floor.

If baseline swings by more than a minute, stop. Your suite is flaky, and every later number is decoration. Fix the flake or pick a narrower test command.

Expected shape of the output:

| path      | result          |
|-----------|-----------------|
| baseline  | 42s to green    |
| patched   | 44s to green    |
| revert    | 45s to green    |
| reset     | 41s to green    |
| flag_off  | RED (see flag_off.log) |

A red flag_off row is a real finding. The kill switch does not fully disable the change, or your test command ignores the flag. Both are worth knowing on day one.

Step 5: Read the table like a reviewer

Compare paths on the same machine only. Wall-clock seconds are not portable across hardware.

Look for two signals. First, does any undo path take longer than the patch took to write? Second, does reset beat revert by a wide margin? If yes, you now know why people reach for dangerous commands under pressure.

That gap is the real lesson. revert preserves history and costs conflict resolution. reset is fast and throws work away.

Decision table

Situation	Path	Why	Watch out
Patch is already pushed to a shared branch	`git revert`	Others keep a readable history	Later commits on the same lines conflict
Patch is local and unpushed	`git reset --hard base`	Fastest clean tree	Silently discards uncommitted work
Patch sits behind a flag	flip the flag	Seconds, no deploy	Flag debt, and the off-path is untested
Patch includes a migration	neither, escalate	Code revert is not data revert	You need a restore plan first

Print this table into your onboarding notes. Rewrite it when your repo proves it wrong.

Failure modes that make the numbers lie

Migrations. Reverting code leaves the schema changed. If patch.diff touches a migration, the drill measures the wrong thing entirely.

Cached artifacts. A stale build directory makes reset look faster than it is. Clear the cache before each run, or run baseline twice.

Uncommitted work. reset --hard does not ask. Run the script in the temp clone, never in your working tree.

Wrong test command. If the drill's command differs from CI, you are timing a rehearsal of a rehearsal.

Limitations and who should skip this

You need a test command that finishes in minutes and fails for the right reasons. Without one, build a smoke test first. This drill will not save you.

Skip it if policy forbids pushing repo content to third-party hosts. Run everything locally instead; the script works the same. Skip it if your rollback procedure is a documented incident process with named owners. Training must not shadow the real runbook.

Skip it in monorepos you cannot clone cheaply. A partial clone is fine. A forty-minute clone is not.

Terms snapshot you should verify yourself

Operator-supplied and not independently verified: free model access, a free server option, and a listed allowance of 10 million tokens. Quotas and terms change without notice. Read the project's current page before you plan any workflow around them.

Close the loop

Run the drill once. Keep the timing table in your onboarding notes.

If you try it on a throwaway remote, the free server option saves you from polluting your laptop. Paste your slowest undo path in the comments. A five-minute revert is a team asset, and now you know yours.

Day One: Prove the Build Before You Take the Ticket

Quinn Zhu — Mon, 19 Oct 2026 08:43:48 +0000

Your first hour should prove the build. It should not be reading source code.

Most juniors start onboarding by opening files. That feels productive. It produces opinions, not evidence.

A build that fails on your machine tells you nothing about the code. It tells you about your machine. The fix belongs in a written environment probe, not in a chat thread.

This post gives you that probe. It takes about twenty minutes. It ends with your first PR and a rehearsed rollback.

Why the probe comes first

A failing test on day one has three possible owners. The repo, the toolchain, or you.

You cannot tell them apart from memory. You can tell them apart from a log with versions, commands, and exit codes.

Write the log once. Reuse it for every future "works on my machine" argument.

Step 1: Build a disposable workspace

Do not probe inside your real clone. Use a throwaway directory or a temporary sandbox.

This is where a free server option is genuinely useful. A disposable host gives you a clean OS with no leftover global installs.

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

MonkeyCode offers free model access and a free server option, per the operator. I am not asserting specs, quotas, uptime, or permanence here. Treat both as conveniences, not guarantees.

mkdir -p ~/probe && cd ~/probe
git clone --depth 1 <repo-url> app
cd app
git rev-parse --short HEAD   # record this in your notes

Record the commit hash. A probe without a commit hash is a rumor.

Step 2: Write `probe.sh`

This is a template. It is not tested against your repo. Adjust the install and test commands to match your README and CI config.

#!/usr/bin/env bash
# probe.sh - day-one environment probe (template)
set -euo pipefail

OUT="env-probe.txt"
: > "$OUT"
log() { printf '%s\n' "$*" | tee -a "$OUT"; }

log "== commit: $(git rev-parse --short HEAD) =="
log "== time:   $(date -u +%FT%TZ) =="
log "uname:  $(uname -srm)"
log "shell:  $BASH_VERSION"

for bin in git node npm python3 go java docker; do
  if command -v "$bin" >/dev/null 2>&1; then
    log "$bin: $("$bin" --version 2>&1 | head -n1)"
  else
    log "$bin: MISSING"
  fi
done

log "== install =="
if [ -f package-lock.json ]; then
  npm ci --no-audit --no-fund 2>&1 | tail -n 20 | tee -a "$OUT"
fi

log "== test (300s cap) =="
set +e
timeout 300 npm test --silent 2>&1 | tail -n 40 | tee -a "$OUT"
code=${PIPESTATUS[0]}
set -e
log "test exit: $code"

log "== end =="
exit 0

Two design choices matter here. The timeout cap stops a hung watcher from eating your morning. The tail cap keeps the log small enough to read and share.

The script always exits zero. It is a reporter, not a gate.

Step 3: Read the verdict, not the vibes

Run it and classify the result before you ask anyone for help.

chmod +x probe.sh && ./probe.sh
grep -E 'MISSING|test exit' env-probe.txt

`test exit`	Missing tools	Verdict	Your next action
`0`	none	Green	Take the ticket, link `env-probe.txt` in it
non-zero	none	Amber	Reproduce once in the sandbox, then compare logs
any	one or more	Red	Fix the toolchain first, do not touch code

Green is common and boring. Good. Boring means the repo is not your problem today.

Amber is the interesting case. It means the failure is real and reproducible, which makes it a legitimate ticket.

Red is a setup bug wearing a code bug costume. Half of "the tests are broken" reports die here.

Step 4: Delegate only the log reading

The slow part of onboarding is not typing commands. It is squinting at 40 lines of noise.

This is a reasonable place to use free model access. The task is bounded, the input is small, and a wrong answer is cheap to detect.

Do not ask for a patch. Ask for a classification.

You are triaging a build log. Do not propose code changes.
Input: the last 40 lines below.
Output exactly three lines:
FAILURE_CLASS: <missing-tool | dependency | test-assert | network | unknown>
FIRST_BAD_LINE: <verbatim line>
NEXT_COMMAND: <one shell command to run>

Then run the NEXT_COMMAND yourself. If it does not move the log forward, the classification was wrong and you learned that in one step.

Keep the model's output in your notes with the commit hash. Unlabeled model output is not evidence.

Step 5: Make the probe your first PR

Your first PR should be small, reversible, and additive. probe.sh plus env-probe.txt is all three.

git checkout -b chore/env-probe
git add probe.sh env-probe.txt
git commit -m "chore: add day-one environment probe"

In the PR body, state three things. The commit hash you probed. The verdict from the table. The one command a reviewer should run to confirm.

Do not bundle a source change into this PR. Reviewers forgive a noisy artifact. They do not forgive a mixed diff.

Step 6: Rehearse the rollback now

You will need a rollback eventually. Practice it while the stakes are zero.

git revert --no-edit <merge-or-commit-sha>
git push origin chore/env-probe

If CI rejects the probe script, revert it and say so in the thread. That is a successful onboarding step, not a failure.

You now know the revert command, the review path, and the CI turnaround time. That knowledge is worth more than the script.

Limitations and who should skip this

A sandbox probe proves a fresh environment. It does not prove production behavior, data shape, or service dependencies.

The free server option suits exploration. It is not a substitute for a pinned CI runner or a reproducible container image your team controls.

Skip this approach if any of the following is true.

Your repo needs credentials or production data to build. Do not paste those into a shared sandbox.
Your organization forbids sending logs to hosted models. Ask first, and use a local model if approved.
Your build needs GPUs, large services, or hours of compilation. Use the team's real CI instead.
You need guaranteed capacity. Free tiers change; plan around that.

Also skip the model step entirely if the log is short. Ten lines of output do not need triage help.

What you actually learned

You learned the build before the code. You learned the revert before the mistake.

That order is deliberate. Juniors who learn rollback first take bigger, safer steps later.

If you want a zero-cost place to run the probe, MonkeyCode's free model access and free server option are a reasonable starting point. Verify the current terms yourself before you depend on them.

Timebox Your First PR: A 90-Minute Onboarding Log for New Repos

Quinn Zhu — Fri, 16 Oct 2026 05:26:26 +0000

Most first PRs fail for process reasons, not coding reasons.

The fix is cheap. Log your first 90 minutes in a new repo. Then attach that log to your first pull request.

This post gives you a small bash script, a timebox table, and explicit stop rules. It also explains where a free cloud box fits when your laptop cannot reproduce CI.

Why hour one decides your first PR

You join a repo you have never run. You read code for two hours. You patch something small. Tests pass locally, then fail during review.

The reviewer asks one question. "What was the baseline?" You do not know.

That is the entire failure. The order was wrong, not your skill.

So flip the order. Record first, patch second. Your log becomes evidence a reviewer can replay.

Agent tooling keeps improving. Onboarding discipline has not kept up.

The artifact: a JSONL onboarding log

Save this file as onboard-log.sh on a scratch branch.

#!/usr/bin/env bash
# onboard-log.sh - append JSONL breadcrumbs during your first repo day.
# Usage:
#   ./onboard-log.sh fingerprint
#   TEST_CMD="npm test" ./onboard-log.sh baseline
#   ./onboard-log.sh note "auth tests need redis on 6379"
#   ./onboard-log.sh report
set -uo pipefail

LOG="${ONBOARD_LOG:-onboard.jsonl}"
PHASE="${1:-report}"
shift || true
TEST_CMD="${TEST_CMD:-}"
BASELINE_LOG="${TMPDIR:-/tmp}/onboard.baseline.log"

iso() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
sha() { git rev-parse --short HEAD 2>/dev/null || echo no-git; }

emit() {              # $1 phase, then raw key=value pairs
  local phase="$1"; shift
  local extra=""
  for kv in "$@"; do
    [ -n "$kv" ] && extra="$extra,\"${kv%%=*}\":\"${kv#*=}\""
  done
  printf '{"at":"%s","phase":"%s","head":"%s"%s}\n' \
    "$(iso)" "$phase" "$(sha)" "$extra" >> "$LOG"
}

case "$PHASE" in
  fingerprint)
    emit fingerprint "bash=${BASH_VERSION%%(*}" "node=$(node -v 2>/dev/null || echo none)"
    ;;
  baseline)
    [ -n "$TEST_CMD" ] || { echo "set TEST_CMD first" >&2; exit 2; }
    t0=$(date +%s)
    bash -c "$TEST_CMD" >"$BASELINE_LOG" 2>&1
    code=$?
    emit baseline "exit=$code" "secs=$(( $(date +%s) - t0 ))"
    echo "baseline exit=$code  log=$BASELINE_LOG"
    ;;
  note)
    emit note "note=${1:-}"
    ;;
  report)
    [ -f "$LOG" ] || { echo "no log yet" >&2; exit 1; }
    awk -F'"' '{for(i=1;i<=NF;i++) if($i=="phase") print $(i+2)}' "$LOG" \
      | sort | uniq -c
    tail -n 1 "$LOG"
    ;;
  *)
    echo "phases: fingerprint baseline note report" >&2; exit 2 ;;
esac

Four phases, four commands. Run them in this order.

Fingerprint the machine before you read any code.

./onboard-log.sh fingerprint

Branch from main and record the baseline on a clean checkout.

git switch -c onboard/scratch main
TEST_CMD="npm test" ./onboard-log.sh baseline

Write notes while reading. Do not edit product code yet.

./onboard-log.sh note "auth suite needs redis on 6379"

Print the summary before you open the PR.

./onboard-log.sh report

The report prints one count per phase plus the last entry. A reviewer can replay your first hour in seconds.

Timebox the day in five windows

Window	Action	Exit condition
0-20 min	fingerprint + find the test entry point	you can name the test command
20-35 min	baseline on a clean checkout	exit code written to the log
35-55 min	write one failing test	it fails for the right reason
55-80 min	patch the smallest path	new test passes, baseline still passes
80-90 min	open the PR with the log	reviewer sees one behavior change

Stop at the window boundary. Say what you finished and what comes next. That message beats a rushed patch.

Three ways this goes wrong

Baseline is red on a clean checkout. Stop immediately and report it. Do not fix it in your first PR.

Baseline is green only on your machine. Your fingerprint line will show a different runtime. Fix the environment, not the test.

Your log has no baseline entry. The PR cannot be judged. Skipped steps are invisible, so leave a note instead.

Where a hosted box fits

Some repos will not build on a laptop. Old Node versions, native modules, a database you cannot install locally.

That is the honest use case for a remote environment. Run the fingerprint and baseline steps on a free hosted box, then copy onboard.jsonl back into your branch.

MonkeyCode is an open-source coding-agent project that, per its maintainers, offers free model access and a free server option. Its site currently lists a free token allowance; treat that figure as current-at-writing and verify it on the project's own page before you plan around it.

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

The value here is narrow and testable. The remote box removes environment noise from step 2. Free model access helps only with small questions, like "which fixture seeds this table?" Keep those answers in your notes.

Do not route security review or architecture decisions through a chat box. That work stays with you.

Limits and who should skip this

The script needs bash 4 or newer and a repo with one test command. Monorepos with per-package commands need one baseline entry per package.

Notes containing quotes get mangled by the simple escape used here. Keep notes plain ASCII, or store them elsewhere.

Skip this if your repo holds regulated or proprietary code and you have not read the hosting terms. Skip it if your team already has a trusted CI baseline. Skip it if you need a decision today, because a log costs 90 minutes.

If you want a box for step 2 without provisioning one, MonkeyCode's free tier is one option to evaluate. The log file is the part that matters.

What to take away

Record before you patch. Timebox every window. Stop when the log tells you to stop.

Your first PR should be small, explainable, and replayable. This log makes all three true.

Your First Hour in a New Repo: Build a Reading Order from Git History

Quinn Zhu — Thu, 15 Oct 2026 11:29:37 +0000

Conclusion first: do not read a new repo alphabetically

You join a repo on Monday. Nobody has time to walk you through it. So you open the file tree and start at the top.

That is the slowest path through a codebase. Files that change together belong together. Git already recorded which files move as one unit.

Read the coupled files first and the architecture appears faster. This workflow has three steps: extract co-change pairs, expand them into a reading order, then use an agent to cover what you cannot read in time. Setup costs about fifteen minutes.

The scripts below are templates. Run them in your own clone and treat the ranking as a hypothesis to verify.

Step 1 — Extract co-change pairs from commit history

A commit that touches checkout.ts and cart.ts is evidence of a relationship. Repeat that across a year of history and the strong edges stand out from the noise.

Limit the window to 12–18 months. Older commits describe code that no longer exists.

# Dump one commit per NUL byte, followed by the file names it touched.
git log --no-merges --since="18 months ago" \
  --pretty=format:'%x00' --name-only > /tmp/cochange.log

wc -l /tmp/cochange.log   # sanity check: is this file absurdly large?

Now count the pairs.

# cochange.py — rank file pairs by how often they change together
import collections, itertools, subprocess

IGNORE = ("vendor/", "node_modules/", "dist/", "third_party/", ".lock")

raw = subprocess.run(
    ["git", "log", "--no-merges", "--since=18 months ago",
     "--pretty=format:%x00", "--name-only"],
    capture_output=True, text=True, check=True).stdout

pairs = collections.Counter()
touched = collections.Counter()

for chunk in raw.split("\x00"):
    files = {f.strip() for f in chunk.splitlines() if f.strip()}
    files = {f for f in files if not f.startswith(IGNORE)}
    if len(files) < 2:
        continue
    for f in files:
        touched[f] += 1
    for a, b in itertools.combinations(sorted(files), 2):
        pairs[(a, b)] += 1

for (a, b), n in pairs.most_common(20):
    print(f"{n:4d}  {a}  <->  {b}")

Check two things before you trust the output. First, generated files and lockfiles dominate raw counts, so keep the ignore list honest. Second, squash-merged history turns every commit into a whole feature, which flattens the pair counts.

The --no-merges flag hides merge commits. That is usually what you want. If your team merges feature branches without squashing, drop the flag and compare the two outputs.

Step 2 — Expand one seed into a reading order

The top pair is a starting point, not a plan. Expand outward from the most frequently touched file and stop after roughly a dozen files.

# Continue in the same script: walk the coupling graph.
import collections

neighbors = collections.defaultdict(collections.Counter)
for (a, b), n in pairs.items():
    neighbors[a][b] += n
    neighbors[b][a] += n

seed = touched.most_common(1)[0][0]

order, seen = [seed], {seed}
while len(order) < 12:
    best, score = None, 0
    for recent in order[-3:]:            # weight the last few picks
        for cand, w in neighbors[recent].items():
            if cand not in seen and w > score:
                best, score = cand, w
    if best is None:
        break
    order.append(best)
    seen.add(best)

print("\nreading order:")
for i, f in enumerate(order, 1):
    print(f"{i:2d}. {f}")

Greedy expansion is a heuristic. It can wander into a test-only cluster and stall there. If the list looks wrong, change the seed to a file you already know matters.

Then write the plan down with a stop condition for each block.

Time	Target	Stop when
0:00–0:20	top 3 coupled files	you can name the entry point and its caller
0:20–1:00	full pair list	you can draw five arrows between modules
1:00–2:00	one end-to-end test	the test passes locally and you know what it asserts
2:00–3:00	agent summaries of the rest	every claim is checked against code or a test

The third row matters most. A reading order you cannot run is still a guess.

Step 3 — Use an agent for the files you cannot reach

You will not read 200 files on day one. Hand the ranked list to a coding agent and ask for narrow, checkable answers.

MonkeyCode offers free model access and a free server option, which makes this step cheap to try from a work laptop. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Keep the prompt narrow. Broad questions produce broad guesses.

For each file listed below, answer in at most four lines:
1. Which files in this repo reference it? Give file:line, or "not found".
2. What does it return or mutate?
3. Which test exercises it? Give the test name, or "no test found".
4. What would break if this file were deleted?

Files:
<paste the reading order here>

"Not found" and "no test found" are the most useful answers. They mark the edges of the repo's documented behavior.

Step 4 — Verify before you believe

Agent output is a hypothesis, not a fact. Three commands settle most of it.

# Does the caller really exist?
grep -rn "parseCheckout" --include="*.ts" src/ | head

# Is this file actually alive?
git log -1 --format='%h %ad %an' --date=short -- src/cart.ts

# Does the claimed test exist, and does it pass?
npm test -- --testPathPattern cart

If the grep finds nothing, the agent invented the caller. If the last commit is four years old, the file is probably dead code, not core logic.

Record each verified fact in one note file. That note becomes the onboarding document for the next hire, which is a better gift than a Slack summary.

Your first PR comes from the gaps

The "no test found" list is your backlog. Pick one small function and add the missing test. It is a real contribution, it is low risk, and it forces you to run the code.

Do not refactor anything in week one. You do not yet know which odd-looking code is load-bearing.

Limitations and who should skip this

Repos under about 40 files: just read them all in one sitting.
Squash-merge-only history: co-change counts flatten, so pair ranking gets weak.
Heavy vendoring or generated code: your ignore list does most of the work.
Teams without a working local test command: verify by reading code instead.
Anyone who cannot review agent output critically: skip Step 3 entirely.

Do not hand security-critical paths to an agent on day one. Read those yourself, slowly.

The pair list also says nothing about runtime behavior. Two files can co-change because a formatter touches them together, not because they are coupled. Skim the commit messages for the top pairs before you build a mental model on them.

What to do next

Run Step 1 on the repo you joined this week. Paste the top ten pairs into your notes. You now have a reading order, a verification habit, and a first PR candidate.

If your laptop cannot spare the cycles for Step 3, MonkeyCode's free server option is one way to move that work off your machine.

Scan the Diff Before You Request Agent Review

Quinn Zhu — Tue, 13 Oct 2026 02:28:31 +0000

Do not request review on an agent patch yet.
A leaked secret outlives a bad function name.
Scan the diff, then write a replay note.

Start from the review gate

You are the new engineer on this repo.
Your first pull request should stay very small.
An agent may draft the patch for you.

You still decide what reviewers are allowed to see.
Treat the agent summary as an unverified claim.
Every claim needs a command you can rerun.

A confident paragraph is not evidence at all.
You need a command log beside that paragraph.
Git output beats a polished explanation every time.

Keep this hour narrow

Change only one behavior during this first hour.
Touch only the files that this behavior needs.
Leave lockfiles and migrations alone unless the ticket names them.

Do not explore the whole tree on this branch.
Do not ask the agent to clean unrelated files.
Wide diffs hide secrets and unrelated edits together.

Step 1: Freeze the base ref

Pick the base branch that reviewers already trust.
Write that ref down before you edit anything.
Do not guess the base ref from memory later.

git fetch origin
git rev-parse --abbrev-ref HEAD
git merge-base HEAD origin/main
git status --short

Stop if your working tree is not clean.
Stop if the base ref is missing locally.
A dirty tree makes this scan meaningless now.

Replace origin/main if your default branch name differs.
Ask a teammate for the real base name.
Do not invent a base just to pass.

The three-dot diff starts at the merge base.
It shows changes your branch introduced, not upstream noise.
A two-dot diff can blame files you never edited.

Step 2: Keep secrets out of the prompt

Never paste env file contents into a chat.
Never paste private keys, tokens, or customer rows.
Name the file path when the agent must avoid it.

Say which files the agent is allowed to touch.
Say which commands the agent is allowed to run.
Say that unknown files must stay completely untouched.

A free model does not make a secret safer.
The secret already left your machine in that paste.
Treat every prompt as a copy you may not recall.

Step 3: Run a diff scan before review

This script is only a proposal for you.
It is an unexecuted example for your branch.
Adapt the base ref and path rules first.

#!/usr/bin/env bash
# Unexecuted example. Review it before you run it.
set -euo pipefail

base="${1:-origin/main}"

if ! git rev-parse --verify "$base" >/dev/null 2>&1; then
  echo "FAIL: base ref not found"
  exit 2
fi

files="$(git diff --name-only "${base}...HEAD")"

if [ -z "$files" ]; then
  echo "FAIL: empty diff against $base"
  exit 2
fi

echo "FILES:"
printf '%s\n' "$files"

blocked='(^|/)(\.env|\.env\..*|id_rsa|id_ed25519|.*\.pem|.*\.p12|.*\.key|credentials\.json|secrets\.ya?ml)$'

if printf '%s\n' "$files" | grep -E "$blocked"; then
  echo "FAIL: sensitive path in diff"
  exit 1
fi

pattern='AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----|ghp_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}'

if git diff --unified=0 "${base}...HEAD" | grep -E -q "$pattern"; then
  echo "FAIL: possible secret text in diff"
  echo "Do not print the match in a shared log."
  exit 1
fi

echo "PASS: no blocked path or obvious token pattern"

Save the script outside the repository if possible.
Run it with the base ref as its argument.
Read each failure before you silence the script.

bash scan-first-diff.sh origin/main

A pass is not a full security audit.
It catches obvious paths and a few token shapes.
Your team scanner still matters when you have one.

The failure path can still reveal a secret nearby.
Run the scan in a private terminal, not a shared log.
If a real secret appears, rotate it with the owner.

Step 4: Use a decision table

Read this table before you push the branch.
Act on the row that you actually hit.
Do not blur two rows into a maybe.

Scan result	What you do	What you do not do
Sensitive path listed	Remove that file from the branch	Ask the model to ignore it in prose
Token-like text in the diff	Tell the credential owner and rotate	Hide the line and hope review misses it
Empty diff	Stop and restate the one behavior	Open review only to show effort
Pass, but a hunk is unexplained	Drop that hunk or ask a human	Ship the model explanation as your own
Pass, and you can replay the test	Write the replay note next	Add extra files for completeness

A shared branch needs a teammate before any rewrite.
This table does not teach you to force-push.
Ask the owner before you rewrite any public history.

Step 5: Fix a failure without hiding it

Do not delete the failing line from the log.
Copy the flagged path, then remove it from the branch.
Commit that removal before you rerun the scan.

If the file is new, delete it from the branch.
If the file is tracked, restore the base version with help.
Do not hide a flagged path inside gitignore.

Rerun the same script after that fix lands.
A second pass still needs the replay note.
Do not request review from a failing log.

Step 6: Write the replay note

Put this note in the pull request body.
A reviewer should rerun your checks without guessing.
Keep each line short enough to verify quickly.

## Replay note

- Base ref: origin/main
- Branch: your-branch-name
- One behavior: one sentence you can defend
- Allowed paths: list only those paths
- Command run: the exact test command
- Scan result: pass or fail, plus script name
- Not run: anything you skipped on purpose
- Model claim you rejected: one sentence, or none

Fill every line using your own words only.
Do not paste an agent summary over those lines.
If any line is unknown, the review is early.

Step 7: Use a remote run only as a tool

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

MonkeyCode offers free model access and a free server option.
Both are availability claims supplied for this article, not measured results.
Current quotas, hardware, and time limits are not stated.

Check the current product docs before you rely on either.
Those offers can change, and this article will not track them.
Do not plan a deadline around an unverified limit.

Use the free model to draft replay note wording.
You still type the commands and read the output.
Use a free server only when your team allows that workspace.

Do not upload secrets so a remote scan looks better.
The scan should see the diff, not your password store.
If that workspace is unclear, run the script locally.

Read the current MonkeyCode docs before any remote run.
Try the scan on a branch you can delete.
Stop if the docs disagree with this article.

Step 8: Reject a yes from the model

Ask the agent which checks it actually skipped.
A short approval line is not a real scan.
Compare its file list with git diff output.

If those lists differ, believe git every time.
If the agent reports no secrets, rerun the script.
If you cannot explain a line, drop that line.

This is the habit you want on later reviews.
Your first review is where that habit starts.
Reviewers teach faster when your note stays honest.

Who should skip this workflow

Skip this if CI already blocks secret paths.
Follow that gate instead of a second unofficial script.
Skip this if you cannot open pull requests yet.

Skip this flow during an active production incident.
Incident work needs the on-call owner, not a first-hour test.
Skip this if the ticket requires production credentials.

That ticket needs a human owner, not an agent run.
You are still learning the review path on purpose.
An incident is the wrong classroom for this script.

Limits you should say out loud

The pattern list misses many private token formats.
It misses secrets that are split across lines.
It misses tokens that do not match these shapes.

The path list misses custom secret file names.
Add the secret names your repository actually uses.
Do not delete a team rule to match this example.

The script does not rotate any credential for you.
The script does not prove that your test passed.
The script does not make the agent accountable.

This example was not run against your repository.
Treat the listing as a starting point only.
Change it until a teammate accepts the blocked paths.

Before you request review

Run the scan and keep the last lines.
Paste the replay note in your own words.
Read the full diff with the agent closed.

Request review only when all three answers hold.
You can name the base ref from the command output.
You can name the exact test command you ran.

You can name every file you would defend.
If one answer fails, keep the branch in draft.
Fix that gap, or close the branch and start smaller.

A delayed first review is cheaper than a leaked key.
Leave the draft closed until those answers are easy.
Your name is on the pull request, not the model's.

Score Every Hunk Before Your First Agent PR

Quinn Zhu — Sun, 11 Oct 2026 21:57:16 +0000

You should not open your first agent pull request blind. Score every changed hunk before you request human review. A fluent model reply is not evidence of safety.

You joined this repo as a junior during hour one. You still lack a map of risky paths. An agent can still draft a wide patch quickly.

This hour is for a gate, not for a demo. You will build a packet you can defend. You will refuse the pull request when a score fails.

Hold the boundary first

Keep the agent run off your real pull request branch. Bring back a diff, a test note, and a revert line. Leave secrets, tokens, and production configs out of the prompt.

Do not allow edits under CI workflows during this pass. Do not allow lockfile edits or migration files either. Those paths need a senior review, not a first hour guess.

Name the tool without inflating it

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

MonkeyCode enters here as one place to run that first pass. The operator supplied two availability claims for this draft. Those claims are free model access and a free server option.

This draft does not name any specific model. This draft does not state a token quota. It also does not state hardware, duration, or uptime.

Check the project docs on the day you run the tool. If the docs disagree with this article, trust the docs. A review habit should not pretend to be a product spec.

Use the free server so your laptop clone stays untouched. Use free model access so a bounded retry stays cheap. Still copy the patch home and score it locally.

Shape the prompt before the call

Write the prompt as four short constraints, not a story. Name the ticket line, the allowed files, the forbidden paths, and the test command. Refuse any reply that skips one of those four.

Ticket: reject empty names in parseName.
Allowed: src/parseName.js src/parseName.test.js
Forbidden: .github migrations package-lock.json .env
Test: npm test -- src/parseName.test.js
Output: a patch only. Do not commit.

Keep that prompt in the scratch notes beside the packet. If you change the prompt, change the notes too. A later reviewer should see the exact ask.

Add a local score script

Save the checker below before you call any model. This script is a proposal, not an executed benchmark. Adapt the blocked path list to your repository.

#!/usr/bin/env bash
# proposal: unexecuted junior gate for an agent diff
set -euo pipefail

BASE="${1:-origin/main}"
MAX_FILES="${MAX_FILES:-8}"
MAX_LINES="${MAX_LINES:-200}"

git rev-parse --is-inside-work-tree >/dev/null
FILES="$(git diff --name-only "${BASE}...HEAD" || true)"
COUNT="$(printf '%s\n' "$FILES" | sed '/^$/d' | wc -l | tr -d ' ')"
STAT="$(git diff --numstat "${BASE}...HEAD" || true)"
ADDED="$(printf '%s\n' "$STAT" | awk '{s+=$1} END {print s+0}')"
DELETED="$(printf '%s\n' "$STAT" | awk '{s+=$2} END {print s+0}')"
LINES=$((ADDED + DELETED))

echo "files=${COUNT} lines=${LINES}"

fail=0
if [ "$COUNT" -gt "$MAX_FILES" ]; then
  echo "FAIL too many files for hour one"
  fail=1
fi
if [ "$LINES" -gt "$MAX_LINES" ]; then
  echo "FAIL diff too large for hour one"
  fail=1
fi

BLOCK='(^|/)(\.github/workflows/|migrations/|.*lock$|\.env|credentials?)'
if printf '%s\n' "$FILES" | grep -E "$BLOCK"; then
  echo "FAIL blocked path present in diff"
  fail=1
fi

if [ ! -f REVIEW_PACKET.md ]; then
  echo "FAIL missing REVIEW_PACKET.md"
  fail=1
else
  grep -q '^Revert: ' REVIEW_PACKET.md || { echo "FAIL missing Revert line"; fail=1; }
  grep -q '^Test: ' REVIEW_PACKET.md || { echo "FAIL missing Test line"; fail=1; }
  grep -q '^Unknown hunks: 0$' REVIEW_PACKET.md || { echo "FAIL unknown hunks remain"; fail=1; }
fi

exit "$fail"

Run the checker from the scratch branch after you pull the patch. Pass the base ref your team actually uses. Do not open a pull request when the exit code is nonzero.

chmod +x scripts/score-agent-diff.sh
MAX_FILES=8 MAX_LINES=200 ./scripts/score-agent-diff.sh origin/main
git diff --stat origin/main...HEAD

Read the stat output even when the script passes. A rename can still hide a large rewrite. Your own eyes still have to close the gate.

Write the packet yourself

Create REVIEW_PACKET.md in the scratch branch before review. You write every line in that packet yourself. Do not accept an agent-written packet as your own note.

Ticket: ISSUE-123
Test: npm test -- workspace/foo.test.js
Revert: git revert <merge-sha>
Unknown hunks: 0
Risk: parser change only, no schema edit

The test line must name a command you actually ran. If you have not run it, write Test not run and stop. A missing run is a failed gate, not a minor note.

The revert line must be a command you understand today. If revert would need a data backfill, stop the pull request. Hour one is the wrong time for that class of change.

Follow these eight steps

Copy the ticket acceptance line into your prompt notes.
Create a scratch branch that is not your pull request branch.
Start the agent on the free server option, without secrets.
Limit the prompt to files the ticket actually needs.
Pull the patch back and run the score script locally.
Run the test command and record the real result.
Set unknown hunks to zero only after you explain each hunk.
Open the pull request only when the script exits zero.

Stop the run if the agent edits a file you did not name. Stop again if the summary mentions a file absent from the diff. Those mismatches mean the packet is not ready.

Use this decision table

Do not bargain with a failed row during hour one. Split the work now or discard the scratch branch. Ask a senior when the row is outside your map.

Signal	Score	Your move
Eight files or fewer	Pass	Continue to the test line
More than 200 changed lines	Fail	Split the patch or discard it
Blocked path in the diff	Fail	Reset the scratch branch
Test command not run by you	Fail	Run it, or do not open the PR
Unknown hunk count above zero	Fail	Read again or drop that hunk
Revert line you cannot explain	Fail	Write a real revert or stop
New dependency or workflow edit	Fail	Hand the ticket to a senior

A passing size score is not a passing meaning score. You still need to read each hunk in order. Opaque code stays a fail until you can teach it.

Walk one sample hunk

Imagine the ticket says the parser should reject an empty name. The agent changes parseName and also reformats the README file. You score the parser hunk as related to the ticket.

You score the README hunk as unknown, then you drop it. That parser hunk matches the ticket, so it can stay. You still run the named test before you open any pull request.

- if (!name) return null;
+ if (!name || !name.trim()) throw new Error("empty name");

Treat this diff as an illustration, not as a result from your repo. Replace the function names with the files your ticket names. Keep the same pass or fail questions on every hunk.

Read hunks in a fixed order

Open the diff one file at a time. Ask what user-visible behavior changed for this ticket. If the answer needs a guess, mark that hunk unknown.

Watch for formatter noise spread across unrelated files. Watch for a new helper that the ticket never requested. Watch for a comment that hides a behavior change.

Compare the agent summary with the name-only diff output. Every file in the summary should appear in that list. Every file in the list should appear in your notes.

Keep the free options in their lane

The free server is only for the noisy first pass. Keep private fixtures and credentials off that machine. Copy a patch back, not a live environment.

Free model access can make a second prompt cheap. Change the constraint before you retry the same ask. A retry without a new limit is usually noise.

This article states no token total and no expiry date. Those facts were not supplied as verified numbers. Read the current docs before you plan a long session.

If your team bans external coding agents, stop here. Do not treat a free tier as a policy workaround. Ask your lead before you send the first prompt.

Know the checker limits

The block regex is a starter, not a complete risk map. Add your real danger paths before you trust a pass. A green script can still miss a risky file name.

Numstat sums ignore binary files and some renames. Run git diff stat when those numbers look too small. Trust the strange stat over the cheerful summary.

A free server may lack your private test fixtures. A pass on that server can still fail in CI. Prefer the pinned CI command when you can run it.

Skip this flow in these cases

Skip the flow when the ticket needs production data. Skip it when you cannot read the language yet. Skip it when the change is a release or a migration.

Skip it when you need a guaranteed quota or support contract. This draft does not establish either of those promises. Use an approved internal tool when the ticket is urgent.

Skip it when the diff is already on a shared branch. Hour one should not repair a public mistake with another agent pass. Revert first, then review the result with a human.

Leave with a defendable pull request

Your first pull request should stay small enough to explain aloud. The score script is the defense you can show. The model only drafted the patch you scored.

If you use MonkeyCode for that first pass, read the current notes. Confirm the free-access terms on the day you actually run it. Then run the local gate before you ask anyone for review.

Gate Your First Agent Patch on a Stable Failure Log

Quinn Zhu — Sat, 10 Oct 2026 18:42:54 +0000

Save the failing command before any agent edits your repo. A first PR should start from a bundle, not a chat guess. That bundle holds a script, two logs, and a base SHA.

Start from the failure

You join the repo and the ticket already sounds urgent. Someone suggests an agent can patch the bug before lunch. You paste the issue text and accept the first diff.

The reviewer cannot replay that chat on their machine. You also cannot defend a rollback if main breaks later. Hour one should prove the failure, not invent the fix.

What you leave behind

You will finish the hour with a small repro directory. It contains a script, two logs, a SHA, and a note. The script must fail the same way on two clean runs.

You do not open a pull request during this hour. You do not let an agent write files before those runs.

Keep the names stable so a reviewer can find them fast. Do not rename logs after you paste one into a prompt.

repro/
  START_SHA
  NOTE
  run.sh
  run-1.log
  run-2.log
  log.diff
  PROMPT_LOG
  run-3.log

1. Freeze the starting SHA

Clone the repository into a new directory on a clean host. Do not reuse a laptop checkout full of old builds. Check out the default branch your team already documents.

Record the commit SHA before you install extra tools. That file is your anchor if the patch needs a revert. Do not update the SHA after you start the two runs.

mkdir -p repro
git rev-parse HEAD | tee repro/START_SHA
printf '%s\n' "ticket: <id>" "command: <paste from CI>" > repro/NOTE

If the branch moves, start the bundle over from clone. A moved base makes the later diff harder to explain.

2. Copy the command, not the story

Open the ticket and the newest failing CI log. Copy the exact command that failed, including its working directory. Do not shorten the command so the run feels faster.

Pin package scripts if CI called those scripts by name. Write unknown flags down instead of guessing their meaning.

cat > repro/run.sh << 'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd "$(dirname "$0")/.."
# Replace the next line with the exact CI command.
npm test -- workspace/parser
EOF
chmod +x repro/run.sh

Treat that file as a template until the real command lands. If the log names a setup step, put that step first. Keep secrets out of the script and out of the note.

3. Run the script twice on a clean host

A laptop cache can hide the bug you are chasing. Run both attempts on a throwaway host instead. A clean host is enough for this narrow check.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option. Use that server only as the clean host for these two runs.

Use free model access only after the logs match. Do not assume a model name, a quota, or a machine size. Those details are not stated here because they can change.

Read the current product docs before you depend on access. Confirm the live limits before you store anything there. Treat current access as optional, not as a lasting promise.

Run the script once and keep every line of output. The true fallback keeps the shell alive after a failed test. You still want the log when the command exits non-zero.

./repro/run.sh > repro/run-1.log 2>&1 || true

Wait a minute, then run the same script again. Save the second log beside the first one. Diff the logs before you decide the failure is real.

./repro/run.sh > repro/run-2.log 2>&1 || true
diff -u repro/run-1.log repro/run-2.log > repro/log.diff || true

Stop when the logs disagree in a meaningful way. A flaky failure is a bad target for your first PR.

Write the mismatch in the ticket and ask a human. Do not ask a model to hide flake with retries.

4. Read the log before you prompt

Read the log from the bottom, not from the top. Find the first error that names a file and a line. Ignore warnings that also appear on a green main build.

If you cannot tie the error to a file, stop here. A vague failure needs a human, not a generated patch.

tail -n 40 repro/run-2.log > repro/PROMPT_LOG

5. Ask for a patch only after the logs match

Open a chat only after the two logs agree. Attach the script, the SHA, and the second log. Ask for a patch that makes this script pass.

Ask for the file list before you ask for code. Reject any reply that ignores the script you saved. Keep the prompt short so a free model can answer.

Trim the saved log before you paste it into a chat. Forty lines is a starting cap, not a measured limit. Never paste tokens, customer rows, or private URLs.

Base SHA: <paste repro/START_SHA>
Command: ./repro/run.sh
Failure log: <paste repro/PROMPT_LOG>
Constraint: change the smallest set of files.
Do not add dependencies.
Return a file list, a patch, and one short reason.

If the ticket needs those, use the private runner. Treat the answer as an unexecuted proposal, not a result. You still have to apply it and rerun the script.

6. Apply it on a branch and rerun

Create a branch from the SHA you already recorded. Apply a short patch by hand so you see each hunk. Do not apply a patch that adds new dependencies.

Run the same script and save a third log. Compare the second log with the third log yourself. The old error text should be gone in the third log.

git checkout -b junior/repro-fix "$(cat repro/START_SHA)"
# Apply the reviewed patch by hand, then:
./repro/run.sh > repro/run-3.log 2>&1 || true

Other tests in that command should not start failing. If they fail, revert the branch and keep the bundle. Map every hunk to a line in the failure log.

git diff --stat "$(cat repro/START_SHA)"

If a hunk has no story, the patch is too wide. Cut the extra files and ask for a smaller patch.

7. Write the PR so a stranger can replay it

Open the PR only when you can narrate the diff. Put the script path and the base SHA in the body.

Name the command you ran and the log you compared. Invite review of the bundle, not praise of the agent.

## Repro
- Base SHA: <paste>
- Script: repro/run.sh
- Compared: repro/run-2.log and repro/run-3.log

## What changed
- <file>: <one sentence tied to the error line>

## Rollback
- Revert this branch if a hunk cannot be explained.

8. Roll back the same day if the story breaks

Roll back the same day if review exposes a gap. A clean revert is better than a clever unexplained patch. Follow your team's revert rule if the merge was squashed.

# Use your team's documented revert path after merge.
git revert --no-edit <merged-commit>

Leave the bundle in the ticket after the revert. The next person can rerun it without your laptop. Do not delete the logs just because the PR closed.

Decision table

Use this table as a gate before you push. It is a checklist, not a scoreboard for speed.

Signal	Action
Two logs match and name one error	Ask for a small patch
Logs differ, or the run hangs	Stop and ask a human about flake
Patch touches files outside the stack	Reject it and re-ask with a file cap
Script passes but one hunk has no story	Revert and do not merge
Ticket includes secrets or production data	Do not use an external host or chat

Print the table and keep it next to the ticket. If a row says stop, stop before you prompt again.

Limits to say out loud

This method fits one failing command with a stable log. It does not fit races, load tests, or hardware bugs. Two matching runs do not prove a rare crash is gone.

A free server may sleep, throttle, or disappear later. Do not call that host your team's continuous integration. Do not store credentials or production dumps on it.

Free model access may reject a very long log. Trim to the failing section and send that slice only. The commands in this article are an unexecuted example.

They are a workflow to adapt, not a measured benchmark. No timings, pass rates, or hardware claims belong here.

Who should skip this

Skip this if your team forbids external code hosts. Skip this if the bug needs a private dataset. Skip this if you are on call for a live incident.

Senior engineers chasing a multi-service outage need another plan. New hires with a documented unit-test failure are the fit. If your mentor already owns the patch, pair with them.

Close the hour

Hour one ends with a bundle, not a hero patch. Save the SHA, the script, and two matching logs.

Ask for a patch only after that evidence exists. If the diff outruns your explanation, revert it today.

If you already have that free server, run the two checks there. Keep the prompt tied to the saved logs only. Check the docs your team trusts before you rely on availability.

Classify Repo Paths Before Your First Agent Prompt

Quinn Zhu — Fri, 09 Oct 2026 15:02:39 +0000

Classify Repo Paths Before Your First Agent Prompt

Your first agent prompt needs a written path map. A junior can leak secrets with one careless paste. Classify every path before any model sees the repo.

This hour is about refusal, not about shipping a fix. You will build a small path classifier first. You will not prompt until that map is green.

What hour one can break

You just cloned a repo you barely know. The agent offers to look around and fix tests. That browse can read tokens and customer fixtures.

A hosted model may retain what you upload. A free server is still someone else's computer. Treat both as untrusted until policy says otherwise.

Three buckets, one decision

Give every path one bucket before you prompt. Read-only context may be summarized, not edited. The sandbox is the only tree the agent may change.

Forbidden paths never enter the prompt or the upload. Env files, key files, and prod configs belong there. If you feel unsure, mark the path forbidden.

1. Freeze a toy tree

Do not point this drill at a production clone. Use a fixture repo your lead already approved. Create a branch that nobody will merge today.

git switch -c onboard/path-map
mkdir -p sandbox fixtures/secrets docs
printf 'Toy repo for a path-map drill.\n' > README.md
printf 'print("ok")\n' > sandbox/hello.py
printf 'TOKEN=replace-me\n' > fixtures/secrets/.env
printf 'Not a real secret.\n' > docs/notes.md

Those sample files are examples, not live secrets. Delete the fixture when the drill is done. Never copy a live credential into this tree.

2. Write the rule file

Keep rules in the repo only with lead approval. Otherwise store the map in your private notes. Start from a plain text file named path-map.txt.

# path-map.txt - example rules, edit before use
read_only:
  README.md
  docs/
sandbox:
  sandbox/
forbidden:
  .env
  .env.*
  fixtures/secrets/
  *.pem
  infra/prod/
local_tool:
  path-map.txt
  classify-paths.sh
  path-report.txt

Put one rule on each line for easy review. A glob you cannot explain should stay forbidden. Ask your buddy before you widen the sandbox.

3. Run a local classifier

Read this script before you execute a single line. It does not call a network or an agent. It only prints a bucket for each file path.

#!/usr/bin/env bash
# Unexecuted example. Prefix checks only. No network calls.
set -euo pipefail

find . -type f ! -path './.git/*' | sed 's#^./##' | while IFS= read -r rel; do
  case "$rel" in
    .env|.env.*|*/.env|*/.env.*|fixtures/secrets/*|*.pem|infra/prod/*)
      echo "forbidden ${rel}"
      ;;
    sandbox/*)
      echo "sandbox ${rel}"
      ;;
    README.md|docs/*)
      echo "read_only ${rel}"
      ;;
    path-map.txt|classify-paths.sh|path-report.txt)
      echo "local_tool ${rel}"
      ;;
    *)
      echo "unmapped ${rel}"
      ;;
  esac
done

Treat the script as an unexecuted example first. An unmapped file should block the prompt completely. You do not guess a bucket under time pressure.

4. Fail closed on gaps

Count the report lines before you continue today. An unmapped count above zero stops the session. A forbidden count tells you what never gets uploaded.

bash classify-paths.sh | tee path-report.txt
awk '/^unmapped /{c++} END{print c+0}' path-report.txt
awk '/^forbidden /{c++} END{print c+0}' path-report.txt

If the unmapped count is not zero, fix the map. Keep every forbidden path out of the prompt text. Then rerun both counts and save the report.

5. Pick a machine with a table

Use this table before you choose a machine. Your written company policy beats every row below. When policy is silent, do not upload the repo.

Disclosure: This article was prepared as part of MonkeyCode's product outreach. MonkeyCode offers free model access and a free server option. This article does not name models, quotas, or duration.

Those terms change, so read the current product page. Do not paste the sample token into any prompt. Do not upload payroll files to a free server.

A free tier is not a data-processing agreement. Check retention terms before you type a prompt. Stop if those terms conflict with your handbook.

Situation	Where to run	What you may upload
Policy forbids external models	Approved laptop only	Nothing leaves the machine
Policy allows a hosted spike	Free server, if still offered	Toy repo or redacted sandbox
You want a hosted model	Free model access, if offered	Same allowlist, no forbidden paths
Live credentials sit on disk	Do not start the agent	Stop and ask your lead

6. Lock a prompt contract

Paste the contract above the task, not below it. Keep the task limited to one sandbox file. Refuse any request to scan the whole repo.

Path contract:
- Edit only sandbox/hello.py.
- Do not open fixtures/secrets or any env file.
- Do not add dependencies.
- Stop if a needed file is unmapped.
Task: add a one-line comment that says hello.

You review the diff yourself after the run. You do not merge from the agent summary alone. If the diff touches a forbidden path, discard the branch.

7. Reset before any pull request

This drill ends in a reset, not a merge. You are proving you can undo agent edits. You are not shipping product code on day one.

git status --short
git diff -- sandbox/hello.py
git restore -- sandbox/hello.py
# Switch back to the branch you started from, then:
git branch -D onboard/path-map

Confirm the sandbox file matches the original bytes. Confirm the secret fixture never entered a commit. Then tell your buddy what you refused to upload.

Limits you should say aloud

This classifier is a text filter, not a boundary. A model can still infer secrets from pasted logs. The sample globs are narrow on purpose today.

The script does not follow symlinks or submodules. It will miss a renamed env file easily. You still need human review on every diff.

Free model access can change or disappear later. A free server may retain prompts under its terms. Neither offer replaces your team's vendor review.

Who should skip this

Skip this if a sealed devcontainer is already required. Skip this if no redacted fixture is allowed. Skip this if you cannot name the editable file.

Staff with a written agent policy need stricter controls. This drill is for hour one, not production automation. Do not point it at a live customer tenant.

After the map is green

Ask your buddy to spot-check the path report. If they approve a hosted spike, open the MonkeyCode terms. Confirm the free options still match team policy.

Run the same contract on the toy repo only. Your first real PR waits until you can explain every line.

The path map is the note you keep nearby. Repeat that map on the next ticket before prompting.

8. Show your lead a receipt

Bring a short receipt to your onboarding lead. Include the branch name and the report counts. Include the list of paths you refused to upload.

Say which machine ran the classifier and why. Say whether any prompt left your laptop today. If a prompt left, attach the exact contract text.

If no prompt left, say that in one line. Ask which bucket was wrong before the next ticket.

Move the First Agent Run Off Your Laptop Clone

Quinn Zhu — Thu, 08 Oct 2026 10:30:27 +0000

Do not let your first agent edit land in the laptop clone. Run that first session on a remote sandbox instead. Bring back one reviewed patch after the checks pass.

You joined this repository with a thin map of its risks. A coding agent can still draft a small change for you. That speed is not a safe first pull request.

Keep the default branch untouched during this first hour. Explain every changed line before you request review. Treat the steps below as a proposal you must adapt.

1. Write the Contract Before You Open a Chat

Write a one-page brief before you open an agent chat. The brief is the only contract for this hour. If the brief feels vague, do not start the session.

Lock five facts in that brief before you type a prompt. Name the ticket and the one behavior you will change. Also name allowed paths, the CI test command, and the base SHA.

Do not ask the agent to invent those facts for you. You write them from the repository and the ticket. The agent may work only inside that written fence.

2. Record the Base Commit Before Any Agent Prompt

Your first commands should only read local repository state. They should not create an agent branch on this clone. Save the default-branch SHA where you can find it later.

git fetch origin
git status --short
git rev-parse --abbrev-ref HEAD
git rev-parse origin/main
git log -1 --oneline origin/main

Write that SHA into a note outside the work tree. If this repository uses master, record that name instead. This note is your return point if the session goes wide.

git rev-parse origin/main > "$HOME/hour-one-base.txt"

Do not commit that personal note into the repository. Do not push it to the remote by mistake either. It is a personal checkpoint, not a project file.

Confirm the work tree is clean before you continue. A dirty clone will mix your scraps with the agent patch. Stash or drop those scraps before you record the base.

3. Pick a Sandbox That Is Not Your Clone

You need a place the agent can edit without touching your clone. A free server can be that place when the offer includes one. A local virtual machine remains a valid substitute here.

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

MonkeyCode is only one route to free model access and a free server. Treat both items as availability claims that you must recheck today. This article does not name models, token caps, hardware, or duration.

Those details change, and this draft did not measure them. Open the current product page before you depend on any limit. If the free server is absent, keep the same brief locally.

Use that server only for this first reviewed patch. Do not place production secrets on that remote machine. Do not point the session at private customer data.

If the repository is private, read the server terms first. If those terms are unclear, skip the remote option entirely. A company ban on outside models also ends this path.

4. Copy a Narrow Brief Onto the Sandbox

Create a file named SESSION_BRIEF.md on the sandbox before prompting. Keep that file short enough to reread in two minutes. The sample below is an unexecuted template, not a real run.

# Session brief
Ticket: https://example.test/tickets/123
Change: Adjust empty-state copy in web/src/Empty.tsx only.
Allow: web/src/Empty.tsx and web/src/Empty.test.tsx
Outside scope: workflows, lockfiles, migrations, and infra
Test: npm test -- Empty.test.tsx
Done: that test passes, and no other file changes.
Stop: if a new dependency is required, stop.

Paste the brief as your first message to the agent. Tell the agent to stop when the change leaves those files. Tell it not to push or open a pull request.

Tell it not to amend commits or rewrite history. If the agent leaves the allowed files, discard the sandbox. Do not salvage a wide diff on your first day.

Start again later with a smaller allowed file list. Watch the session for scope creep in the chat replies. A request to update a lockfile is a stop signal.

5. Export One Patch and Leave the Sandbox

On the sandbox, read status before you export anything. You want a single patch file copied to your laptop. You do not want a surprise push to the team remote.

git status --short
git diff --stat
git diff > /tmp/hour-one.patch

Copy that patch home through your normal file transfer step. Remove any secrets you typed into the sandbox session. Stop or destroy that server when the product lets you.

Do not keep a forgotten remote checkout for later experiments. Hour one ends when the reviewed patch is home. A living sandbox is not a second source of truth.

6. Apply the Patch on a Named Ticket Branch

Return to the laptop clone after the patch is home. Create a branch that names the ticket, not the tool. Test the patch with an apply check before you apply it.

git fetch origin
git switch -c ticket-123-empty-state origin/main
git apply --check /tmp/hour-one.patch
git apply /tmp/hour-one.patch
git diff --stat

If the default branch moved, do not rebase alone. Ask a human owner before you replay the patch. If the apply check fails, stop and do not hand-merge.

A confused patch is a failed hour, not a puzzle. Rerun the sandbox session with a smaller written brief. Leave the laptop clone clean while you do that rerun.

7. Run the Named Test and Read Every Hunk

Run only the test command you wrote in the brief. A full local suite can wait for CI on this pass. You need proof that this patch matches the ticket text.

npm test -- Empty.test.tsx
git diff -- web/src/Empty.tsx web/src/Empty.test.tsx

Replace that npm command with the one CI already runs. Do not invent a friendlier command just for the agent. If CI uses a task runner, pin that exact task in the brief.

Write a reviewer note in your own words after the test. Use the checklist below before you open any pull request. The checklist is an unexecuted proposal, not a team form.

- [ ] I can name the user-visible change in one sentence.
- [ ] I can name the test that now covers that change.
- [ ] No lockfile, workflow, or migration file changed.
- [ ] No new dependency appeared in the diff.
- [ ] I can delete this branch without touching main.

If you cannot check a box, do not open the pull request. Shrink the patch or drop it and restart from the brief. Silence is better than a review you cannot defend.

8. Use a Decision Table Before You Continue

This table is a proposal, not an official team policy. Read the row that matches the diff you actually have. Then do that action, even if the agent sounded confident.

What you see	What you do
Only allowed files changed, and the named test passes	Open a draft pull request
The patch touches files outside the brief	Discard the sandbox result and restart
A new dependency or workflow edit appears	Stop and ask the code owner
The patch does not apply on the base	Do not hand-merge; rerun a smaller brief
You cannot explain one hunk	Do not request review

Confidence in the chat transcript is not evidence for you. The diff on disk is the evidence you can defend. Your short note is what the reviewer will actually trust.

9. Open the First Pull Request as a Draft

Push only the ticket branch from the laptop clone. Open the pull request as a draft, not as ready review. Paste the brief, the test command, and the base SHA.

git push -u origin HEAD

Write that body yourself after you finish reading the diff. Do not paste the agent transcript as the description text. Reviewers need the change, the test, and the risk.

They do not need the full chat log in the body. They need to see that you understood each hunk. A short body beats a long generated summary every time.

Request review only after the draft checks are green. If CI uses a different command, trust the pipeline. Update the brief, rerun that command, and then ask.

Do not argue with the pipeline on your first day. Do not weaken a check just to make the patch green. Ask the code owner before you touch any workflow file.

10. Close a Bad Draft Without Extra Story

Some drafts should die before anyone spends review time. Close the pull request and delete the ticket branch. Then confirm your clone still matches the fetched default branch.

git switch main
git fetch origin
git status --short
git push origin --delete ticket-123-empty-state
git branch -D ticket-123-empty-state

Do this when the patch grew past the written brief. Do this when a reread still leaves one hunk unexplained. A closed draft is a clean outcome, not a failure story.

If you already merged, follow your team revert rule instead. This article does not invent a revert policy for shared history. Ask the owner before you rewrite commits on the default branch.

Confirm the default branch SHA before you delete local work. If origin main moved, fetch and read the new log first. Never reset a shared branch to your hour-one note.

Respect Limits Before You Trust Free Access

This workflow fits a small, reversible text or copy change. It does not fit migrations, auth changes, or billing code. It does not fit code you cannot place on a third-party server.

Skip the free server when private-repo terms are still unclear. Skip free model access when your company bans outside models. A local editor plus the same brief is enough in that case.

Free access can change or disappear without prior notice. Do not plan a week of work on an unpaid server. Do not assume a token grant, machine size, or time limit.

Verify those facts on the current product page yourself. The sample test command is generic on purpose here. Your repo may use pytest, go test, or a task runner.

Pin the command your CI configuration already runs today. Do not invent a new command so the agent looks fast. A green command that CI ignores is not a valid signal.

The template paths are fiction for this teaching example. Replace them with a real file named in your ticket. If you have no ticket, do not invent work for the agent.

Skip This Path When the Fit Is Wrong

Skip this path if you cannot read a unified diff yet. Pair with a human before you invite an agent in. An agent does not replace that first reading hour.

Skip this path for production hotfixes and incident channels. Skip it for mass edits across issues you do not understand. A first contribution still needs the project guide and the license.

Skip the remote sandbox if it would hide work from review. The patch still comes home to your laptop clone. Your name stays on the pull request either way.

Do not use this flow to bypass code owner rules. Do not use it to skip a required design note. If the ticket lacks checks, write them with your mentor first.

Try One Ticket and Then Stop Cold

If those free options are still listed, try exactly one ticket. Keep the written brief tighter than the prompt you want. If that offer is gone, use a local virtual machine instead.

Stop after one reviewed draft leaves your laptop. Hour one builds a habit, not a batch of agent pulls. Tomorrow, repeat the brief before you touch a second file.

Keep Hour-One Exploration Off Your First PR Branch

Quinn Zhu — Thu, 08 Oct 2026 08:06:50 +0000

Do not let an agent edit your first pull request branch. Explore on a separate clone or a free server. Bring notes back and leave the surprise diff behind.

You just joined, so the repository still feels opaque. An agent can read faster than you can judge. That speed becomes a liability on your first pull request.

The failure you are preventing

The agent edits the same clone you plan to push. You skim a wide diff and approve your own confusion. Reviewers then ask why an unrelated file moved.

Rollback turns into a search instead of a known sequence. Your first hour should prevent that search entirely. Pins come first, and generated patches come later.

A junior pull request fails in a quiet way. The code may even pass a local check. The author still cannot explain the change.

Pin three facts before any prompt

You need three written facts before the first prompt. Keep them in a local note beside the clone. Do not let the agent edit that note.

Store that note outside the branch you will ship. A committed pin can be rewritten by the next edit. Your copy should survive a reset.

1. Capture the branch contract

Run these commands from the clone you control. Save the raw output before you interpret it. Confirm the default branch before you create work.

git remote -v
git status --short --branch
git symbolic-ref --short HEAD
git rev-parse --abbrev-ref origin/HEAD

If origin HEAD is unset, ask a teammate before guessing. Do not assume main when the repo tracks trunk. A wrong base branch wastes the entire first review.

Record the remote name next to the default branch. Later commands fail when you hard-code origin. That one line saves a messy recovery.

2. Name the review surface

List the files you must reread before any push. Start with entry points, config, and auth boundaries. Add each path your ticket names in writing.

# review-surface.md
- default_branch:
- base_remote:
- must_reread:
  -
- checks_i_will_run:
  -
- out_of_scope:
  -

You fill this file yourself, and the agent does not. If a path is unclear, leave the bullet blank. A blank line is safer than invented certainty.

Name one check you can run without extra setup. A test command you cannot find is not a plan. Ask where the project documents that command.

3. Write the rollback card before the diff

Write the revert sequence before any agent edit. Use placeholders until a real merge SHA exists. A card you cannot find is not a plan.

# Proposal only. Fill the SHA after the PR merges.
# Do not run this until you intend to revert.
git switch <default-branch>
git pull --ff-only
git revert --no-edit <merge-sha>
git push origin HEAD

Label the card as a proposal, not a result. Do not invent a SHA just to look ready. The sequence matters more than a guessed hash.

Keep the card next to the review surface. If you need help, you can show both. A reviewer can correct the sequence early.

Explore away from the branch you will ship

You can read the repo with MonkeyCode free model access. A free server option can host that reading session. Disclosure: This article was prepared as part of MonkeyCode's product outreach.

Confirm the current offer in the product before you rely on it. Do not assume a model name, a token quota, or a machine size. Treat availability as something you recheck, not a permanent promise.

Use that session to map the ticket, not to push. Do not paste secrets, tokens, or production environment files. Do not add the server remote to your pull request branch.

Copy notes back in words you can defend aloud. Retype any small patch you decide to keep. A pasted agent diff is not yet your change.

If the free server is unavailable, use a second local clone. The boundary matters more than the hosting choice. Your pull request branch stays untouched either way.

A reading prompt, labeled as a proposal

This is a reading prompt, not a license to edit. Paste it only inside the separate explore session. Replace the ticket line before you send it.

Map this ticket. Do not edit files. Do not propose a full patch.
Ticket: <paste the ticket title only>
Return:
1. Files I should reread.
2. Commands I should run locally.
3. Risks if I change the wrong file.
Stop if you need secrets or production data.

Reject any reply that includes a commit or a push. Reject any reply that asks you to paste credentials. Keep the map, then do the reading on your clone.

Treat the reply as a hint list, not as truth. Open each named file and confirm it exists. Drop any path the repository does not contain.

Decision table: what may cross back

Item	Cross back?	Rule you apply
Notes you rewrote	Yes	You can explain each line
Command output	Yes	Strip tokens, emails, and host secrets
Generated patch	Only after retype	You run the listed checks yourself
Env files or keys	No	Stop and rotate if they were copied
Unrequested lockfile edits	No	Leave them out of the first PR
Suggested commit message	No	You write the message after the diff

Read the table before you copy anything home. If a row says no, delete that content locally. When unsure, keep the note and drop the patch.

A useful map names files, risks, and local commands. A risky map includes secrets or a ready-made branch. Choose the map you can repeat without the agent.

Hour-one steps you can repeat

Follow this order on the day you join. Do not skip to a prompt because the ticket looks small. Small tickets can still touch shared project files.

Clone the repository into a path you control.
Run the branch-contract commands and store the output.
Fill review-surface.md before you write a prompt.
Write the rollback card with placeholders only.
Open the explore session away from that clone.
Ask for a file map of the ticket, not a patch.
Bring rewritten notes back and update the surface file.
Create the pull request branch only after those pins exist.
Limit the diff to files you listed as in scope.
Run the checks you named, then open the pull request.

Stop at the first step you cannot complete honestly. Hour one can end with pins and no pull request. That outcome is still a successful join day.

How you know the notes are yours

Read each note aloud before you trust it. If you stumble, the line is not ready to ship. Rewrite that line or drop it from the pull request.

Check three questions before you create the branch. Can you name the default branch without looking it up? Can you name the check you will run?

Can you point to the rollback card on disk? If any answer is no, stay in hour one. Do not open the real pull request yet today.

What you put in the first pull request

You write the pull request body in your own words. Name the ticket, the files, and the check you ran. State what you left unchanged and why that was right.

## What changed
-

## What I ran
-

## Out of scope
-

## Rollback
- revert the merge commit on the default branch if this must come out

Link the ticket your team already assigned to you. Do not let the agent invent acceptance criteria. If the ticket is vague, stop and ask a human.

Keep the first diff inside the files you listed. Extra files are a signal to pause, not to push. Explain a wider diff only after a teammate agrees.

Rehearse the exit before the real pull request

Before the real change, rehearse how you exit. Create a throwaway branch and one empty commit. Open a draft pull request, then close it unmerged.

git switch -c scratch/hour-one-exit
git commit --allow-empty -m "chore: rehearse pull request exit"
# Open a draft with your team's normal command, then close it.
git switch <default-branch>
git branch -D scratch/hour-one-exit

This drill is not a change you intend to ship. Close the draft and delete the local scratch branch. You want the exit path in memory, not an open request.

If your team forbids empty commits, skip the commit. Still practice creating the branch and switching back. The goal is a calm exit, not a clever history.

A small failure you can recognize

Imagine the agent edits a lockfile you never requested. Your review surface did not list that file. The decision table says that edit stays out.

Reset that path on the pull request branch only. Do not reset the whole clone if other work is present. Ask for help if you cannot see what changed.

git diff -- <path>
git restore --source=<default-branch> -- <path>

Run the named check after the restore finishes. Then explain the remaining diff in the pull request body. If you still cannot explain it, do not push.

Another failure is a note full of unfamiliar names. That note did not become knowledge by crossing back. Reread the file, or leave the change for later.

Limitations you should say out loud

This workflow does not review the code for you. It only separates exploration from the branch you own. A free server can still leak data if you paste secrets.

These steps do not replace your team's written policy. A local pin file cannot override CODEOWNERS or branch protection. You still need a human reviewer on the first pull request.

I did not execute these commands against your repository. Treat every snippet as a proposal you must adapt. Replace origin if your remote uses another name.

Free model access does not guarantee a correct map. Models miss local scripts, generated code, and private docs. Your reread is the check that matters.

This also will not teach the whole codebase in one hour. It teaches a boundary you can reuse tomorrow. Depth comes from the next ticket, not a bigger prompt.

Who should skip this approach

Skip this if you already maintain the service yourself. Skip it when your team forbids external coding tools. Skip it when the ticket touches secrets or production data.

Use the approved internal environment in those cases. A junior onboarding path is not an access bypass. If policy is unclear, ask before you open any session.

Skip the separate server if the repo cannot leave the laptop. A second local clone still gives you the same split. Do not weaken security to follow a hosting tip.

After the pins exist

If a free MonkeyCode server is already available, use it for the map only. Then return to your pinned clone and open the pull request yourself.

DEV Community: Quinn Zhu

Let the Existing Tests Choose Your First PR

Step 0 — Fix your question in one sentence

Step 1 — Map which tests already name your file

Step 2 — Run only those tests, and save the output

Step 3 — Turn your question into one assertion

Step 4 — Make the smallest change that flips the test

Step 5 — When your laptop cannot run the suite

The decision table

What this drill does not do

Score the File, Not the Prompt: A Week-One Triage Table for AI-Assisted PRs

The risky window is week one

Step 1: Measure the blast radius

Step 2: Turn the numbers into a decision

Step 3: Write the ticket contract in one paragraph

Step 4: Prove the loop before the edit

Step 5: Set the hunk budget and the rollback line

Where free model access and a free server actually help

Limitations and who should skip this

Your first-hour checklist

Rehearse the Rollback Before You Ship the Patch: A Day-One Git Drill

Rehearse the Rollback Before You Ship the Patch

Why rehearse undoing work you have not shipped

Step 0: Define "green" before you touch anything

Step 1: Move the drill onto a disposable remote

Step 2: Generate one small, believable patch

Step 3: Script the rehearsal

Step 4: Run each path three times

Step 5: Read the table like a reviewer

Decision table

Failure modes that make the numbers lie

Limitations and who should skip this

Terms snapshot you should verify yourself

Close the loop

Day One: Prove the Build Before You Take the Ticket

Why the probe comes first

Step 1: Build a disposable workspace

Step 2: Write probe.sh

Step 3: Read the verdict, not the vibes

Step 4: Delegate only the log reading

Step 5: Make the probe your first PR

Step 6: Rehearse the rollback now

Limitations and who should skip this

What you actually learned

Timebox Your First PR: A 90-Minute Onboarding Log for New Repos

Why hour one decides your first PR

The artifact: a JSONL onboarding log

Timebox the day in five windows

Three ways this goes wrong

Where a hosted box fits

Limits and who should skip this

What to take away

Your First Hour in a New Repo: Build a Reading Order from Git History

Conclusion first: do not read a new repo alphabetically

Step 1 — Extract co-change pairs from commit history

Step 2 — Expand one seed into a reading order

Step 3 — Use an agent for the files you cannot reach

Step 4 — Verify before you believe

Your first PR comes from the gaps

Limitations and who should skip this

What to do next

Scan the Diff Before You Request Agent Review

Start from the review gate

Keep this hour narrow

Step 1: Freeze the base ref

Step 2: Keep secrets out of the prompt

Step 3: Run a diff scan before review

Step 4: Use a decision table

Step 5: Fix a failure without hiding it

Step 6: Write the replay note

Step 7: Use a remote run only as a tool

Step 8: Reject a yes from the model

Who should skip this workflow

Limits you should say out loud

Before you request review

Score Every Hunk Before Your First Agent PR

Hold the boundary first

Name the tool without inflating it

Shape the prompt before the call

Add a local score script

Step 2: Write `probe.sh`