A report prints four rows, but its config file says limit: 6, and you’ve been asked to find out why. You’ve never seen this repository before. It has a CLI, a config loader, a few services, and a folder of tests. Reading all of it would get you there eventually. Following the one value that sets the row count is much faster.

Pin down the question

“Understand the reporting module” has no finish line. A question with a concrete answer does:

The config says limit: 6 and the environment has REPORT_LIMIT=4. The report prints four rows. Which one won, and what happens if REPORT_LIMIT is an empty string?

Write down the command you ran, the directory, and the commit. Also make sure the input has more than four records. If the source data only has four rows, getting four rows back tells you nothing about the limit.

Find a starting file from the clue you have

The first useful file might be a launcher, a formatter, or a test—not the function that chooses the limit. Use the clue you can reproduce to reach that function, and keep track of which links you have actually checked.

Download the report entry lab, unzip it, and enter report-entry-lab. This small project was constructed for this tutorial. It adds a real command, dispatch table and local fixture loaders around the same precedence rules used below. You need Node.js 22 or later, npm and ripgrep (rg); no dependency installation or model account is needed. The shell commands here work on macOS and Linux.

REPORT_LIMIT=4 npm run --silent report
Report rows: 4
Aster
Birch
Clover
Dahlia

The config fixture contains limit: 6; the data fixture has eight rows. The first line is a header, followed by four data rows. That makes the mismatch real, rather than a consequence of a short input file. The program reads only the included local fixtures and writes to the terminal; its tests launch local Node processes, with no network requests or file writes.

The clue you have Start here What still needs checking
A command that reproduces the behavior The package script or executable it invokes Which argument selects which handler
A distinctive output or error string The code that constructs it Whether a match is a producer, fixture or assertion, and who calls the producer
A named test Its import and the call inside the test Whether it starts the real command or supplies replacement dependencies
A config key or environment variable The read and conversion of that value Which caller reaches it and which loader supplies the config

Read the same lab in Yenpo

Use the downloaded report-entry-lab when your question is “Which entry produced these four rows?” The reading result should be a short record of the launch command, selected handler, input files and output call.

  1. Open the extracted report-entry-lab folder in Yenpo, choosing the root that contains package.json. Use Command-P (Go to File) to open package.json, then src/cli.mjs and src/commands.mjs. Check the launch script and the handler registered for report.
  2. Use Search All Files in the sidebar to search Report rows: with Regex off. Read src/format-report.mjs alongside the test matches: one constructs the text, while the others assert an expected result. Follow the formatter’s import and call in src/report.mjs before treating it as part of this command.
  3. Keep src/report.mjs, src/limits.mjs and the relevant test open in tabs. Note the file and line that supports each step, then use the Terminal checks below to distinguish a direct-function test from a run through the real CLI.

File browsing and text search need no model connection or JavaScript language server. To try this workflow, get Yenpo for Mac and open the same extracted folder; the reading help explains the two search tools. The ZIP contains source files, not Git history, so this exercise reads those files rather than a pinned commit comparison.

You have the terminal command

Inspect the script before inferring the entry from a folder name:

npm pkg get scripts.report
rg -n 'process.argv|commands\[command\]' src/cli.mjs
rg -n 'report:|runReport|report-config.json' src/commands.mjs

The first command prints "node src/cli.mjs report". In cli.mjs, process.argv.slice(2) makes report the command name; the remaining arguments go to the selected handler. commands[command] is a lookup, so finding the launcher is only half the job. Open commands.mjs: its report property calls runReport, with loaders for report-config.json and rows.json. Its neighboring help property returns help text instead.

Now make one controlled change through that same launcher:

REPORT_LIMIT=4 npm run --silent report -- --limit 2

This prints Report rows: 2, then Aster and Birch. npm forwards the arguments after the double-dash separator to the script. Read the dispatch lookup and the registered handler to establish the path; the changed output then checks that this command reaches the limit behavior. Output alone would not identify every call along the way.

You only have an output string

rg -n -F 'Report rows:' src tests
rg -n 'renderReport|runReport' src

The first search finds format-report.mjs and test assertions. The formatter constructs the header; the tests compare expected text. Neither kind of match is automatically a command entry. In report.mjs, check both the import of renderReport and the call that passes the selected names to it. Then follow runReport back to the report registration in commands.mjs, and the selected handler back to the stdout write in cli.mjs.

That gives you a route to verify with the command above. If your real output is assembled from several pieces, search for a stable fragment, then inspect how the surrounding expression is built. If a shared formatter has several callers, keep those as candidates until the launch arguments or a focused test select one; don’t merge all of them into the same execution path.

You have a test name

rg -n -F 'environment wins over config' tests
node --test --test-name-pattern='environment wins over config' tests/report.test.mjs

The matching test imports runReport directly and passes its own environment, config loader and row loader. It confirms that four beats six inside this function, but never starts cli.mjs or reads a config file. It cannot tell you which file a real command loads.

Follow the import to locate the behavior, then inspect the actual commands.report binding. This separate test crosses that missing boundary:

node --test --test-name-pattern='CLI uses REPORT_LIMIT' tests/cli.test.mjs

It launches the real CLI in a child process with REPORT_LIMIT=4 and checks its exit status and stdout. Both selected tests pass. Keep the distinction in your note: one test chooses its dependencies; the other exercises the launch and file adapters. A passing direct-function test is not a substitute for the latter.

You have the config name

rg -n -F 'REPORT_LIMIT' src tests
rg -n 'resolveLimit|loadConfig|report-config.json' src

The source read is in limits.mjs; other matches arrange test inputs. Follow the resolveLimit call in report.mjs, then check the loadConfig function supplied by commands.report. Its new URL(..., import.meta.url) chooses the included fixture relative to the module. The filename match alone would not establish that this handler uses it.

You now have the starting point needed for the value investigation below. Leave help and unrelated tests aside: you have checked the command, selected handler, actual input files and output location. If the real command uses another checkout, wrapper or environment source, resolve that difference before expanding the search. Otherwise, the next question is the value’s precedence—not the rest of the repository.

Follow the selected handler

The lab’s report.mjs parses arguments, loads the config, selects a limit and loads rows, then calls renderReport to add the header. Its CLI writes the returned string. The earlier standalone example below keeps just the data rows, so you can examine the value without the command wiring. The loaders are arguments in both versions, which lets tests observe the order without reading files:

export async function runReport({ args, env, loadConfig, loadRows }) {
  const { values } = parseArgs({
    args,
    options: { limit: { type: 'string' } },
    strict: true,
  });
  const config = await loadConfig();
  const limit = resolveLimit(values, env, config);
  const rows = await loadRows();
  return rows
    .slice(0, limit)
    .map((row) => row.name)
    .join('\n');
}

Before you open a single helper, this function already tells you the order of events: parse arguments, load the config, pick the limit, load rows, print. It also tells you something easy to miss: resolveLimit() only runs if loadConfig() succeeds. That will matter later.

In a real codebase, follow the imports. A function called loadConfig might read one JSON file, merge several, or call a remote service. The name won’t tell you which.

How the limit gets picked

export function resolveLimit(cli, env, config) {
  const raw = cli.limit ?? env.REPORT_LIMIT ?? config.limit ?? 10;
  const limit = Number(raw);
  if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
    throw new Error('limit must be an integer from 1 to 100');
  }
  return limit;
}

Three things happen here: pick a source, turn it into a number, check the range. Keep them apart in your notes. If you only write down “env overrides config,” it’s easy to assume that a bad environment value falls back to the config file. This code never does that.

CLI --limit REPORT_LIMIT Config limit Result
2 4 6 2, from the command line
absent 4 6 4, from the environment
absent absent 6 6, from the file
absent absent absent default 10
absent empty string 6 validation error
0 4 6 validation error

?? only skips null and undefined. An empty string still counts as a value, so REPORT_LIMIT='' wins. Number('') is 0, the range check throws, and the function never looks at the config file.

Changing ?? to || would let empty strings fall through, but it would also treat 0 as “not set.” That changes the rules; it isn’t a cleanup. Decide which behavior you want first: should a bad value that someone set on purpose be an error, or should it quietly fall back?

Follow the value to where it’s used

A correct limit doesn’t guarantee correct output. Follow limit to rows.slice(0, limit), then look at where rows comes from.

Here, loadRows() returns every row and the handler keeps the first few. Nothing is sorted, filtered, or paged at the source. So the limit caps how many rows get printed, not how much data gets read or held in memory.

That matters when the bug report is different. If someone says “the report runs out of memory even with --limit 2,” the precedence rules are the wrong place to look. You’d go into loadRows and check whether the limit needs to reach the data source. Same handler, different question, different next file.

Break something on purpose

Now try a broken config file together with --limit 2. The command line has the highest priority, so the command should still work, right?

It doesn’t. The config is loaded before the limit is chosen, so when loadConfig() throws, nothing after it runs. Precedence decides which value gets used. It says nothing about what has to succeed before that choice is made.

The opposite case deserves a test too: the config loads, but the chosen limit is invalid. Then the rows should never be read. Count the reads to check:

let reads = 0;
await assert.rejects(
  runReport({
    args: [],
    env: { REPORT_LIMIT: '' },
    loadConfig: async () => ({ limit: 6 }),
    loadRows: async () => {
      reads++;
      return [];
    },
  }),
  /integer/,
);
assert.equal(reads, 0);

If you only asserted that an error was thrown, a version that reads every row first and rejects the limit afterwards would also pass. reads === 0 is what pins down the order.

Run the example

Download configuration-flow.mjs and run it with Node.js 22 or later. It has no dependencies:

node --test configuration-flow.mjs

This original single-file download remains available. Its six tests cover the precedence order, empty and invalid values, the printed output, skipping the row read after bad input, and the broken-config case. They exercise these functions on their own; in your project you’d still want to check how the real CLI loads its environment and prints errors.

The new entry lab covers the command wiring as well. From its folder, run:

node --test tests/*.test.mjs
REPORT_LIMIT='' npm run --silent report

All nine tests pass. The second command deliberately exits with status 1, prints limit must be an integer from 1 to 100 on stderr, and produces no stdout. The unit test also counts row reads, so the empty-value case checks the ordering described above. The ZIP includes a SHA-256 manifest; both the archive and its extracted tests were checked.

Write down what you found

A short note is enough, and next time it’s much quicker to read than the code:

runReport
  parseArgs → loadConfig → resolveLimit → loadRows → slice → output

limit: command line > environment > config > 10
invalid selected value: error; no fallback; rows are not loaded
config read failure: stops even when --limit is present
scope: limit bounds output, not the row loader's work

In a real codebase, add the file and line next to each step, and list what you haven’t checked yet: which file loadConfig reads, whether a parent process sets REPORT_LIMIT, how the CLI shows errors. Once you can explain the four rows and name those open questions, you can stop for now. You don’t need to understand the rest of the project yet.

Let another maintainer check the handoff

A reading note becomes more useful when someone else can reproduce it without your conversation history. Try the poster-desk handoff ZIP and its short handoff brief. This small offline project and its claims were constructed for teaching; they are not a captured AI-generated app or a real handoff.

The receiving task is to check four promises against one fixed source snapshot: local cards can be read by a new process, exact sequential retries reuse a record, receipts are only fixture previews, and retention across deployment replacement remains unknown. “Implemented” covers the tested conditions; sequential retries do not establish concurrency safety, the mock sends nothing, and the package supplies no deployment storage evidence.

Follow the brief, copy RECEIVER.md outside the extracted package, and fill that copy with your commands, results, source locations and open questions. Keep the delivered template unchanged, then verify the original package again.

ZIP SHA-256
c39d19b210c05f4667cd74db4934459a079408d14c5e7678c24cd087e1df5185

In Yenpo, Go to File and workspace search let you keep the handler, the resolver, and the tests open side by side. When you ask the AI Reader, ask about one value: “Trace REPORT_LIMIT from where it’s read to where it’s used, with line references.” You’ll get a path you can check step by step, instead of another summary of the whole project.

Choose the next reading task by the evidence you have: