@kidlat-dakila/flightplan 0.0.0-stage → 0.1.6

package/backend/configurations/default-configurations/standard/writingStyle.md

@@ -0,0 +1,137 @@
+# How to write it
+
+Every review artifact Flight Plan stores is prose beside code. The code is referenced,
+never pasted, so **the prose is the whole of what you write** — and the same
+voice runs through all of it, from a five-word node label to a four-sentence
+reading.
+
+This file is the voice: what every surface has in common. How to word any one
+field is that field's own instruction, and the artifact's shape is
+`artifactFormat`.
+
+## The test
+
+A reader has the code open beside your sentence. Write what they cannot get from
+it: why this runs, and what goes wrong without it. Anything they could
+read for themselves is a sentence spent.
+
+The second test is harder and matters more: **could this be checked?** A claim
+about code that names the code can be verified by opening it. A claim that names
+nothing cannot be, so it never is.
+
+## Voice
+
+Written in [ASD-STE100](https://www.asd-ste100.org) Simplified Technical
+English. Six rules carry most of it:
+
+- **One idea per sentence.** Twenty words is long.
+- **Active voice.** "`checkSize()` throws `TooLarge`", not "`TooLarge` is thrown".
+- **Present tense**, except where the tense table below says otherwise.
+- **Plain words over precise ones.**
+- **No ambiguous *it*.** Name the thing again.
+- **No vague verbs** — *handle*, *manage*, *process*, *support*, *orchestrate*,
+  *surface*, *drive*, *deal with*. Each names a topic and leaves out what
+  happens. Use the verb the code uses.
+
+**No metaphor for what the code does.** Where the code has an operation, name
+the operation. The test is whether the reader can find the word in the code:
+they are reading beside it, so a word that is not in it is a word they have to
+translate.
+
+- Not "climbs the ancestors" but `element = element.parentElement`, written
+  twice if the loop runs twice. Not "bubbles up", "walks the tree", "falls
+  through", "bails out", "hands off" — and not "the climb" or "the hand-off"
+  either.
+- Not "missing" or "never set" but `undefined`, `null` or `""`. Name the value.
+- Not "the check wants a clean path" but "`resolvePath()` returns null for a
+  path outside the root". Code has no intent.
+- Not "the guard", "the gate", "the plumbing" or "the wiring" but the plain word
+  for what the code is: a condition, a validation, a check, a function that
+  passes the value to `saveOrder()`. Review jargon is a metaphor too.
+- Not "refuses", "rejects", "accepts", "allows", "blocks" or "protects" but the
+  operation: returns `false`, throws `RangeError`, returns a 400, skips the
+  line. A verb of judgement is a metaphor for one of these, and hides which.
+
+A codebase's own nouns are not metaphors for this purpose — a card, a panel, a
+board, a waypoint — because the code calls them that and the reader can search
+for them. Nor are technical verbs with one meaning: return, throw, parse,
+render, call.
+
+A metaphor cannot be checked, which is why it never is. "Four ancestors up"
+survived several drafts of this instruction; written out as `<li>` → `<ul>` →
+`<div>` it turned out to be three.
+
+**Name the value, never the variable.** A call carries the arguments it was
+given on the run you are describing: `` `addToBasket({ id: 7 })` ``,
+never `` `addToBasket(payload)` ``. Where a literal will not fit, write the shortest
+thing that identifies it — `<div.fp-interlude>`, `[9 ranges]` — but never the
+variable name, because that is the one thing the reader cannot resolve.
+
+**Do not narrate the diff.** "This line was changed to…" is about the pull
+request. The prose is about the code, and the panel already marks what changed.
+
+**Invent no nouns.** A *post-acquire release* or a *rank direction contract*
+names something the codebase does not name, so a reader can neither search for
+it nor check it. Both read as precision until somebody tries to use them to find
+something.
+
+## Tells
+
+Six habits that mark prose nobody checked. Fix each on sight.
+
+- **The `-ing` rider.** A clause opening *ensuring*, *allowing*, *improving*,
+  *providing* or *helping* is a claim tacked onto a verified one. Either it is
+  what the code does — say it as the main clause and link it — or cut it.
+- **The hedge.** *Likely*, *presumably*, *appears to*, *generally*, *typically*.
+  A reading that hedges is a reading nobody opened the file for. What you could
+  not resolve is a `question`, or a `risk` whose reading says what stopped you.
+- **The sales adjective.** *Robust*, *seamless*, *elegant*, *powerful*,
+  *crucial*, *pivotal*. The marks and the `changed` chip carry the emphasis; a
+  word insisting on it competes with them.
+- **The vague connection.** *Associated with*, *related to*, *tied to*, *works
+  with*. Name the relation the code has: calls, reads, returns, throws, wraps.
+- **Staging instead of stating.** "This isn't just a check — it's…". Say what it
+  is; a sentence that opens with what something is not has spent half itself on
+  nothing.
+- **Borrowed authority.** *Best practice*, *industry standard*, *the usual
+  pattern*. Cite the code, or this repository's own convention with a link, or
+  drop the point.
+
+And two smaller ones: **`serves as`, `features`, `boasts`** where *is*, *has* or
+the real verb would do; and **a reading that restates its own title**, which
+means the title is doing no work or the reading is not.
+
+**None of these reach inside code.** An identifier, a quoted error string, a
+value and a finding's solution are exempt from every rule in this file:
+`handleRequest()` is a name, not a word choice.
+
+The rest of this file is weighed in context rather than fixed on sight. How long
+a reading runs, how much reasoning a description carries, whether a sentence
+repeats its neighbour — the code beside it settles those, and no rule can.
+
+Linking code is a fixed part of the writing style, always in force — its rules
+are served separately and are not edited here.
+
+## Tense
+
+Titles are past tense — *Added*, *Modified*, *Removed* — because the code
+exists.
+
+Descriptions are present tense: they describe code, not work. A waypoint's
+reading is the exception: it opens with what the author did, then says in the
+present what the code does as a result. Its own instruction has the form.
+
+## Where a reason goes
+
+`context` carries the reason the change exists, and a node's `description`
+carries the reason a step is in the path. A waypoint's reading carries the
+reason for its own piece of the change — what it is for within the pull request
+— and its instruction says how. A constraint or a trade-off beyond that is
+worth one sentence at the end of a reading, and nothing more, because a reading
+that argues is a reading nobody finishes.
+
+Everything else about a particular field — how to word a title, a label, a
+reading, a description, an edge label, a contract, a finding — is that field's
+own instruction. Ask for it when you reach the field. It used to be restated
+here as well, which meant two copies of every rule and, in the end, two copies
+that disagreed.

package/backend/configurations/default-configurations/unfamiliar-territory/blast.nodes.impactReason.md

@@ -0,0 +1,8 @@
+Write one or two sentences a reviewer can check against the code.
+
+- On `breaks`: what fails, and the case the author did not account for.
+- On `behaviour-changes`: what is different now, and for whom.
+
+Name the place and link it: "renders the units left, and now renders a negative
+number when holds exceed the stock". Do not restate the impact type. Write none
+on an unaffected file.

package/backend/configurations/default-configurations/unfamiliar-territory/blast.nodes.impactType.behaviour-changes.md

@@ -0,0 +1 @@
+It still works, and now does something different that the change does not mention.

package/backend/configurations/default-configurations/unfamiliar-territory/blast.nodes.impactType.breaks.md

@@ -0,0 +1 @@
+Its logic no longer holds against the changed code, and the compiler does not say so.

package/backend/configurations/default-configurations/unfamiliar-territory/blast.nodes.impactType.md

@@ -0,0 +1,11 @@
+Set the impact type to what the change does to this file. What each value means
+is given with its option.
+
+Judge the logic, not the types. A call that no longer type-checks is the
+compiler's to report, and is never the reason for a value here.
+
+Leave it unset when nobody has assessed the file. There is no `unknown`. A file
+of the change takes no impact type at all.
+
+`breaks` and `behaviour-changes` never travel alone: write the `impactReason` in the
+same call. `unaffected` is written alone, with no reason.

package/backend/configurations/default-configurations/unfamiliar-territory/blast.nodes.impactType.unaffected.md

@@ -0,0 +1 @@
+The change reaches it, and nothing it does is different.

package/backend/configurations/default-configurations/unfamiliar-territory/context.md

@@ -0,0 +1,70 @@
+Write three parts, in this order: an opening paragraph, then `## Overview`, then
+`## Implementation`.
+
+```markdown
+A basket with an item that sold out a minute ago could still reach payment. The
+shopper now hears about every such item before paying.
+
+## Overview
+
+- **When** a customer submits a basket with two lines out of stock, **then**
+  [the error names both lines](code:src/stock/check.ts#hasStock).
+- **When** every line is in stock, **then** nothing changes.
+
+## Implementation
+
+**`src/stock/`**
+
+- Modified [`hasStock()`](code:src/stock/check.ts#hasStock) to read every level
+  once and collect every short line.
+```
+
+**Verify every claim against the diff**, never against a pull request's own
+description.
+
+### The opening paragraph
+
+Say why anyone should care, to a reader who has not seen the code.
+
+**This paragraph bans identifiers, paths and links.** If you cannot write it
+without naming a symbol, you are describing the implementation rather than the
+change. That ban is what makes it the easiest place to hide a vague verb, so say
+what the reader would see: not "the size check handles an oversized query" but
+"a query over 1 MB now gets an error that names the 1 MB limit".
+
+Five sentences, and no more even when the change is large.
+
+### Overview
+
+What changes from outside the code, as a list of scenarios. Each item is one
+sentence: a bold **When**, the situation, a bold **then**, what can be observed.
+
+The situation is in the reader's terms — one clause. Name what a person outside
+the code does, or the state that holds: "a customer submits a basket with two
+lines out of stock", "every line is in stock". Write the situation, not the code
+path that answers it.
+
+What can be observed is the result a person or another system sees, not the
+mechanism: "the error message names both out-of-stock lines". Link the code the
+result comes from where there is code to name.
+
+Say "nothing changes" when a reader would reasonably expect a change and there
+is none; that line stops a reviewer hunting for a regression that is not there.
+A "nothing changes" scenario carries no link.
+
+### Implementation
+
+What changed inside the code, grouped by where it lives. Each group is a bold
+label on its own line, then a list of the changes there.
+
+The label is the place the changes live — a file, or a directory when several
+inside it are touched. It takes no verb. Group by where the code lives, not by
+theme, and put the groups in the order the tour walks them.
+
+Each item is one change a reader would notice, as one sentence: the verb first,
+then the code it names. "Modified `hasStock()` to read every level once and
+collect every short line." Link the code the claim is about.
+
+An item that names no code is usually one that has not been thought through. The
+exceptions are rare — a configuration value, a deleted file, the tests — and
+they carry no link.

package/backend/configurations/default-configurations/unfamiliar-territory/contextCodeBlocks.description.md

@@ -0,0 +1,98 @@
+Write for an engineer who has never opened this repository and does not know its language or its
+libraries well. They do not know this codebase's words, its product, or where anything is used.
+They opened this code by hovering its name, and they see the code under your words.
+
+Each item is handed out with its `kind`:
+
+- `codebase` is code of this repository.
+- `library` is one name the code imports from a library, such as `useState` of `react`.
+- `language` is a name the file neither imports nor declares, such as `Promise` or `Math`. Flight
+  Plan assumes it is part of the language or of where the code runs.
+
+**A function's description is three sentences, in this order:**
+
+> `{name}({arguments})` is a {what it is} that {what it does}. It takes {each argument, with its
+> type and what it stands for} and returns {what the caller gets back}. It is used in {where} to
+> {what that code needs it for}.
+
+> `validateAge(user)` is a validation function that checks whether a user is old enough to hold an
+> account. It takes `user: User`, the person signing up or editing their details, and returns
+> `true` when their `birthDate` is 18 years ago or more, and `false` otherwise. It is used in the
+> [registration page](code:src/account/RegisterPage.tsx#RegisterPage) and the
+> [update profile page](code:src/account/ProfilePage.tsx#ProfilePage) to stop the form before it
+> is sent.
+
+- **What it is**: the kind of function, in two or three words: a utility function, a validation
+  function, a query function, an event handler, a hook, a server procedure.
+- **What it does**: its job, in plain words. One clause. Do not walk the lines.
+- **Arguments**: write each as `name: type`, then what the value stands for in the product. Say
+  which can be left out.
+- **Returns**: the type and what it stands for. Say what comes back when there is nothing to
+  return, and what it throws, where it does either.
+- **Where it is used**: the pages, routes or functions that call it, by the name a user of the
+  product would know them. Take them from the `usedBy` the item is handed out with, not from a
+  guess. Where many use it, name three and say how many there are.
+- **What for**: the reason that code needs it, in the product's words.
+
+**A component's description is the same three sentences**, with its props for the arguments, what
+it shows for what it returns, and the pages that render it for where it is used:
+
+> `<EmptyState />` is a placeholder component that a page shows in place of a list when there is
+> nothing to list. It takes `title: string`, the main line, `hint: string`, a smaller line under it
+> that can be left out, and `action: { label, href }`, an optional button. It is used in the
+> [orders page](code:src/orders/OrdersPage.tsx#OrdersPage), the
+> [basket page](code:src/checkout/BasketPage.tsx#BasketPage) and 6 other pages to tell a shopper
+> why the page is empty and what to do next.
+
+**Any other code** (a type, a constant, a table, a router) is two sentences: what it is and what
+it holds, then where it is used and what for.
+
+> `orderRouter` is a router that holds every operation a browser can ask the server to do with
+> orders: `list`, `byId` and `cancel`. It is used in
+> [`appRouter`](code:src/server/api/root.ts#appRouter), the one list of every router of the
+> server, so that the page can call `api.order.list`.
+
+**A `library` item's description says what the name is and what it does**, in one sentence or
+two. Say what kind of thing it is and which library it comes from, then what it does when it is
+called, rendered or used. Do not say where this codebase uses it: one description is shown in
+every file that imports the name.
+
+> `useState(initialValue)` is a React hook that keeps a value of a component between its renders.
+> It returns the value and a function that sets it, and setting it draws the component again.
+
+> `z` is the entry of Zod, a library that checks the shape of a value while the program runs.
+> `z.object({ … })` describes an object, and its `parse(value)` returns the value when it has that
+> shape and throws when it does not.
+
+**A `language` item's description is the same two sentences**: what the name is, then what it
+does. Say whether it belongs to the language, to the browser or to the server it runs on.
+
+> `Promise` is JavaScript's value for a result that arrives later. `Promise.all(list)` waits for
+> every promise in the list and returns their results in the same order, and fails when one fails.
+
+> `localStorage` is the browser's store of text that stays after the page is closed.
+> `localStorage.getItem(key)` returns the text saved under a key, or `null` when there is none.
+
+- Write a call as it is written in the language of the code, with the arguments a caller passes.
+- Say what the name does, not how it is built.
+- Where the name holds several functions, describe the ones this code calls. The item is handed
+  out with no code, so read the change for how the name is used.
+- A name that is not of the language at all, because a tool or a framework puts it there, is
+  described as what it is. Say which tool provides it.
+
+**Define a word of this codebase the first time you use it**, in one clause: a hold, a line, a
+procedure. The reader has not met it.
+
+**Link every place it is used that the artifact holds.** A link resolves only inside the files the
+artifact holds. Name code in any other file in backticks, with its path.
+
+**Describe the code as it is, not the pull request.** The description is shown wherever the name
+is hovered, in any file, so do not say _here_, _this caller_ or _the change_. A waypoint's reading
+says what the author changed.
+
+**Explain a library or the language in its own item, and nowhere else.** In the description of a
+`codebase` item, name a library function the code is built on and say in one clause what this code
+gets from it. The reader can hover that name for the rest.
+
+**Do not tell history the code does not show.** Why it was built and what it replaced are not in
+the code, unless a comment or a name says so.

package/backend/configurations/default-configurations/unfamiliar-territory/journey.description.md

@@ -0,0 +1,10 @@
+Tell the diagram as text: what a reader would know after following every line of it. Five sentences at most, and fewer for a small diagram.
+
+- **Start where the paths start.** Say what sets each path off, in the reader's terms: "When a shopper places an order", "When the nightly job runs".
+- **Follow each path in the order the diagram draws it**, from the left to the changed code, naming the steps by what they do: `<Checkout />` calls `placeOrder()`, which asks `stockOf()` for every line of the cart.
+- **Say where the paths reach the change.** Name the nodes the change touched and how the path arrives at each. Do not explain the change: the Context Section and the waypoints do.
+- **Several paths.** Say how many there are and where they meet, then tell each in one sentence. Tell paths that run alike together.
+
+Cover the whole diagram, not one path of it. A large diagram is told by its paths and the steps they share, not node by node. Do not open with "This diagram shows", and do not count the nodes.
+
+`When a shopper places an order, <Checkout /> calls placeOrder(), which asks stockOf() for every line of the cart before it charges the card. The stock badge reaches stockOf() as well, through useStockLevel(). Both paths end at stockOf(), which now subtracts the held units.`

package/backend/configurations/default-configurations/unfamiliar-territory/journey.nodes.blockLabels.label.md

@@ -0,0 +1,9 @@
+Say what this row of the node is for, as a reader of the product would: "The promo code the shopper typed", "Sends the order to the API". Read the code of the node first, so the label says what the block holds or does, not what it is called.
+
+- **An argument or a state.** Say what the value holds: `The lines of the cart`, not `items`.
+- **A hook.** Say what it gives the node: `The mutation that applies a promo code`.
+- **An effect.** Say what it does and when: `Clears the form after a save`.
+- **A call.** Say what is asked of the code it calls: `Saves the renamed user`.
+- **A step.** Say what the step does: `Refuses an empty title`. For a condition, say what is checked. A step can stand for several statements that follow each other, listed by the first: say what they do together, `Renames the chosen user`.
+
+Leave the name of the code out: the row shows it under your label. Keep the same shape and tense on every block label of one node.

package/backend/configurations/default-configurations/unfamiliar-territory/journey.nodes.description.md

@@ -0,0 +1,7 @@
+Tell the journey that reaches this node, in the order the diagram draws it: "When {who} {action}, {caller} {calls, renders or reads} this {what}." Start with what starts the path, then name each step between it and this node, and end on what hands over to it: `When a shopper opens /orders, <OrdersPage /> calls useOrders(status), and useOrders() hands this function to useQuery as its query function.`
+
+- **Several paths.** A node that more than one path reaches opens with one line that says so, then a list with one such sentence per path.
+- **A node with trigger labels.** Say what each event runs and what each fetch feeds, in the words of its trigger label: `When a shopper clicks "All", the handler calls setStatus(null) on the filter store.`
+- **Nothing reaches it yet.** Say that no code uses it, and what is meant to.
+
+Do not describe the change here. The waypoint of the code says what changed, and the side panel shows that waypoint above the code. Do not restate the label or the identifier, which the node already shows. Link a step to its code where a reader would want to open it.

package/backend/configurations/default-configurations/unfamiliar-territory/journey.nodes.label.md

@@ -0,0 +1,5 @@
+Say what this step does, and to what — "Throws when a line is out of stock", not "The stock check" and not the identifier. A bare noun tells a reader which code this is and nothing about why they are being shown it. The identifier is never the label: the node already carries the name of its code. Keep the same shape and tense on every node of one diagram.
+
+A component drawn inside another is read inside its frame, so do not repeat the outer component in its label.
+
+A node of an event, an effect or a callback inside a component, of a procedure of a router and of an action of a store is read beside the node around it, so say what this unit does on its own: "Applies the code when the form is submitted", "Stores the promo when the request succeeds". An event has a trigger label too, which says what the user does, so the node says what the handler does.

package/backend/configurations/default-configurations/unfamiliar-territory/journey.nodes.triggerLabels.label.md

@@ -0,0 +1,6 @@
+Say what happens at this place, as a reader of the product would: "A shopper clicks Remove", "The orders of the account are loaded". Read the code of the node first, so the label names the element the user acts on or the data that is fetched.
+
+- **An event.** Start with who acts, then the action and what it is on: `A shopper clicks "All"`. Leave the name of the component and of the handler out: the row shows the name of the code under your label.
+- **A data fetch.** Say what is loaded, not how: `The stock of the product is loaded`, not `useQuery runs`.
+
+Keep the same shape and tense on every trigger label of one diagram.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.title.md

@@ -0,0 +1,7 @@
+Say what the reviewer is being shown in this file, in one line — "Rounding moves
+to the subtotal", "The stock check now counts held units". It is the file's
+label on the section rail, so it has to tell this file apart from the others in
+the change. Never the path, which the section already shows, and never a list of
+every waypoint under it.
+
+Present tense, about the code. Keep it under about eight words.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.kind.bug.md

@@ -0,0 +1,2 @@
+Broken behaviour that will cause an incident, and proven. Do not report a bug
+until you have proven it; an unproven one is a `risk`.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.kind.md

@@ -0,0 +1,7 @@
+### Kind
+
+Choose exactly one kind. Each is a different answer, not a different intensity.
+What each kind means is given with its option.
+
+Order a waypoint's findings most severe first: `bug`, then `risk`, then `nit`, then
+`question`.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.kind.nit.md

@@ -0,0 +1,3 @@
+Anything the author may decline: style, naming, a micro-optimisation, and every
+improvement. All of it is optional, which is the one thing the reader needs to
+know at a glance.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.kind.question.md

@@ -0,0 +1,2 @@
+You are not sure. A genuine question, not a suggestion in disguise. Carries no
+trace and no solution.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.kind.risk.md

@@ -0,0 +1,3 @@
+The code is fragile though it works (a race, a missing null check, a swallowed
+error), or it looks broken and you could not demonstrate it. Both are an unsafe
+path that looks reachable and that nobody has seen fire.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.md

@@ -0,0 +1,30 @@
+Report what is wrong with the code this waypoint shows, on the waypoint itself.
+A reviewer meets the claim with the code it is about rather than in a list at
+the end, which is the whole reason this is here rather than there.
+
+Report only what your reading of the code found. A finding you inferred from the
+diff without opening the file is a guess with a chip on it, and the reviewer
+cannot tell the difference. Verify it against the repository, including files
+the change never touched — a guard three files away may already handle the case
+you are about to report.
+
+Pick the kind honestly. `bug` is something that is wrong now. `risk` is
+something that will go wrong under conditions you can name. `nit` is worth
+saying and not worth blocking on. `question` is you not knowing — a genuine
+question, not a suggestion in disguise, and it carries no trace and no fix.
+
+The title says what is wrong in one line, the reading says why, and the trace is
+the steps that prove it. Name code with `code:` links throughout, so every claim
+resolves to lines a reader can check.
+
+Give every `bug`, `risk` and `nit` a `solution`: the lines as they should be.
+It is a string of code that replaces the lines this waypoint covers — no path,
+no position, because the waypoint is the position — and the reader can preview
+it against the real file.
+Write the lines whole, since a line left out of the body is a line the fix
+deletes. If the fix needs more than these lines, write the part that belongs
+here and name the other lines in the reading.
+
+A card shows one chip, the highest kind it carries, so a bug beside a nit reads
+as a bug. That is right, and it is also why a nit reported on the same card as a
+bug is easy to miss: report the nit where it belongs.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.reading.md

@@ -0,0 +1,14 @@
+### Reading
+
+Explain the defect in the reader's file, one linked claim at a time: what the
+code does, and why that is wrong. Every claim links the exact lines it rests on,
+so the reader can open each one. Present tense, a few sentences at most.
+
+Do not hedge — a reading that hedges is a reading nobody opened the file for.
+Where you report a `risk` because you could not prove a suspected bug, the
+reading says in one sentence what stopped you.
+
+**An improvement says three things**: what the code does now and its limitation,
+stated plainly as working; the better alternative, with the exact imported
+symbol; and why it is better — fewer lines, fewer states, one fewer round trip.
+Never "cleaner".

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.solution.md

@@ -0,0 +1,12 @@
+### Solution
+
+Every `bug`, `risk` and `nit` carries a solution. A `question` carries none: it
+is not a claim.
+
+Write the lines as they should be, whole, with the indentation they have in the
+file. The solution replaces every line the finding's waypoint covers, so a line
+you leave out of it is a line the fix deletes.
+
+If the fix needs more than these lines, write the part that belongs to these
+lines and name the other lines that must change in the reading, with `code:`
+links. The waypoint says where the defect is, and the solution follows it.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.title.md

@@ -0,0 +1,6 @@
+### Title
+
+Name the code and what it does wrong — "`annotateRanges` drops the line mapping
+for the whole block", not "Prose loses its line numbers" and not "A subtle
+indexing problem". A title that could belong to a different finding is not a
+title. About ten words.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.findings.trace.md

@@ -0,0 +1,12 @@
+### Trace
+
+The steps that prove the finding, in the order the code runs.
+
+The first step is the trigger: name the action and what makes it fire — the
+parameter, the state, the condition. "A reader selects a sentence", not
+"selection happens"; `POST /orders` with `quantity: 0`, not `POST /orders`. That
+step names a user action, so it carries no link.
+
+Every step after it is a debugger step, linked to where it is in the code. A
+trace carries the proof and nothing else — no impact, no evidence, no proposal
+step. A `nit` and a `question` carry no trace.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.needsAttention.md

@@ -0,0 +1,36 @@
+Mark the few waypoints that carry the change: the cards a reviewer should spend
+their time on. Write one or two sentences saying why this is where the pull
+request does its work, and leave the field off every other waypoint.
+
+A pull request mixes the change with what the change drags along: a value
+threaded through three signatures, an import moved, a class renamed, a style
+adjusted, a type widened so the new code compiles, a fixture updated. A reviewer
+with forty cards and an hour has to know which three are the change. That is
+all this flag says. It points at importance. It is not a warning.
+
+**Flag the waypoint where the behaviour changes**: the new rule, the decision
+the code now makes differently, the data that now goes somewhere it did not,
+the contract a caller will now depend on. **Leave it off the plumbing**: wiring
+that passes the new value along, a constant, a comment, formatting and styling,
+a type-only edit, a rename, a test that restates the code.
+
+**It is not a bug report.** Something you believe is wrong, or could go wrong,
+is a finding — a `bug` or a `risk` — on the same card. A card can carry both,
+and a finding is never the reason for the flag. If the only sentence you can
+write is about what might break, you are writing a finding, so write one and
+leave this off.
+
+**Say why the card is central, against what the pull request is for.** "This is
+the rule the pull request exists for: an order now holds its stock before the
+card is charged, and the other cards in this file wire it in." Not "check this
+carefully", "core logic" or "this is complex": they name no reason, and a
+reviewer can see complexity without being told.
+
+**It works by contrast, so keep it rare.** One to three in a pull request is
+usual, and seldom more than one in a file. If every card would carry it, none
+should: the flag has nothing left to point at.
+
+It is not a second reading. The reading says what the code does; this says why
+it is the part to read.
+
+Name code the way every other field does, with `code:` links.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.reading.md

@@ -0,0 +1,68 @@
+Write the reading as the engineer who read the change, telling a colleague what the author did here
+and why it matters to the pull request.
+
+**Open with one sentence of a fixed shape**: _The author_ + what they did + what kind of code + what
+the change does.
+
+> The author modified a condition in `validateQuantity()` that now returns `false` for a quantity
+> over 10, down from 20. [`<BasketForm />`](code:src/checkout/BasketForm.tsx#L40-52) calls it before
+> it submits, so the form no longer submits a quantity of 11 to 20.
+
+- **What they did** is one verb, past tense: _added_, _implemented_, _modified_, _removed_,
+  _moved_, _replaced_.
+- **What kind of code** is the thing the reader will find in the panel, in the plain word for it:
+  a function, a method, a condition, a validation, a query, a loop, a type, a component, a
+  constant, a test. Then its name. Not review jargon — not a guard, a gate, a hook or wiring —
+  because the reader has to translate it back into the code they are looking at.
+- **What the change does** is the effect, not the mechanism. Say what is different now — the value
+  that moved, the input that now gets an error, the result that is now returned — and name the
+  values: from 20 to 10, from a throw to a returned reason.
+- **Say what the code does, not a judgement of it.** Not _refuses_, _rejects_, _accepts_, _allows_,
+  _blocks_ or _protects_, but the operation: returns `false`, throws `RangeError`, returns a 400,
+  skips the line. A verb of judgement hides which of these it is.
+
+**The author is the subject of the change, never of the code.** "The author reads every row" is
+wrong: the author read nothing, the code does. After the opening, the code is the subject: "It
+reads…", "`validateQuantity()` returns…".
+
+**When the change does more than one thing, list them.** Open with the sentence up to _that_, then
+one item per effect, in the order the code does them. Do not chain effects into one sentence with
+_and_, _then_ and commas.
+
+> The author added a function `reserveStock()` that:
+>
+> - reads the stock level of every line in the basket in one query
+> - writes one hold per line, which lapses after 15 minutes
+> - returns the holds, so that [`placeOrder()`](code:src/checkout/placeOrder.ts#L13-27) can release
+>   them when the charge fails
+
+**Do not walk the lines.** The panel shows them. Leave out how the code reaches its effect — the
+sort order, the option merge, the loop — unless that detail is the change itself.
+
+**Then say what it is for, against the pull request.** Every reading connects its piece of the
+change to the purpose `context` states, usually with _so that_ or _because_. A reviewer who reads
+only this card should know why it is in the pull request.
+
+**Take the connection from the Blast Diagram, not from a guess.** Where the artifact has one, `blast` lists the files
+that import the file this card is in, and what the change does to each: its `impactType` and its `impactReason`. Name the one this card exists
+for — the form that no longer submits, the route that now returns something else, the caller that now
+depends on the new value — and link it. Where nothing outside the change reaches this code, name
+what inside the pull request uses it. Where neither the Blast Diagram nor `context` shows a reason,
+say what the change does to its consumer and stop: the author's reason is not yours to invent.
+
+**Link code outside the card; name code inside it.** The panel already shows the card's own lines,
+so a link to them points at what the reader is looking at. Write those identifiers in backticks
+without a link. Link everything else the reading mentions — the caller, the consumer, the type, the
+test, the other half of the change in another file — and link every such mention, not the first one.
+A link resolves only inside the files the artifact holds, which `codeLinks` lists how to find; name
+code in any other file in backticks, with its path.
+
+**A body's reading** (a waypoint with children) says what the author did across the whole body and
+why: the opening sentence, a list of at most five items where it does several things, and one
+sentence of purpose. **A block's reading** (a child) is the opening sentence about its one block,
+with a list only if that block does several things, and its _so that_ points at the body it sits
+in or the code that consumes it.
+
+**Do not restate the title.** The title names the change; the reading adds the values, the reason
+and what the change connects to. A reading that says the title again at greater length means the
+title needs work, not the reading.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.files.waypoints.title.md

@@ -0,0 +1,12 @@
+**Say what was done, and to what** — "Modified the file reader to return a reason
+for binary content", "Returns null for a path outside the root". Not a bare noun
+like "The file reader" or "The error path": a noun names which code this is about but not why
+the reader is shown it, which is the one thing a title is for.
+
+**Past tense** — Added, Modified, Removed. Never the identifier on its own.
+
+**One title, one thing.** An arrow, an "and", or three clauses means several
+waypoints crammed into one.
+
+**A child's title is a smaller change than its parent's**, not a different kind
+of thing: same shape, same tense, at every level.

package/backend/configurations/default-configurations/unfamiliar-territory/walkthrough.intro.md

@@ -0,0 +1,5 @@
+One optional line that frames the whole Code Walkthrough: the order the files are read in,
+and why — "The stock check first, then the query it calls."
+
+It names the tour, not the first file. Leave it out when the file order speaks
+for itself.