Lee las respuestas para decidir qué medir
Unos 20 minutos de lectura, con 2 ejemplos en 6 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.3. Lee el original
Al terminar este capítulo podrás leer un conjunto de respuestas de un asistente, clasificar qué está mal en cada una dentro de un modo de fallo y decir cuáles de esos fallos puede detectar una comprobación.
El capítulo 1 terminó con un límite: veinte elementos pueden encontrar respuestas rotas, pero no pueden ordenar dos prompts. El asistente de este libro responde a partir de tres versiones de la documentación de sablefile, 1.0, 1.1 y 2.0, y una pregunta sobre una versión puede recibir una respuesta que es correcta para otra. Una tasa de aciertos cuenta todos estos fallos de la misma forma y no nombra ninguno. Un equipo que mide solo con una tasa de aciertos escribe sus comprobaciones para los fallos que espera, y los fallos que no espera quedan sin comprobar. Leer las respuestas primero es la manera de encontrar el segundo tipo. El intervalo del capítulo 1 indica cuánto se puede confiar en una puntuación. Este capítulo pregunta en qué se equivoca cada variante, algo que una puntuación no puede decir.
Leer antes de contar tiene respaldo fuera de este libro. El capítulo 1 citó Who Validates the Validators? (2024), de Shankar y colaboradores, para el punto de que las personas refinan sus criterios de evaluación mientras califican las salidas. Ese artículo es sobre todo un sistema, EvalGen, y el estudio con usuarios de nueve profesionales es la parte en la que este capítulo se apoya. La deriva que registra el estudio ocurrió mientras las personas calificaban salidas. Que un cambio en la canalización pueda hacer derivar los criterios es una discusión de los autores, no un hallazgo del estudio. Es un solo estudio, así que este capítulo lo trata como una advertencia y no como un resultado que el libro mide.
Este capítulo usa los 80 elementos de desarrollo, la división del conjunto de prueba con la que trabaja este libro mientras desarrolla sus medidas. Solo lee los elementos de desarrollo, así que nada aquí está ajustado a los elementos reservados, y los recuentos de rechazos de los elementos reservados aparecen en el capítulo 10. La lectura produce tres cosas: una nota sobre cada respuesta, un recuento de los defectos en que caen esas notas y una comprobación candidata para cada defecto. Cada respuesta aquí es una grabación hecha una vez por cada variante y reproducida por los ejemplos, así que la lectura es la misma en cada ejecución. Las citas de respuestas provienen de las salidas grabadas, y las respuestas de referencia aparecen junto a sus elementos, de modo que cualquier línea que el texto cite de ellas puede encontrarse en la salida del ejemplo. Las notas están en un archivo de datos que lee el ejemplo de recuento.
A lo largo del capítulo, una respuesta se considera correcta cuando da la respuesta de referencia, o cuando se niega a responder porque la referencia dice que la documentación no lo dice. Sus citas se comprueban por separado, con la comprobación de citas del capítulo 1 y las comprobaciones del capítulo 4. Cualquier otra cosa es un fallo, y el resto del capítulo dice de qué tipo es. Los mismos pasos sirven con un archivo de reproducción propio. Agrupa sus respuestas por tipo, lee cada una frente a su referencia, codifica cada una por su defecto principal y escribe una comprobación candidata por cada modo. Este capítulo hace eso con las respuestas de sablefile, para que puedas seguir cada paso con datos que puedes abrir.
Este capítulo no elige las comprobaciones ni escribe la rúbrica de un juez, y no estima con qué frecuencia aparece cada modo en el uso real. Eso llega en capítulos posteriores, y cada uno de ellos depende de los modos nombrados aquí.
Cómo son las respuestas
Tres variantes del asistente respondieron a los mismos elementos de desarrollo, y cada comparación de este capítulo pone las respuestas de una variante junto a las de otra. La línea base es la configuración que midió el capítulo 1. Recupera secciones solo de la versión por la que pregunta la consulta, de modo que su contexto contiene la documentación de una sola versión. La variante sin filtro elimina el filtro de versión de la línea base. Su contexto puede contener secciones de las tres versiones, cada una marcada con su versión, así que el modelo puede detectar una discrepancia, pero también puede copiar el texto de la versión equivocada. La variante con segundo modelo mantiene el prompt de la línea base y entrega la respuesta a un modelo más pequeño, Qwen3 de 0.6 mil millones de parámetros en una compilación de 8 bits. El prompt es el mismo, así que cualquier diferencia respecto a la línea base procede del modelo, no del prompt.
Cada elemento de desarrollo tiene un tipo, y el tipo indica cómo es una respuesta correcta. Un elemento respondible es uno que la documentación responde. Un elemento no respondible pide algo que la documentación no dice, y la respuesta correcta es una negativa con las palabras que se le dieron al asistente: "The docs don't say." Un elemento dependiente de la versión tiene una respuesta que cambia según la versión consultada, de modo que la misma pregunta hecha sobre dos versiones puede tener dos respuestas correctas. Un elemento ambiguo puede leerse de dos maneras, y la documentación responde a cada lectura. Algunos elementos son plantados, escritos para atrapar un error concreto. La salida indica el motivo de cada elemento plantado, que es uno de estos: una premisa falsa, un término casi equivalente, un cambio de versión, una respuesta desactualizada o un destino ambiguo. Una respuesta que falla un elemento plantado muestra si el asistente cometió el error para el que se escribió ese elemento.
Leer un elemento lleva tres pasos. Empieza por la pregunta y su versión, ya que una respuesta solo es correcta para la versión que nombra. Después lee la respuesta de referencia, que es la declaración del autor sobre lo que dice una respuesta correcta. Luego compare cada una de las tres respuestas con ella, una por una. Solo después de eso un lector las agrupa o las cuenta.
El ejemplo que sigue es donde empieza el capítulo. Muestra cada elemento de desarrollo con su respuesta de referencia y la respuesta de cada variante, agrupados por tipo y ordenados por ID, de modo que las tres respuestas a una misma pregunta quedan en líneas contiguas. Lee a lo largo de las líneas de un elemento, no hacia abajo por la columna de una sola variante. Las variantes fallan de maneras distintas ante la misma pregunta, y esa diferencia es lo que hay que ver. Cada respuesta se corta en sus primeros 120 caracteres, y su línea indica si la respuesta fue una negativa y qué citó. Una respuesta que contiene la frase de negativa dentro de otro texto aparece marcada como frase, no como negativa, para que veas dónde traza el analizador la línea.
1"""Prints the dev items, grouped by kind and sorted by ID, with each item's reference answer and the baseline,2unfiltered and second-model replies.34The reference is printed in full under its item, since the reading compares each reply with it. Each reply is one line:5whether it declined, its citations, and its first 120 characters. The reader's job is to set these side by side and6see which failure each reply shows (the codes are in data/failure-codes.json)."""7import lib # first: fixes the thread counts and seeds before anything else loads89from lib.contract import DECLINE, parse_reply10from lib.prompts import P1_SHA25611from lib.replay import ReplayModel12from lib.testset import load_items1314RECORDINGS = { # the three variants, in the order the chapter discusses them15 "baseline": "assistant-baseline",16 "unfiltered": "assistant-unfiltered",17 "second-model": "assistant-second-model",18}19KINDS = ("answerable", "unanswerable", "version-dependent", "ambiguous") # plan section 3.1 order20SHOWN = 120 # characters of each reply printed; the full text is in the recording2122# The prompt hash is checked here, so a recording made from another prompt fails to load.23models = {name: ReplayModel(recording, P1_SHA256) for name, recording in RECORDINGS.items()}24items = load_items(split="dev") # dev only: the held-out items are not read in this chapter (plan section 3.4)2526for kind in KINDS:27 group = [item for item in items if item.kind == kind] # load_items already sorts by ID28 print(f"## {kind}: {len(group)} dev items")29 for item in group:30 planted = f"planted ({item.planted_why})" if item.planted else "not planted"31 print(f"{item.id} | version {item.version} | {planted} | {item.question}")32 reference = item.reference_answer or "none: the item is unanswerable, so the right reply declines"33 print(f" reference: {reference}")34 for name in RECORDINGS:35 reply = parse_reply(models[name].reply(item.id, 0))36 if reply.declined:37 mark = "declined"38 elif DECLINE in reply.text:39 # The phrase is there, but with other text: the parser does not call that a decline.40 mark = "decline phrase with other text"41 else:42 mark = f"cites {' '.join(reply.citations)}" if reply.citations else "no citation"43 text = reply.text.replace("\n", " ") # a reply may hold line breaks; one line keeps the output readable44 more = "..." if len(text) > SHOWN else ""45 print(f" {name} ({mark}): {text[:SHOWN]}{more}")
python read-replies-dev.py## answerable: 40 dev items
q-0005 | version 2.0 | planted (near-miss-term) | Does sablefile 2.0 still read sablefile.lock in my project root?
reference: Only as a fallback. If the new file is missing and an old sablefile.lock is present, a 2.0 command reads the old file but warns you about it. Once the new file exists, 2.0 reads only that one, and sablefile never deletes the old file.
baseline (cites install-upgrade): No, sablefile 2.0 does not read `sablefile.lock` in the project root. Version 2.0 moves the lock file to a new place. Th...
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0006 | version 2.0 | not planted | Is there a way to make check exit with status 0 even when a file has drifted in 2.0?
reference: Yes. Pass --no-fail to check. It still prints each DRIFT line, but it exits with status 0, so a script can report drift without failing. The flag changes nothing except the exit status.
baseline (cites no-fail-flag): Yes, there is a way to make `check` exit with status 0 even when a file has drifted in 2.0. Use the `--no-fail` flag wit...
unfiltered (cites no-fail-flag): Yes, there is a way to make `check` exit with status 0 even when a file has drifted in version 2.0. Use the `--no-fail` ...
second-model (cites no-fail-flag): The `--no-fail` flag is used to make the check exit with status 0 even when files have drifted. [sec:no-fail-flag]
q-0007 | version 1.1 | not planted | In 1.1, will an ignore entry of docs/**/*.tmp catch a file two folders down, like docs/x/y/a.tmp?
reference: Yes. Version 1.1 adds the double-star pattern, which matches zero or more folders. So docs/**/*.tmp matches docs/x/y/a.tmp as well as files directly in docs.
baseline (cites ignore-recursive): Yes, an ignore entry of `docs/**/*.tmp` will catch a file two folders down, like `docs/x/y/a.tmp`. [sec:ignore-recursive...
unfiltered (cites ignore-recursive): Yes, in version 1.1, an ignore entry of `docs/**/*.tmp` will catch a file two folders down, like `docs/x/y/a.tmp`. [sec:...
second-model (no citation): The docs section does not allow for an ignore entry of docs/**/*.tmp to catch a file two folders down, as per the rules....
q-0008 | version 2.0 | not planted | In 2.0, is there a way to re-include something that an earlier ignore line had excluded?
reference: Yes, with a leading exclamation mark. A line that starts with ! negates an earlier match, so a later line can restore a file that an earlier line ignored.
baseline (cites ignore-syntax): Yes, in 2.0, you can re-include something that an earlier ignore line had excluded by using a leading `!` to negate an e...
unfiltered (cites ignore-syntax): Yes, in version 2.0, you can re-include something that an earlier ignore line had excluded by using a leading `!` to neg...
second-model (declined): The docs don't say.
q-0009 | version 1.0 | not planted | What does one line of the 1.0 lock file hold?
reference: The SHA-256 hash of a generated file's content, then two spaces, then that file's path. The 1.0 lock has no mode field.
baseline (cites lockfile): One line of the 1.0 lock file holds the SHA-256 hash of the file's content, two spaces, then the path. [sec:lockfile]
unfiltered (cites lockfile): One line of the 1.0 lock file holds the SHA-256 hash of the file's content, then the file's mode, then the path. [sec:lo...
second-model (cites lockfile): The lock file holds the SHA-256 hash of the file's content, two spaces, and the path. [sec:lockfile]
q-0010 | version 2.0 | not planted | Will syncing the same content twice in 2.0 produce a different lock file each time?
reference: No. The 2.0 lock file is JSON with no timestamps, so the same content always gives back an identical file.
baseline (cites lockfile): No, syncing the same content twice in 2.0 will not produce a different lock file each time. The lock file has no timesta...
unfiltered (cites lockfile): No, syncing the same content twice in 2.0 will produce an identical lock file each time because the lock file has no tim...
second-model (declined): The docs don't say.
q-0011 | version 1.1 | not planted | How many times does 1.1 retry a remote template fetch that keeps failing, and can a flag change that?
reference: Five times, before the command gives up. In 1.1 that number is fixed, and no flag or setting can change it.
baseline (cites remote-retries): The count is fixed in 1.1, and no flag or setting changes it. [sec:remote-retries]
unfiltered (cites remote-retries): In version 1.1, sablefile retries a remote template fetch up to 5 times before giving up. The count is fixed and no flag...
second-model (cites remote-retries): The count is fixed in 1.1, and no flag or setting changes it. [sec:remote-retries]
q-0012 | version 2.0 | not planted | I want sync to retry a slow remote template only twice in 2.0. What do I pass?
reference: Pass --retries 2 to sync. The flag sets how many times a failed fetch is retried, in place of the default of five, and it only affects the command it is given to.
baseline (cites retries-flag): Pass `--retries 2` to sync. [sec:retries-flag]
unfiltered (cites retries-flag): Pass `--retries 2` to sync. [sec:retries-flag]
second-model (cites retries-flag): `--retries 2` to pass. [sec:retries-flag]
q-0013 | version 1.0 | not planted | In 1.0, which table in sablefile.toml holds the values a placeholder can name?
reference: The [values] table. Each name in it can be used as a placeholder, and a placeholder name in a template must match a key in that table.
baseline (cites config-values): The `[values]` table holds the values a placeholder can name. [sec:config-values]
unfiltered (cites config-values): The `[values]` table in sablefile.toml holds the values a placeholder can name. [sec:config-values]
second-model (cites config-values): The values table holds the values a placeholder can name. [sec:config-values]
q-0014 | version 1.1 | not planted | What does sablefile init put into a new sablefile.toml in 1.1?
reference: A [values] table with one entry, project, set to the folder's name, and no [[file]] tables. init writes no other file.
baseline (cites init-command): `sablefile init` creates `sablefile.toml` in the folder where you run it, or in the folder you name. The new file has a ...
unfiltered (cites init-command): `sablefile init` creates `sablefile.toml` in the folder where you run it, or in the folder you name. The new file has a ...
second-model (declined): The docs don't say.
q-0051 | version 2.0 | planted (near-miss-term) | My 1.x ignore file uses shell globs, so does *.log only match files in the top folder in 2.0?
reference: No. Shell glob rules no longer apply in 2.0. Entries use gitignore syntax, so *.log matches at any depth, and a trailing slash limits an entry to directories.
baseline (cites ignore-syntax): In 2.0, entries use gitignore syntax. A line such as `*.log` matches at any depth. Therefore, `*.log` matches files in a...
unfiltered (cites ignore-syntax): No, in 2.0, `*.log` matches at any depth, not just in the top folder. [sec:ignore-syntax]
second-model (declined): The docs don't say.
q-0052 | version 2.0 | planted (near-miss-term) | I have {{project}} all through my templates from 1.x. Is that still valid in 2.0?
reference: No. In 2.0 each placeholder is written as a dollar sign and braces, ${project}. The double-brace form is an error: rendering fails, sync reports the file and line, and it exits with status 1.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0053 | version 2.0 | planted (stale-answer) | I have an old sablefile.lock from 1.1. When I first run sync --apply under 2.0, what happens to it?
reference: 2.0 writes a new .sablefile/lock.json holding each file's hash and, where the old file recorded one, its mode. The old file is not deleted, so you remove it yourself. A warning is printed when 2.0 reads the old file.
baseline (cites lock-migration): When a 2.0 command finds an older `sablefile.lock` and no `.sablefile/lock.json`, it reads the old file and prints a war...
unfiltered (cites lock-migration): When a 2.0 command finds an older `sablefile.lock` and no `.sablefile/lock.json`, it reads the old file and prints a war...
second-model (cites lock-migration): The old `sablefile.lock` file from version 1.1 is not written to the new lock file, so it remains unchanged. [sec:lock-m...
q-0054 | version 2.0 | planted (stale-answer) | Does the 2.0 lock keep each generated file's mode, and what happens to modes from an old lock?
reference: Yes. 2.0 records each generated file's mode in .sablefile/lock.json. When a 2.0 command migrates an older lock, it keeps each mode that the old file has.
baseline (cites lock-mode lock-migration): Yes, the 2.0 lock keeps each generated file's mode, the Unix permission bits such as `0644`, in `.sablefile/lock.json` [...
unfiltered (cites lock-mode lock-migration): Yes, the 2.0 lock keeps each generated file's mode, the Unix permission bits such as `0644`, in `.sablefile/lock.json` [...
second-model (cites lock-mode lock-migration): The 2.0 lock keeps each generated file's mode, as specified in [sec:lock-mode]. When a lock file is migrated from `sable...
q-0055 | version 2.0 | planted (stale-answer) | How do I make sync retry a remote template fetch fewer times in 2.0?
reference: Pass --retries N with the number you want, for example --retries 1. The flag sets the retry count for sync and diff; without it the default is five.
baseline (cites retries-flag): Use the `--retries N` flag to set the number of times `sync` retries a failed fetch of a remote template, where N is a w...
unfiltered (cites retries-flag): To make `sync` retry a remote template fetch fewer times in version 2.0, use the `--retries N` flag where N is a whole n...
second-model (cites retries-flag): The `--retries` flag sets how many times `sync` and `diff` retry a failed fetch of a remote template, in place of the de...
q-0056 | version 1.0 | not planted | Does sablefile check need a network connection to run in 1.0?
reference: No. check does not fetch remote templates or render templates, so it works without a network.
baseline (cites check-command): No, sablefile check does not need a network connection to run. [sec:check-command]
unfiltered (cites remote-fetch-failure): Yes, sablefile checks need a network connection to run in 1.0, as it requires fetching remote templates, and if a remote...
second-model (declined): The docs don't say.
q-0057 | version 2.0 | not planted | Will check pick up a change that someone made on a remote template's server?
reference: No. check never fetches remote templates, so only the next sync's output and the output of diff reflect that change.
baseline (cites remote-retries): No, `check` does not see changes on a remote template's server. [sec:remote-retries]
unfiltered (cites remote-retries): No, `check` does not fetch anything and never retries, so it will not pick up a change that someone made on a remote tem...
second-model (cites remote-templates): Check does not see changes on a remote template's server. A change on the server affects what the next sync writes and w...
q-0058 | version 2.0 | not planted | If I run check --no-fail while drift is present, what does its printed output look like?
reference: It still prints a DRIFT line and the path for each drifted file. The flag only changes the exit status to 0.
baseline (cites quickstart-check): Run `sablefile check` after a sync. If no output appears, no generated file has drifted since the last sync. To see what...
unfiltered (declined): The docs don't say.
second-model (no citation): The check prints `DRIFT` and the path, and exits with status 1. A check with no drift exits with status 0. Pass `--no-fa...
q-0059 | version 1.1 | not planted | What is the mode that sablefile 1.1 stores for each generated file, and which command stores it?
reference: The Unix permission bits of the file, such as 0644. sync saves it for every file it writes.
baseline (cites lock-mode lock-mode): The mode that sablefile 1.1 stores for each generated file is the Unix permission bits, such as `0644` [sec:lock-mode]. ...
unfiltered (cites lock-mode): The mode that sablefile 1.1 stores for each generated file is the Unix permission bits, such as `0644`. The `sync` comma...
second-model (cites lock-mode lock-mode): The mode that sablefile 1.1 stores for each generated file is described in [sec:lock-mode]. The command that stores it i...
q-0060 | version 2.0 | not planted | What top-level keys does the 2.0 lock file JSON contain?
reference: A format key, set to the string 2.0, and a files key that maps each generated path to its SHA-256 hash and mode.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (no citation): The 2.0 lock file JSON contains keys: `lock.json`.
q-0061 | version 1.0 | not planted | What is the usual way to preview sync's changes in 1.0 before writing?
reference: Run sablefile diff. It shows the differences between each rendered template and its target on disk, without writing any file or changing the lock.
baseline (cites diff-command): Run `sablefile diff` to preview sync's changes before writing. [sec:diff-command]
unfiltered (cites sync-default): To see the changes before they are written, run `sablefile diff`, which shows the same differences without writing anyth...
second-model (cites diff-command): The usual way to preview sync's changes in 1.0 before writing is to use `sablefile diff`. [sec:diff-command]
q-0062 | version 2.0 | not planted | Can I point sablefile init at a folder other than the current one in 2.0?
reference: Yes. Give the folder as an argument, such as init path/to/folder. The folder must already exist, and a relative path is read from the folder where you run the command.
baseline (cites init-directory): Yes, you can point `sablefile init` at a folder other than the current one. To do this, provide the path to the folder a...
unfiltered (cites init-directory): Yes, you can point `sablefile init` at a folder other than the current one in 2.0. To do this, give the folder as an arg...
second-model (declined): The docs don't say.
q-0063 | version 1.1 | not planted | If a target sits in folders that do not exist yet, what does sync do in 1.1?
reference: It creates the missing folders before it writes the file, so no setup is needed. sync never removes a folder, even one that ends up empty.
baseline (declined): The docs don't say.
unfiltered (cites sync-create-dirs): If a target sits in folders that do not exist yet, sync creates the folder before it writes the file in version 1.1. [se...
second-model (no citation): The lockfile is `sablefile.lock` in the project root. It holds one line for each generated file: the SHA-256 hash of the...
q-0064 | version 2.0 | not planted | After I delete a target from sablefile.toml, does sync --apply in 2.0 remove its now-empty folder?
reference: No. A sync run never deletes a directory, which means any empty ones you leave behind remain.
baseline (cites sync-create-dirs): No, sync --apply does not remove empty folders. sync never removes a folder, so empty folders you leave behind stay wher...
unfiltered (cites sync-create-dirs): No, sync --apply in 2.0 does not remove its now-empty folder. sync never removes a folder, so empty folders you leave be...
second-model (declined): The docs don't say.
q-0065 | version 1.0 | not planted | Where can template files sit inside a 1.0 project?
reference: Anywhere in the project. The template key in each [[file]] table gives the path from the project folder, and a template is read only when a command renders it.
baseline (cites templates-location): Template files can sit in any folder of the project. [sec:templates-location]
unfiltered (cites templates-location): Template files can sit in any folder of the project. [sec:templates-location]
second-model (no citation): Template files are ordinary text files, and they can sit in any folder of the project. The `template` key in a `[[file]]...
q-0066 | version 2.0 | not planted | Does sablefile run any code that is inside a template?
reference: No. Rendering only substitutes placeholders. It executes nothing in the template, and the same template with the same values always gives the same output.
baseline (cites template-render): No, sablefile does not run any code that is inside a template. Rendering does not run code in the template. [sec:templat...
unfiltered (cites template-render): No, sablefile does not run any code that is inside a template. Rendering does not run code in the template. [sec:templat...
second-model (declined): The docs don't say.
q-0067 | version 1.1 | not planted | Can a [[file]] table in 1.1 take a template that lives at an https address?
reference: Yes. The template key can name an https URL. sablefile fetches it when a command renders the template, and the fetched text is not copied into the project.
baseline (cites remote-templates): Yes, a [[file]] table in 1.1 can take a template that lives at an https address. [sec:remote-templates]
unfiltered (cites config-files-table): Yes, a [[file]] table in 1.1 can take a template that lives at an https address. [sec:config-files-table]
second-model (declined): The docs don't say.
q-0068 | version 2.0 | not planted | What happens when a remote fetch in 2.0 still fails after every retry?
reference: The command halts, reporting the failing address in its error message, and ends with status 1. Targets it never wrote retain their previous lock records.
baseline (cites remote-fetch-failure): If a remote template still cannot be fetched after the last retry, the command stops with an error that names the URL, a...
unfiltered (cites remote-fetch-failure): If a remote template still cannot be fetched after the last retry, the command stops with an error that names the URL, a...
second-model (declined): The docs don't say.
q-0069 | version 1.0 | not planted | What exit status does sync give in 1.0 when a template file is missing?
reference: Status 1. sync cannot finish in that case, and its error message names the file that caused the failure.
baseline (cites sync-exit-status): Sync exits with status 1 when it cannot finish, for example when a template file is missing or a remote template cannot ...
unfiltered (cites sync-exit-status): sync exits with status 1 when a template file is missing. [sec:sync-exit-status]
second-model (cites sync-exit-status): The exit status for sync in 1.0 when a template file is missing is 1. [sec:sync-exit-status]
q-0070 | version 1.1 | not planted | If sync in 1.1 exits with status 0, does that mean the generated text is what I want?
reference: Not necessarily. Status 0 only shows that sync finished, so you should open the generated files and check them.
baseline (cites sync-exit-status): No, if sync exits with status 0, it only means that sync completed successfully, not that the generated text is what you...
unfiltered (cites sync-exit-status): No, if sync in 1.1 exits with status 0, it does not mean the generated text is what you want. A status of 0 shows that s...
second-model (declined): The docs don't say.
q-0071 | version 1.0 | not planted | Where do I list paths for sablefile 1.0 to leave alone, and what happens to them?
reference: In the ignore file .sablefileignore in the project root, with one entry per line. Sync leaves an ignored target unwritten, check and diff both pass over it, and no lock record is made for it.
baseline (cites ignore-file): You list paths for sablefile 1.0 to leave alone in the ignore file, `.sablefileignore`, which sits in the project root. ...
unfiltered (cites ignore-file): List paths for sablefile 1.0 to leave alone in the `.sablefileignore` file, which sits in the project root. Put one entr...
second-model (no citation): The ignore file, `.sablefileignore`, sits in the project root and lists paths that sablefile must leave alone. A project...
q-0072 | version 2.0 | not planted | With --apply, does 2.0's sync write a target that my ignore file lists?
reference: No. An ignored target is never written, and it gets no lock record either.
baseline (cites ignore-file): No, with `--apply`, 2.0's sync does not write a target that is listed in the ignore file. [sec:ignore-file]
unfiltered (cites ignore-file): No, with --apply, 2.0's sync does not write a target that is listed in the ignore file. [sec:ignore-file]
second-model (declined): The docs don't say.
q-0073 | version 2.0 | not planted | Which lines in a 2.0 ignore file are skipped as comments?
reference: Lines that begin with a hash sign. Blank lines are also ignored.
baseline (cites ignore-syntax): Lines that start with `#` are comments. [sec:ignore-syntax]
unfiltered (cites ignore-syntax): Lines that start with `#` are comments. [sec:ignore-syntax]
second-model (declined): The docs don't say.
q-0074 | version 1.1 | not planted | A check in 1.1 reports drift for a file I did not mean to change. What should I do first?
reference: Start with diff, which shows how the file differs from its template. Keep wanted changes by moving them into the template before running sync; discard unwanted ones by reverting the file and running check again.
baseline (cites troubleshoot-drift): Look at the change before you act. Run `sablefile diff` to see how the file differs from its template. [sec:troubleshoot...
unfiltered (cites troubleshoot-drift): Look at the change before you act. [sec:troubleshoot-drift]
second-model (cites check-command): Run `sablefile diff` to see how the file differs from its template. [sec:check-command]
q-0075 | version 2.0 | not planted | After installing the 2.0 archive, how do I confirm which version the shell is running?
reference: Run sablefile --version. The output has the form sablefile 2.0, and that number should match the docs you are reading.
baseline (cites install-check-version): Run `sablefile --version` to see the installed version. [sec:install-check-version]
unfiltered (cites install-check-version): Run `sablefile --version` to see the installed version. The output has the form `sablefile 2.0`. Check that the number m...
second-model (declined): The docs don't say.
q-0076 | version 1.0 | not planted | How do I remove sablefile 1.0 without losing my project's files?
reference: Run python3 -m pip uninstall sablefile. That removes the command and its package, and leaves the project's own files alone, including the config, templates, outputs and lock.
baseline (cites install-uninstall): To remove sablefile 1.0, run `python3 -m pip uninstall sablefile`. This removes the `sablefile` command and its package....
unfiltered (cites install-uninstall): Run `python3 -m pip uninstall sablefile`. This removes the `sablefile` command and its package. It does not change your ...
second-model (declined): The docs don't say.
q-0077 | version 2.0 | not planted | I installed sablefile but my shell says the command is not found. What should I check in 2.0?
reference: Ask pip where it put the package, using pip show sablefile from that very same shell. If a location comes back yet the command fails, the scripts folder may be missing from your path.
baseline (cites troubleshoot-command-not-found): If the shell reports that `sablefile` is not found, the command is not installed in the environment that is active. Run ...
unfiltered (cites troubleshoot-command-not-found): If the shell reports that `sablefile` is not found, the command is not installed in the environment that is active. Run ...
second-model (declined): The docs don't say.
q-0078 | version 1.1 | not planted | Does upgrading sablefile to a newer 1.x archive change any file in my project?
reference: No. The upgrade writes no project file. Read the changelog in the newer version's folder first, since it lists each section whose behaviour changed.
baseline (cites install-upgrade): No, installing a new version of sablefile does not write any project file. [sec:install-upgrade]
unfiltered (cites install-upgrade): No, installing a new version does not write any project file. [sec:install-upgrade]
second-model (declined): The docs don't say.
q-0079 | version 2.0 | not planted | After a 2.0 sync --apply, how do I confirm the template placeholder was filled in?
reference: Open the target, such as README.md, and look for the project name in the spot where the placeholder stood.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0080 | version 1.0 | not planted | What is the difference between a placeholder and a value in sablefile 1.0?
reference: A placeholder is a name in a template that sync replaces. A value is the string in the [values] table that the placeholder's name points to.
baseline (cites glossary-terms): A placeholder is a name in a template that sync replaces with a value, written as `{{project}}` in this version. A value...
unfiltered (decline phrase with other text): The sections do not define or differentiate between a placeholder and a value in sablefile 1.0. [sec:template-render] de...
second-model (no citation): The difference between a placeholder and a value in sablefile 1.0 is that a placeholder is a name in a template that syn...
## unanswerable: 13 dev items
q-0015 | version 1.0 | planted (false-premise) | In sablefile 1.0, what does the --dry-run flag on sync print?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0016 | version 2.0 | not planted | Does sablefile 2.0 run on Windows?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0017 | version 2.0 | not planted | How fast is sablefile check on a project with several thousand generated files?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0018 | version 1.1 | not planted | Can sablefile 1.1 fetch a remote template from a private URL that needs a login token?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (cites remote-retries): Yes, sablefile 1.1 can fetch a remote template from a private URL that needs a login token, as long as the token is incl...
second-model (declined): The docs don't say.
q-0034 | version 1.1 | planted (false-premise) | In sablefile 1.1, what does sync --apply write to the lock file?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (cites sync-lock-update): The lock file is how check finds drift, so run sync after each change you intend to keep. Commit the lock file with the ...
q-0035 | version 1.0 | planted (false-premise) | Does check in sablefile 1.0 have a --no-fail option?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0036 | version 1.1 | planted (false-premise) | In sablefile 1.1, what does the --quiet flag on sync do?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (cites sync-default): The --quiet flag on sync is used to suppress the display of the diff output. It does not change the lock file or the syn...
q-0037 | version 1.0 | not planted | In sablefile 1.0, what happens when a template uses a placeholder whose name is not in [values]?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0038 | version 2.0 | not planted | Is there a maximum number of templates a 2.0 project can have?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0039 | version 1.1 | not planted | What exit status does sablefile diff return when it finds differences in 1.1?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (cites check-exit-status): When check finds a drifted file, it prints `DRIFT` and the path, and exits with status 1. [sec:check-exit-status]
second-model (declined): The docs don't say.
q-0040 | version 2.0 | not planted | If a file listed in the lock is missing from disk, does check report it in 2.0?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0041 | version 2.0 | not planted | Is there a limit on how long a value in [values] can be?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0042 | version 1.0 | not planted | Can sablefile 1.0 set the output colour through a color key in sablefile.toml?
reference: none: the item is unanswerable, so the right reply declines
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
## version-dependent: 17 dev items
q-0001 | version 1.1 | not planted | In sablefile 1.1, if I run sync with no flags, are the target files written straight away?
reference: Yes. In 1.1 a plain sync writes each target and records it in the lock file. To preview the changes first, run diff, which shows them without writing anything.
baseline (cites sync-default): Yes, if you run `sablefile sync` with no flags, the target files are written straight away. [sec:sync-default]
unfiltered (cites sync-default): Yes, in sablefile 1.1, if you run `sync` with no flags, the target files are written straight away. This is because `sab...
second-model (decline phrase with other text): The docs don't say. The docs don't say.
q-0002 | version 2.0 | not planted | In sablefile 2.0, if I run sync with no flags, are the target files written?
reference: No. In 2.0 a plain sync prints a plan that lists what would be created or updated, and it writes nothing. Adding --apply makes sync write the targets and update the lock file.
baseline (cites sync-default): No, the target files are not written when running `sablefile sync` with no flags. Instead, sync prints a plan and writes...
unfiltered (cites apply-flag): No, in sablefile 2.0, if you run `sync` with no flags, the target files are not written. The `--apply` flag is required ...
second-model (declined): The docs don't say.
q-0003 | version 1.0 | planted (version-swap) | In sablefile 1.0, is ${project} the right way to insert the project name into a template?
reference: No. In 1.0 a placeholder is a name in double braces, written {{project}}. The text ${project} is not a placeholder in 1.0, so it is copied to the output unchanged.
baseline (cites placeholders): No, `${project}` is not the right way to insert the project name into a template in sablefile. The correct way is to use...
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0004 | version 2.0 | not planted | In sablefile 2.0, is ${project} the right way to insert the project name into a template?
reference: Yes. In 2.0 a placeholder is a name with a dollar sign and braces around it, so the form ${project} is replaced by the project value. The old double-brace form is an error.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0021 | version 1.0 | not planted | In sablefile 1.0, does check give a nonzero exit status when a generated file has drifted?
reference: No. In 1.0 check prints DRIFT and the path for a drifted file but exits with status 0, so a script has to read the printed lines to see drift.
baseline (cites check-exit-status): No, check does not give a nonzero exit status when a generated file has drifted. The check command prints "DRIFT" and th...
unfiltered (cites quickstart-check): Yes, in sablefile 1.0, `check` gives a nonzero exit status when a generated file has drifted. This is because, without t...
second-model (cites check-exit-status): The check exits with status 0 even when files have drifted, so a script cannot detect drift from the exit status in this...
q-0022 | version 2.0 | not planted | In sablefile 2.0, does check give a nonzero exit status when a generated file has drifted?
reference: Yes. check exits with status 1 when a file has drifted. Adding --no-fail changes that to status 0 while still printing the DRIFT lines.
baseline (cites check-exit-status): Yes, check gives a nonzero exit status when a generated file has drifted. [sec:check-exit-status]
unfiltered (cites no-fail-flag no-fail-flag): No, in sablefile 2.0, `check` does not give a nonzero exit status when a generated file has drifted if the `--no-fail` f...
second-model (cites check-exit-status): The check exits with a nonzero exit status when a generated file has drifted. [sec:check-exit-status]
q-0023 | version 1.0 | not planted | Does an ignore entry of *.log in sablefile 1.0 skip a target at docs/build.log?
reference: No. In 1.0 each entry is a shell glob matched against the whole target path, and shell globs do not match across folders. The entry only covers files at the top level of the project.
baseline (cites ignore-syntax): Yes, an ignore entry of `*.log` in sablefile 1.0 skips a target at `docs/build.log`. [sec:ignore-syntax]
unfiltered (cites ignore-syntax): Yes, an ignore entry of `*.log` in sablefile 1.0 skips a target at `docs/build.log`. [sec:ignore-syntax]
second-model (cites ignore-syntax): The docs section does not skip the target at docs/build.log. The ignore entry of *.log in sablefile 1.0 does not skip th...
q-0024 | version 2.0 | not planted | Does an ignore entry of *.log in sablefile 2.0 skip a target at docs/build.log?
reference: Yes. In 2.0 entries use gitignore syntax, so a line such as *.log matches at any depth, including docs/build.log.
baseline (cites ignore-syntax): Yes, an ignore entry of `*.log` in sablefile 2.0 skips a target at `docs/build.log`. [sec:ignore-syntax]
unfiltered (cites ignore-syntax): Yes, an ignore entry of `*.log` in sablefile 2.0 skips a target at `docs/build.log`. [sec:ignore-syntax]
second-model (declined): The docs don't say.
q-0025 | version 1.0 | planted (version-swap) | Does the lock file in sablefile 1.0 record each generated file's mode?
reference: No. In 1.0 each lock line holds only the SHA-256 hash and the path, so no mode is recorded.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0026 | version 1.1 | not planted | Does the lock file in sablefile 1.1 record each generated file's mode?
reference: Yes. Each lock line holds the SHA-256 hash, then the file's mode, then the path. check compares only the hash, so a change of mode alone is not reported as drift.
baseline (cites lock-mode): Yes, the lock file in sablefile 1.1 records each generated file's mode. [sec:lock-mode]
unfiltered (cites lock-mode): Yes, the lock file in sablefile 1.1 records each generated file's mode. [sec:lock-mode]
second-model (cites lock-mode): The lock file in sablefile 1.1 records each generated file's mode. [sec:lock-mode]
q-0027 | version 1.0 | not planted | How many times does sablefile 1.0 retry a remote template fetch that keeps failing?
reference: Three retries, after which the command gives up. No flag or setting changes that count in 1.0.
baseline (cites remote-retries): Three times. [sec:remote-retries]
unfiltered (cites remote-retries): Sablefile 1.0 retries a remote template fetch up to 3 times before giving up. [sec:remote-retries]
second-model (cites remote-retries): The count is fixed in 1.0, and no flag or setting changes it. [sec:remote-retries]
q-0028 | version 1.1 | not planted | How many times does sablefile 1.1 retry a remote template fetch that keeps failing?
reference: Five retries, after which the command gives up. In 1.1 no flag or setting can change that count.
baseline (cites remote-retries): Sablefile 1.1 retries a remote template fetch up to 5 times before giving up. [sec:remote-retries]
unfiltered (cites remote-retries): Sablefile 1.1 retries a remote template fetch up to 5 times before giving up. [sec:remote-retries]
second-model (cites remote-retries): The count is fixed in 1.1, and no flag or setting changes it. [sec:remote-retries]
q-0029 | version 1.0 | planted (version-swap) | In sablefile 1.0, does sync --apply create the missing folder for a target?
reference: The 1.0 docs describe no --apply flag. Sync creates a target's missing folder by itself, before it writes the file, so a target such as docs/guide/index.md needs no setup.
baseline (cites sync-create-dirs): Yes, sync --apply creates the missing folder for a target. [sec:sync-create-dirs]
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0030 | version 2.0 | not planted | In sablefile 2.0, does sync --apply create the missing folder for a target?
reference: Yes, but only because --apply is given. In 2.0 a plain sync creates no folder, since it writes nothing, and with --apply the folder is made before the target is written.
baseline (cites sync-create-dirs): Yes, sync --apply creates the missing folder for a target. [sec:sync-create-dirs]
unfiltered (cites apply-flag): Yes, sync --apply creates the missing folder for a target. [sec:apply-flag]
second-model (cites sync-create-dirs): [sec:sync-create-dirs] Folders for targets Yes, with `--apply`, sync creates the missing folders before writing the fi...
q-0031 | version 1.1 | planted (version-swap) | In sablefile 1.1, where is .sablefile/lock.json kept?
reference: The 1.1 docs describe no .sablefile folder. The lock file in 1.1 is sablefile.lock in the project root, with one line for each generated file.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0032 | version 2.0 | not planted | In sablefile 2.0, where is the lock file kept?
reference: In .sablefile/lock.json, a JSON file with a format string and one entry per generated file. A leftover sablefile.lock from 1.x is read with a warning and migrated when a command writes files.
baseline (cites lock-migration): In sablefile 2.0, the lock file is kept in `.sablefile/lock.json`. [sec:lock-migration]
unfiltered (cites lock-migration): In sablefile 2.0, the lock file is kept in `.sablefile/lock.json`. [sec:lock-migration]
second-model (cites lock-mode): The lock file is kept in `.sablefile/lock.json`. [sec:lock-mode]
q-0033 | version 2.0 | not planted | In sablefile 2.0, what does sync print for a target whose content already matches its template?
reference: The word unchanged, as that target's plan line. The plan step itself writes nothing.
baseline (declined): The docs don't say.
unfiltered (cites apply-flag): For a target whose content already matches its template, sync prints "unchanged". [sec:apply-flag]
second-model (declined): The docs don't say.
## ambiguous: 10 dev items
q-0019 | version 2.0 | planted (ambiguous-target) | If I edit the file and then run check, will it fail?
reference: Reading 1: if you edited a generated file (a target), check prints DRIFT and the path for it and exits with status 1, because its hash no longer matches the lock.
Reading 2: if you edited a template, check prints nothing and exits with status 0, since a template change is not drift.
baseline (cites quickstart-check check-exit-status): Yes, if you edit the file and then run `sablefile check`, it will report `DRIFT` and the path of the file, indicating a ...
unfiltered (cites check-exit-status no-fail-flag): Yes, if you edit the file and then run `sablefile check`, it will detect the drift and print `DRIFT` and the path of the...
second-model (cites check-exit-status): If you edit the file and then run `sablefile check`, it will fail because the check will detect a drift and print a `DRI...
q-0020 | version 2.0 | not planted | Does sync change the lock file?
reference: Reading 1: a plain sync, with no flag, writes nothing, so the lock file is left alone.
Reading 2: sync --apply writes the targets and updates .sablefile/lock.json with the hash and mode of each file it wrote.
baseline (cites sync-lock-update): Yes, sync changes the lock file when the `--apply` flag is used. After sync writes a target, it records that file's SHA-...
unfiltered (cites diff-command): No, sync does not change the lock file. [sec:diff-command]
second-model (cites sync-lock-update): The lock file is how check finds drift, so run sync after each change you intend to keep. [sec:sync-lock-update]
q-0043 | version 2.0 | planted (ambiguous-target) | Is it drifted now that I changed the template?
reference: Reading 1: if 'it' means the target, it has not drifted. Nothing has edited the target since the last sync, so check prints nothing for it.
Reading 2: if 'it' means a target that you hand-edited after the last sync, it has drifted, and check prints DRIFT and exits with status 1.
baseline (cites drift-meaning): No, it is not drifted now that you changed the template. A change to a template is not drift, because the generated file...
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0044 | version 2.0 | not planted | Does sync create a folder for a target?
reference: Reading 1: a plain sync writes nothing, so it creates no folder.
Reading 2: sync --apply creates the target's missing folder before it writes the file.
baseline (cites sync-create-dirs): Yes, sync creates a folder for a target if the folder does not exist, but only when the `--apply` flag is used. [sec:syn...
unfiltered (declined): The docs don't say.
second-model (cites sync-create-dirs): Yes, sync creates a folder for a target. [sec:sync-create-dirs]
q-0045 | version 2.0 | not planted | Does --retries change how often the command retries?
reference: Reading 1: for sync and diff, yes. They use the count you give, in place of the default of five.
Reading 2: for check, no. check never fetches a remote template, so it never retries.
baseline (cites retries-flag): Yes, the `--retries` flag changes how often the command retries a failed fetch of a remote template. [sec:retries-flag]
unfiltered (cites retries-flag remote-retries): Yes, the `--retries` flag changes how often the command retries a failed fetch of a remote template. It sets the number ...
second-model (cites retries-flag): The `--retries` flag changes how often the command retries a failed fetch of a remote template, in place of the default ...
q-0046 | version 2.0 | not planted | If I delete sablefile.lock, will check stop reporting drift?
reference: Reading 1: if the old file was the only lock, deleting it leaves check with nothing to read, so check prints an error message instead of DRIFT lines.
Reading 2: once .sablefile/lock.json exists, 2.0 reads only that file, so deleting sablefile.lock changes nothing.
baseline (declined): The docs don't say.
unfiltered (declined): The docs don't say.
second-model (declined): The docs don't say.
q-0047 | version 2.0 | not planted | When does a 2.0 project's old lock file get migrated?
reference: Reading 1: a command that only reads, such as check, reads the old file and prints a warning, but writes nothing, so both files stay as they are.
Reading 2: a command that writes files, such as sync --apply, also writes .sablefile/lock.json and keeps each entry's mode where the old file has one.
baseline (cites lock-migration): When a 2.0 command finds an older `sablefile.lock` and no `.sablefile/lock.json`, it reads the old file and prints a war...
unfiltered (cites lock-migration): When a 2.0 command finds an older `sablefile.lock` and no `.sablefile/lock.json`, it reads the old file and prints a war...
second-model (no citation): The 2.0 project's old lock file is migrated when a 2.0 command finds an older `sablefile.lock` and no `.sablefile/lock.j...
q-0048 | version 1.0 | not planted | In 1.0, does check report the file if I change it?
reference: Reading 1: if 'the file' is a template, no. check does not render templates, so it prints nothing for a template change.
Reading 2: if 'the file' is a generated target you edited, yes. check prints DRIFT and the path for it.
baseline (declined): The docs don't say.
unfiltered (cites check-command): Yes, in 1.0, `check` reports the file if it is changed. [sec:check-command]
second-model (cites check-command): The check command does not report the file if it changes. [sec:check-command]
q-0049 | version 2.0 | not planted | Will init overwrite my config?
reference: Reading 1: if sablefile.toml already exists, init stops with an error and leaves it alone.
Reading 2: if you mean another file in the folder, such as a README, init writes no other file, so it does not touch that file.
baseline (cites init-command): No, init will not overwrite your config. It stops with an error if `sablefile.toml` already exists, so it never overwrit...
unfiltered (declined): The docs don't say.
second-model (cites init-command): init stops with an error if `sablefile.toml` already exists, so it never overwrites your configuration. [sec:init-comman...
q-0050 | version 1.1 | not planted | Does the 1.1 lock file care about a file's mode?
reference: Reading 1: yes, the lock records each generated file's mode alongside its hash.
Reading 2: no, for comparison. check compares only the hash, so a mode-only change is not reported as drift.
baseline (cites lock-mode): Yes, the 1.1 lock file cares about a file's mode. [sec:lock-mode]
unfiltered (cites lock-mode): Yes, the 1.1 lock file cares about a file's mode. The mode field is described in lock-mode, and sync records the mode of...
second-model (cites lock-mode): The 1.1 lock file does not care about a file's mode. The mode field is described in lock-mode. [sec:lock-mode]
Toma el elemento q-0005. Pregunta si sablefile 2.0 todavía lee sablefile.lock en la raíz del proyecto, y es un término casi equivalente plantado, un nombre parecido a uno que usa la documentación, que atrapa una respuesta descuidada. La línea base dice que no y cita una sección sobre la actualización. La respuesta de referencia dice que 2.0 recurre al archivo, con una advertencia, así que el no de la línea base es incorrecto. Las variantes sin filtro y con segundo modelo se niegan ambas a responder, y la documentación sí responde la pregunta, así que sus negativas también son incorrectas.
Las tres respuestas al q-0005 fallan de dos maneras diferentes. Una negativa en un elemento respondible y una respuesta equivocada dada con confianza son fallos distintos, y una comprobación que detecta uno no detecta el otro. Una tasa de aciertos contaría las tres respuestas como fallos y perdería esa diferencia. La nota sobre esta respuesta en el archivo de datos empieza con "says 2.0 never reads sablefile.lock; reference says it falls back to it with a warning." Cada nota dice, en una frase, qué hizo la respuesta y qué dice la referencia, de modo que la agrupación que sigue descansa en algo que un lector puede comprobar. Un recuento puede proceder de defectos distintos, y dos respuestas que fallan igualmente en una tasa de aciertos pueden ser fallos diferentes. Por eso las respuestas van antes que el recuento.
La comparación tiene límites, y estos acotan lo que los recuentos pueden afirmar. Los elementos de desarrollo se escribieron para sondear al asistente, y los elementos plantados no son una muestra aleatoria de lo que preguntan los usuarios. Así que los recuentos indican qué variante falla de qué manera en estos elementos. No indican con qué frecuencia un usuario encontraría cada fallo. Para eso haría falta una muestra de preguntas extraída de la forma en que preguntan los usuarios.
Regla práctica: Antes de contar nada, lee las respuestas de todas las variantes, agrupadas por tipo, y anota qué está mal en cada una. Un recuento puede indicar que una variante falla. Solo las respuestas dicen cómo.
Codificación de los fallos
Leer se convierte en contar una vez que cada respuesta tiene una nota y un modo. El modelo redactor escribió una nota por respuesta, como la de q-0005, y luego agrupó las notas. Cada respuesta recibió un solo modo, su defecto principal, y una respuesta sin defecto recibió ok. Los códigos los asignó el modelo de IA que redactó este libro, como único codificador; ningún segundo codificador los revisó y nadie midió el acuerdo entre codificadores. Los 80 elementos de desarrollo dan 240 respuestas, 80 de cada variante. Los códigos están en un archivo de datos junto a los ejemplos, con una entrada por respuesta.
Los recuentos llevan la etiqueta "codificado por el modelo redactor (un codificador; no son etiquetas humanas)", y la etiqueta significa exactamente lo que dice. Este capítulo no tiene una cifra de acuerdo, y nadie más ha reproducido los recuentos. El capítulo 1 planteó el mismo punto: el acuerdo con tus propias etiquetas no calibra un juez. El capítulo 6 lo retoma.
El ejemplo de recuento convierte las notas en cifras, y antes comprueba los códigos. Cada elemento de desarrollo tiene exactamente un código por variante, ningún código nombra un modo que el archivo no defina, y el archivo lleva la etiqueta. Luego imprime una fila por modo y una columna por variante, y una línea etiquetada para cada recuento, que son las cifras que el texto siguiente cita.
1"""Counts the drafting model's failure codes over the dev items, per variant, and prints one table and one labelled line2per count.34The point rests on the table's reading of each mode: the codes were made by the drafting model, as one coder, and are not5human labels. The codes live in data/failure-codes.json; the checks below stop a reply being counted twice or left out.6The labelled lines are the numbers the chapter's prose quotes."""7import lib # first: fixes the thread counts and seeds before anything else loads89import json10from collections import Counter11from pathlib import Path1213from lib.testset import load_items1415CODES = Path(__file__).resolve().parent / "data" / "failure-codes.json"16VARIANTS = ("baseline", "unfiltered", "second-model")1718book = json.loads(CODES.read_text(encoding="utf-8"))19assert book["labelled"] == "coded by the drafting model (one coder; not human labels)", "the codes are the model's, not human labels" # the label the prose uses20assert book["variants"] == list(VARIANTS), "the variants in the file are the three the chapter names"2122dev_ids = {item.id for item in load_items(split="dev")}23n = len(dev_ids)24codes = book["codes"]25assert {code["item"] for code in codes} <= dev_ids, "a code names an item that is not in the dev split"26pairs = [(code["item"], code["variant"]) for code in codes]27# One code per dev item and variant: a pair repeated would be counted twice, a missing one would go unseen.28assert len(pairs) == len(set(pairs)) == n * len(VARIANTS), "expected one code per dev item and variant"29assert all(code["mode"] in book["modes"] for code in codes), "a code uses a mode the file does not define"3031counts = Counter((code["variant"], code["mode"]) for code in codes)32print(f"dev items: {n}")33print(f"replies coded: {len(codes)}")34print(f"labelled: {book['labelled']}")35print(f"{'mode':<22}" + "".join(f"{variant:>14}" for variant in VARIANTS))36for mode in book["modes"]: # the file's order: ok first, then the failure modes37 total = sum(counts[(variant, mode)] for variant in VARIANTS)38 if total == 0: # a mode no variant shows is printed as zero of N, so the reader sees it was looked for39 print(f"{mode}: 0 of {n}")40 continue41 print(f"{mode:<22}" + "".join(f"{counts[(variant, mode)]:>14}" for variant in VARIANTS))42totals = {variant: sum(counts[(variant, mode)] for mode in book["modes"]) for variant in VARIANTS}43assert all(total == n for total in totals.values()), "each variant's counts add up to the dev items"44print(f"{'all modes':<22}" + "".join(f"{totals[variant]:>14}" for variant in VARIANTS))45print()46for variant in VARIANTS: # one labelled line per count, the form the chapter's prose binds to47 for mode in book["modes"]:48 print(f"{mode}, {variant}: {counts[(variant, mode)]}")49 print(f"defective, {variant}: {n - counts[(variant, 'ok')]}")
python tally-failure-modes.pydev items: 80
replies coded: 240
labelled: coded by the drafting model (one coder; not human labels)
mode baseline unfiltered second-model
ok 56 49 24
over-declining 10 15 31
wrong-version-answer 2 3 0
wrong-answer 3 5 9
missed-refusal 0 2 2
incomplete-answer 8 4 7
citation-problem 1 2 6
malformed-reply 0 0 1
all modes 80 80 80
ok, baseline: 56
over-declining, baseline: 10
wrong-version-answer, baseline: 2
wrong-answer, baseline: 3
missed-refusal, baseline: 0
incomplete-answer, baseline: 8
citation-problem, baseline: 1
malformed-reply, baseline: 0
defective, baseline: 24
ok, unfiltered: 49
over-declining, unfiltered: 15
wrong-version-answer, unfiltered: 3
wrong-answer, unfiltered: 5
missed-refusal, unfiltered: 2
incomplete-answer, unfiltered: 4
citation-problem, unfiltered: 2
malformed-reply, unfiltered: 0
defective, unfiltered: 31
ok, second-model: 24
over-declining, second-model: 31
wrong-version-answer, second-model: 0
wrong-answer, second-model: 9
missed-refusal, second-model: 2
incomplete-answer, second-model: 7
citation-problem, second-model: 6
malformed-reply, second-model: 1
defective, second-model: 56
Lee la fila ok, y después las filas debajo de ella. La línea base tiene el mayor número de respuestas sin defecto, 56, y la variante con el segundo modelo tiene el menor, 24. La negativa excesiva es el defecto más frecuente en cada variante. En la variante con el segundo modelo supone más de la mitad de los defectos: 31 de 56.
La línea base tampoco se libra de los defectos más graves. Da 2 respuestas con la versión incorrecta, en q-0023 y q-0029, y la variante sin filtrar da el mayor número, 3. Las negativas omitidas (casos en que debía negarse y no lo hizo) aparecen solo en las variantes, y la línea base no tiene ninguna. Todos los modos aparecen al menos una vez. Un modo que ninguna variante mostrara se imprimiría como cero, de modo que el lector podría ver que se buscó.
Regla práctica: Asigna a cada respuesta una nota y un modo, e imprime una línea etiquetada por cada recuento, para que cada cifra que da el texto pueda comprobarse contra la salida.
Rechazo excesivo
Una respuesta con rechazo excesivo rechaza un elemento que la documentación sí responde. Es el defecto que el lector encuentra primero, porque un rechazo parece prudente, y falla al usuario tanto como una respuesta incorrecta. Los términos que se usan aquí, la frase de rechazo, el elemento sin respuesta y las variantes, están definidos en qué aspecto tienen las respuestas. El recuento abarca todos los elementos que la documentación responde, incluidos los que dependen de la versión, así que para la línea base es mayor que la tasa de rechazos falsos del capítulo 10, que cuenta solo los elementos respondibles. El elemento q-0004 es el caso que depende de la versión y que el capítulo 1 explica por completo. Las tres variantes lo rechazan con las mismas palabras, así que la línea base también lo hace.
Contar los rechazos tiene una trampa, y está en el analizador. El elemento q-0080 es respondible, y la respuesta de la variante sin filtrar a él consta de dos oraciones que dicen que las secciones no definen la diferencia, y termina con la frase de rechazo. La documentación responde la pregunta, así que la respuesta es un rechazo excesivo. El analizador solo cuenta un rechazo cuando la frase es toda la respuesta, así que lee esta como una respuesta que cita una sección. Un lector que busca la frase la encuentra, y una comprobación basada en el analizador la pasa por alto.
La comprobación propuesta es que una respuesta a un elemento cuya referencia nombra una sección de apoyo no debe rechazar, con independencia de las palabras empleadas. Comprobaciones en código construye comprobaciones de ese tipo. Si un rechazo es correcto ante un elemento que la documentación no cubre es un juicio, que el capítulo 10 aborda.
Regla práctica: Cuenta un rechazo por lo que hace la respuesta, no por si la frase aparece sola, y cuenta el rechazo excesivo aparte de las respuestas incorrectas, porque sus comprobaciones son distintas.
Respuestas de versión incorrecta
Una respuesta de versión incorrecta da el comportamiento de otra versión para la versión por la que pregunta la consulta, y puede sonar fluida y citar fuentes aunque sea errónea. En q-0029, la línea base dice que sí, sync --apply crea una carpeta que falta en la 1.0, y cita la sección sobre la creación de carpetas. La nota de la respuesta indica que ese es el comportamiento de la 2.0, y que la 1.0 no tiene ninguna opción --apply en absoluto.
La variante sin filtrar lo hace con más frecuencia. En q-0021 responde que sí a si check devuelve un estado de salida distinto de cero ante una desviación en la 1.0, mientras que la línea base y la variante del segundo modelo responden que no. La nota indica que la respuesta sin filtrar dio la regla de la 2.0 para una pregunta sobre la 1.0. Su contexto contiene todas las versiones, así que la regla de la 2.0 aparece junto a la de la 1.0.
Las citas no lo resuelven. En q-0023, la línea base responde que sí sobre un resultado de la 2.0, y cita la sección de la 1.0. Una comprobación de que cada cita nombra una sección de la versión consultada aprueba esa respuesta. Solo la afirmación, leída frente a la referencia de la 1.0, muestra el error.
Regla práctica: Comprueba la versión de cada respuesta en dos lugares. Sus citas deben pertenecer a la versión consultada, y su afirmación debe coincidir con la referencia de esa versión. Una comprobación solo de las citas deja pasar una respuesta que es correcta sobre la versión equivocada.
Respuestas que faltan a la negativa
Una respuesta que falta a la negativa contesta un elemento sin respuesta con contenido que la documentación no contiene. Es el modo que un lector tiene más probabilidades de creer, porque la respuesta se lee como cualquier otra. Los términos que se usan aquí están definidos en cómo son las respuestas. Los elementos de desarrollo solo lo muestran en las variantes, 2 veces en la variante sin filtrar y 2 en la variante con el segundo modelo, y cada uno es lo bastante breve como para leerlo completo.
En q-0018, la variante sin filtrar dice que un token de inicio de sesión puede enviarse con una descarga remota de plantilla, y cita una sección sobre reintentos. En q-0034, la variante con el segundo modelo da un consejo sobre el archivo de bloqueo, citado a una sección que no cubre la pregunta. En q-0036 dice que --quiet suprime la salida de diff, citando una sección que nunca menciona la opción. En q-0039, la variante sin filtrar responde sobre check cuando la pregunta trata sobre diff. La línea base se niega a responder a todos ellos.
Una comprobación en código puede exigir una negativa en cada elemento sin respuesta, y detectaría cada uno de ellos. En un elemento con respuesta, el mismo fallo pasa inadvertido: una respuesta que cita una sección real que guarda silencio sobre su afirmación pasaría la comprobación, porque responde, como se espera en ese caso. Leer la afirmación frente a la sección citada es el trabajo del capítulo 9 y del capítulo 10.
Regla práctica: Exige una negativa en cada elemento sin respuesta, y lee cada respuesta a uno de ellos frente a la sección que cita antes de contarla como correcta.
De un fallo a una comprobación
Un modo de fallo resulta útil una vez que tiene un candidato a comprobación, y un candidato tiene cuatro partes: el modo, la entrada que lee la comprobación, la afirmación que pone a prueba y lo que no puede ver. Un candidato sin límite declarado no se ha pensado bien. Además, un candidato todavía no es una comprobación. Comprobaciones en código construye las comprobaciones que un programa puede ejecutar, y los juicios pasan a un juez. La lista asigna a cada uno de los siete modos de fallo de codificar los fallos su candidato, y nombra el caso que lo muestra.
- Rechazo excesivo. Una respuesta a un elemento cuya referencia nombra una sección de apoyo no debe rechazar, con ninguna redacción. La comprobación no puede distinguir un rechazo correcto en un elemento que los documentos no cubren de uno incorrecto, así que ese juicio pasa al capítulo 10.
- Respuestas de versión incorrecta. Cada cita debe pertenecer a la versión consultada, y la afirmación debe coincidir con la referencia de esa versión. La primera mitad es una comprobación de código en comprobaciones en código. La segunda, que detecta q-0023, es la corrección de versión del capítulo 9. No puede ver una afirmación que la referencia no cubre.
- Respuestas incorrectas. La afirmación debe coincidir con la respuesta de referencia para la versión consultada, y una respuesta a un elemento ambiguo debe responder a cada lectura, como expone un juez. Un juez con una rúbrica escrita compara cada afirmación con su referencia, como en el capítulo 5. Su caso de prueba es q-0005, donde la línea base dice que 2.0 nunca lee sablefile.lock y la referencia dice que recurre a él. Para los elementos ambiguos la rúbrica debe incluir ambas lecturas en la referencia, como necesita q-0048: la variante sin filtrar dice que sí y la variante del segundo modelo dice que no, y cada una se equivoca en una lectura. El juez también puede equivocarse, lo que mide el capítulo 6.
- Negativas omitidas. Cada respuesta a un elemento sin respuesta debe rechazar, o un lector comprueba su cita contra la sección que nombra. Lo primero es una comprobación de código. Lo segundo es el trabajo del capítulo 9. La comprobación de código no lee el texto de las secciones, así que en un elemento respondible aprueba una respuesta que cita una sección real que guarda silencio sobre su afirmación.
- Respuestas incompletas. La referencia enumera cada número, paso y lectura que necesita una respuesta correcta, y una comprobación de código podría buscar cada uno en la respuesta. Este libro no construye tal comprobación. En q-0011 la línea base dice que el número de reintentos es fijo y que ningún indicador lo cambia, pero nunca da el número. La variante sin filtrar sí lo da, así que una comprobación del número de la referencia suspendería la respuesta de la línea base. Su límite: un número puede aparecer en la respuesta sin ser la respuesta.
- Problemas de citas. Cada cita debe ser una de las secciones de apoyo del elemento. En q-0057 la línea base tiene razón al decir que
checkno ve los cambios en un servidor remoto, pero cita una sección que el elemento no lista como de apoyo, así que la cita no figura en la lista. Una comprobación de código contra esa lista lo detecta. Su límite: una sección listada puede aun así no respaldar la afirmación, lo que requiere un lector, como explica comprobaciones en código. - Respuestas mal formadas. Una comprobación de la forma de la respuesta, frente al formato que pide el prompt, detecta una respuesta que sale en el orden equivocado. La respuesta del segundo modelo a q-0030 pone su cita primero y enreda su frase, aunque su respuesta sea correcta. Su límite: la forma no dice nada sobre la respuesta, así que una respuesta puede superar la comprobación de forma y seguir siendo incorrecta. Las comprobaciones de formato de comprobaciones en código lo construyen.
Cada candidato de la lista nombra la respuesta que habría detectado, y esa es su primera prueba. Si un candidato no marca la respuesta para la que fue escrito, todavía no es una comprobación para ese modo.
Construye primero las comprobaciones de código. Se ejecutan en segundos y no necesitan llamada a ningún modelo, así que pueden correr en cada cambio. Un juez cuesta una llamada al modelo por cada respuesta y necesita su propia calibración, así que se reserva para los modos que una referencia y una cita no pueden resolver. Las respuestas incorrectas necesitan uno para la afirmación. Las respuestas de versión incorrecta necesitan uno solo para la parte que contrasta una afirmación con su referencia, y las negativas omitidas solo para la parte que contrasta una afirmación con la sección que cita.
En producción los modos no llegan etiquetados. Un usuario informa de una respuesta incorrecta, y la primera pregunta es de qué modo se trata, porque una comprobación escrita para el modo equivocado aprueba la respuesta que falló. Cuando ningún modo encaja, vuelve a leer las respuestas fallidas, codifícalas, añade un modo y escribe su comprobación. Por eso este capítulo lee y codifica las respuestas antes de contar nada.
La lista no está cerrada: los elementos reservados y cualquier variante posterior mostrarán modos que estos elementos no tienen, y cada uno necesitará su propia nota y su propio candidato.
El capítulo tomó estas decisiones:
- Un solo codificador hizo los códigos: el modelo redactor. Están etiquetadas como tales, y no se mide ningún acuerdo.
- Los elementos de desarrollo son los únicos leídos aquí; los recuentos de rechazo de los elementos reservados aparecen en el capítulo 10.
- Las respuestas de la línea base se cuentan junto con las variantes, así que sus 2 respuestas de versión incorrecta se reportan como tales.
Regla práctica: Codifica las respuestas por su defecto principal antes de elegir una comprobación, y escribe cada comprobación para un solo modo. Una comprobación construida a partir de los fallos que esperabas prueba esos fallos, y aprueba los que no esperabas.
Este capítulo, en esta edición
Edición 2026.11.3Ejemplos verificados el 21 de nov de 2026Superan la prueba 2 de 2 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.3.