DEV Community: Quinn Zhu

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.

Delete the Scratch Worktree Before Your First Real PR

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

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

Start with the delete path

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

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

Build three cards before any model runs

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

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

Step 1: Create a disposable worktree

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

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

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

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

Step 2: Write the smoke card

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

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

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

Step 3: Practice deletion before any agent

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

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

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

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

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

Step 4: Bound the first agent task

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

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

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

Where a free server fits

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

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

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

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

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

Step 5: Open a tiny first pull request

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

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

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

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

Step 6: Rehearse rollback without drama

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

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

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

Use this decision table

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

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

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

Limitations you should say out loud

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

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

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

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

Who should not use this approach

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

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

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

What you do in the next ten minutes

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

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

Record a Green Local Boot Before Agent Work Starts

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

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

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

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

The failure this drill blocks

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

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

What you pin before any agent session

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

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

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

Step 1: Freeze git state on a clean clone

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

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

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

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

Step 2: Copy the documented boot command

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

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

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

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

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

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

Step 3: Name env files without dumping secrets

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

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

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

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

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

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

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

Step 4: Run boot with a hard timeout

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

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

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

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

Step 5: Prove health, then snapshot the proof

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

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

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

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

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

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

Step 6: Stop the process you started

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

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

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

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

Common boot failures you debug by hand

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

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

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

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

Decision table: may the agent start?

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

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

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

After boot is green: one narrow agent pass

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

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

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

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

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

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

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

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

Where a free agent lane fits

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

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

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

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

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

Limitations

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

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

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

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

Who should not use this

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

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

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

Close

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

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

Pin CI's Test Command Before Your First Agent Edit

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

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

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

Why this matters on day one

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

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

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

The rule

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

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

Artifact: pin file plus local runner

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

Proposed layout for a git-tracked pin directory:

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

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

Step 1: Find the workflow, not the README

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

ls -la .github/workflows

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

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

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

Proposed markdown stub for the pin header:

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

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

Step 2: Copy the run steps by hand first

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

Proposed extraction notes for the test job:

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

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

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

Step 3: Build a local runner that fails closed

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

Proposed script. Review it before you run it.

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

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

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

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

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

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

Mark the script executable after you review it.

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

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

Step 4: Prove the pin against known green tests

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

Proposed proof block for the pin file:

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

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

Step 5: Only then open an agent session

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

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

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

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

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

Step 6: Keep first PR scope tiny

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

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

Proposed PR title style for the pin-only change:

docs: pin CI test command for local junior runs

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

Decision table

Use this table when README and CI disagree.

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

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

First-hour checklist

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

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

Proposed clone and SHA capture commands:

git rev-parse HEAD
git status --short

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

Failure analysis: common first-hour misses

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

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

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

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

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

Need to fix short sentences in that last pair.

What this does not cover

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

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

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

Who should not use this approach

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

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

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

First rollback still belongs to you

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

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

Proposed revert note for the pin file:

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

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

Limitations recap

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

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

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

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

Name One Green Test Before Your First Agent Session

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

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

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

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

Why this belongs on day one

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

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

The session card rule

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

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

Fields you must record

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

Use these eight fields, nothing clever:

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

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

Proposed script

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

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

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

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

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

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

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

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

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

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

exit "${TEST_EXIT}"

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

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

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

Hour-one steps

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

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

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

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

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

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

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

Decision table

Use this table before you open any model.

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

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

First PR after the card exists

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

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

## Session card

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

## Replay

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

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

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

When a free server is useful

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

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

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

If you cannot explain the diff

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

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

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

Limitations

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

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

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

Who should skip this

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

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

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

Build a Path Deny List Before Your First Agent PR

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

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

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

Why this gate exists

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

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

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

The deny list in plain terms

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

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

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

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

Step 1: Inventory the tree before you prompt

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

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

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

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

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

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

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

Step 2: Write a deny file you can grep

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

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

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

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

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

Step 3: Install a checker that fails loud

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

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

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

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

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

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

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

echo "staged paths are outside the deny list"

Make it executable before you rely on it.

chmod +x check-untouchable.sh

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

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

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

Step 4: Prove the checker with a fake diff

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

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

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

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

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

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

Step 5: Bound the prompt after the freeze

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

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

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

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

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

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

A worked example for a billing ticket

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

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

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

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

Restate the bound in one short prompt.

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

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

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

What you paste, and what you never paste

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

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

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

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

Where a free coding agent fits

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

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

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

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

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

Failure modes you should expect

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

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

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

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

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

Limitations

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

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

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

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

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

Who should not use this

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

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

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

Keep the freeze, then request review

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

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

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