Leia as respostas para descobrir o que medir

Cerca de 24 minutos min de leitura, com 2 exemplos em 6 seções.

Edição 2026.11.3 Exemplos aprovados em 21 de nov de 2026 54 de 54 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.3. Leia o original

Ao final deste capítulo, você será capaz de ler um conjunto de respostas de um assistente, classificar o que há de errado em cada uma delas em um modo de falha e dizer quais dessas falhas uma verificação consegue enxergar.

O capítulo 1 terminou com um limite: vinte itens conseguem encontrar respostas erradas, mas não conseguem ordenar dois prompts. O assistente deste livro responde com base em três versões da documentação do sablefile, 1.0, 1.1 e 2.0, e uma pergunta sobre uma versão pode receber uma resposta que está certa para outra. A taxa de acerto conta todas essas falhas do mesmo jeito e não nomeia nenhuma delas. Uma equipe que mede apenas com a taxa de acerto escreve suas verificações para as falhas que espera, e as falhas que não espera ficam sem verificação. Ler as respostas primeiro é o que permite encontrar o segundo tipo. O intervalo do capítulo 1 diz até que ponto se pode confiar em uma pontuação. Este capítulo pergunta o que cada variante erra, o que uma pontuação não consegue dizer.

Ler antes de contar tem apoio fora deste livro. O capítulo 1 citou Who Validates the Validators? (2024), de Shankar e colegas, para o ponto de que as pessoas refinam seus critérios de avaliação enquanto avaliam as saídas. Esse artigo trata principalmente de um sistema, o EvalGen, e o estudo com usuários de nove profissionais é a parte em que este capítulo se apoia. A deriva registrada no estudo aconteceu enquanto as pessoas avaliavam as saídas. Que uma mudança no pipeline possa fazer os critérios derivarem é uma discussão dos autores, não um resultado do estudo. Como se trata de um único estudo, este capítulo o trata como um alerta, não como um resultado que o livro mede.

Este capítulo usa os 80 itens de desenvolvimento, a divisão do conjunto de teste com que este livro trabalha enquanto desenvolve suas medidas. Ele lê apenas os itens de desenvolvimento, de modo que nada aqui foi ajustado aos itens reservados, e as contagens de recusas nos itens reservados aparecem no capítulo 10. A leitura produz três coisas: uma nota sobre cada resposta, uma contagem dos defeitos em que essas notas se enquadram e uma verificação candidata para cada defeito. Cada resposta aqui é uma gravação feita uma vez para cada variante e reproduzida pelos exemplos, de modo que a leitura é a mesma a cada execução. As citações das respostas vêm das saídas gravadas, e as respostas de referência aparecem ao lado de seus itens, de modo que qualquer linha que o texto cite delas pode ser encontrada na saída do exemplo. As notas ficam em um arquivo de dados que o exemplo de contagem lê.

Ao longo do capítulo, uma resposta conta como certa quando dá a resposta de referência, ou quando recusa porque a referência diz que a documentação não trata do assunto. As citações de cada resposta são verificadas à parte, pela verificação de citações do capítulo 1 e pelas verificações do capítulo 4. Qualquer outra resposta é uma falha, e o restante do capítulo diz qual é o tipo. Os mesmos passos funcionam em um arquivo de replay seu. Agrupe as respostas por tipo de resposta, leia cada uma em relação à sua referência, classifique cada uma pelo seu principal defeito e escreva uma verificação candidata por modo. Este capítulo faz isso com as respostas do sablefile, para que você possa acompanhar cada passo com dados que pode abrir.

Este capítulo não escolhe as verificações nem escreve a rubrica de um juiz, e não estima com que frequência cada modo acontece em uso real. Isso vem em capítulos posteriores, e cada um deles depende dos modos nomeados aqui.

Como são as respostas

Última alteração na edição 2026.11.3

Três variantes do assistente responderam aos mesmos itens de desenvolvimento, e cada comparação neste capítulo põe as respostas de uma variante ao lado das de outra. A linha de base é a configuração que o capítulo 1 mediu. Ela recupera seções apenas da versão sobre a qual a pergunta trata, de modo que o contexto contém a documentação de uma única versão. A variante sem filtro retira o filtro de versão da referência. Seu contexto pode conter seções das três versões, cada uma marcada com sua versão, para que o modelo possa perceber uma incompatibilidade e também copiar o texto da versão errada. A variante de segundo modelo mantém o prompt da referência e entrega a resposta a um modelo menor, o Qwen3 com 0.6 bilhão de parâmetros numa versão de 8 bits. Como o prompt é o mesmo, qualquer diferença em relação à referência vem do modelo, não do prompt.

Cada item de desenvolvimento tem um tipo, e o tipo indica como é uma resposta correta. Um item respondível é aquele que a documentação responde. Um item não respondível pede algo que a documentação não diz, e a resposta correta é uma recusa nas palavras que foram dadas ao assistente: "A documentação não diz." Um item dependente da versão tem uma resposta que muda conforme a versão consultada, de modo que a mesma pergunta feita a duas versões pode ter duas respostas corretas. Um item ambíguo pode ser lido de duas maneiras, e a documentação responde a cada uma delas. Alguns itens são plantados, escritos para pegar um erro específico. A saída indica a razão de cada item plantado, que é uma destas: premissa falsa, termo quase idêntico, troca de versão, resposta desatualizada ou alvo ambíguo. Uma resposta que falha num item plantado mostra se o assistente cometeu o erro para o qual aquele item foi escrito.

Ler um item leva três passos. Comece pela pergunta e sua versão, pois uma resposta está correta apenas para a versão que ela menciona. Depois leia a resposta de referência, que é a afirmação do autor sobre o que uma resposta correta diz. Por fim, leia as três respostas em comparação com ela, uma de cada vez. Só depois disso o leitor agrupa as respostas ou as conta.

O exemplo que segue é onde o capítulo começa. Ele imprime todos os itens de desenvolvimento com sua resposta de referência e a resposta de cada variante, agrupados por tipo e ordenados por ID, de modo que as três respostas a uma pergunta fiquem em linhas adjacentes. Leia ao longo das linhas de um item, não de cima para baixo na coluna de uma variante. As variantes falham de maneiras diferentes na mesma pergunta, e essa diferença é o que deve ser observado. Cada resposta é cortada nos primeiros 120 caracteres, e sua linha indica se a resposta recusou e o que citou. Uma resposta que contém a expressão de recusa dentro de outro texto é marcada como expressão, não como recusa, para que você veja onde o analisador traça a linha.

read-replies-dev.py Python 3.12.15 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 Aprovado
"""Prints the dev items, grouped by kind and sorted by ID, with each item's reference answer and the baseline,unfiltered and second-model replies.The reference is printed in full under its item, since the reading compares each reply with it. Each reply is one line:whether it declined, its citations, and its first 120 characters. The reader's job is to set these side by side andsee which failure each reply shows (the codes are in data/failure-codes.json)."""import lib  # first: fixes the thread counts and seeds before anything else loadsfrom lib.contract import DECLINE, parse_replyfrom lib.prompts import P1_SHA256from lib.replay import ReplayModelfrom lib.testset import load_itemsRECORDINGS = {  # the three variants, in the order the chapter discusses them    "baseline": "assistant-baseline",    "unfiltered": "assistant-unfiltered",    "second-model": "assistant-second-model",}KINDS = ("answerable", "unanswerable", "version-dependent", "ambiguous")  # plan section 3.1 orderSHOWN = 120  # characters of each reply printed; the full text is in the recording# The prompt hash is checked here, so a recording made from another prompt fails to load.models = {name: ReplayModel(recording, P1_SHA256) for name, recording in RECORDINGS.items()}items = load_items(split="dev")  # dev only: the held-out items are not read in this chapter (plan section 3.4)for kind in KINDS:    group = [item for item in items if item.kind == kind]  # load_items already sorts by ID    print(f"## {kind}: {len(group)} dev items")    for item in group:        planted = f"planted ({item.planted_why})" if item.planted else "not planted"        print(f"{item.id} | version {item.version} | {planted} | {item.question}")        reference = item.reference_answer or "none: the item is unanswerable, so the right reply declines"        print(f"  reference: {reference}")        for name in RECORDINGS:            reply = parse_reply(models[name].reply(item.id, 0))            if reply.declined:                mark = "declined"            elif DECLINE in reply.text:                # The phrase is there, but with other text: the parser does not call that a decline.                mark = "decline phrase with other text"            else:                mark = f"cites {' '.join(reply.citations)}" if reply.citations else "no citation"            text = reply.text.replace("\n", " ")  # a reply may hold line breaks; one line keeps the output readable            more = "..." if len(text) > SHOWN else ""            print(f"  {name} ({mark}): {text[:SHOWN]}{more}")
Saídapython 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]

Tome o item q-0005. Ele pergunta se o sablefile 2.0 ainda lê o sablefile.lock na raiz do projeto, e é um termo plantado de quase acerto (near-miss), um nome parecido com um que a documentação usa, que pega uma resposta descuidada. A configuração de referência responde não e cita uma seção sobre atualização. A resposta de referência diz que a 2.0 recorre ao arquivo, com um aviso, de modo que o não da referência está errado. As variantes sem filtro e de segundo modelo recusam, e a documentação responde à pergunta, de modo que suas recusas também estão erradas.

As três respostas ao q-0005 falham de duas maneiras diferentes. Uma recusa em item respondível e uma resposta errada dada com confiança são falhas distintas, e uma verificação que pega uma não pega a outra. Uma taxa de acerto contaria as três respostas como falhas e perderia essa diferença. A nota sobre esta resposta no arquivo de dados começa com "diz que 2.0 nunca lê sablefile.lock; a referência diz que ela recorre a ele com um aviso." Cada nota diz o que a resposta fez e o que a referência diz, numa frase, para que o agrupamento que se segue se apoie em algo que o leitor possa conferir. Uma contagem pode vir de defeitos diferentes, e duas respostas que ambas falham numa taxa de acerto podem ser falhas diferentes. Por isso as respostas vêm antes da contagem.

A comparação tem limites, e eles restringem o que as contagens podem afirmar. Os itens de desenvolvimento foram escritos para testar o assistente, e os itens plantados não são uma amostra aleatória do que os usuários perguntam. Assim, as contagens indicam qual variante falha de que maneira nesses itens. Elas não indicam com que frequência um usuário encontraria cada falha. Para isso seria necessária uma amostra de perguntas coletadas da maneira como os usuários perguntam.

Regra prática: Antes de contar qualquer coisa, leia as respostas de todas as variantes, agrupadas por tipo, e anote o que há de errado em cada uma. Uma contagem pode indicar que uma variante falha. Só as respostas dizem como.

Codificando as falhas

A leitura vira contagem quando cada resposta recebe uma anotação e um modo. O modelo que redigiu as respostas escreveu uma anotação por resposta, como a de q-0005, e depois agrupou as anotações. Cada resposta recebeu um modo, o seu principal defeito, e uma resposta sem defeito recebeu ok. Os códigos foram atribuídos pelo modelo de IA que redigiu este livro, como único codificador; nenhum segundo codificador os verificou, e ninguém mediu a concordância entre codificadores. Os 80 itens de desenvolvimento geram 240 respostas, 80 de cada variante. Os códigos ficam em um arquivo de dados ao lado dos exemplos, com uma entrada por resposta.

As contagens trazem o rótulo "codificado pelo modelo redator (um codificador; não são rótulos humanos)", e o rótulo significa exatamente o que diz. Este capítulo não tem nenhum índice de concordância, e ninguém mais reproduziu as contagens. O Capítulo 1 afirmou o mesmo ponto: a concordância com os seus próprios rótulos não calibra um juiz. O Capítulo 6 retoma o assunto.

O exemplo de tabulação transforma as anotações em contagens, e antes disso verifica os códigos. Cada item de desenvolvimento tem exatamente um código por variante, nenhum código nomeia um modo que o arquivo não define, e o arquivo traz o rótulo. Em seguida imprime uma linha por modo e uma coluna por variante, além de uma linha rotulada para cada contagem, que são os números citados na prosa a seguir.

tally-failure-modes.py Python 3.12.15 · numpy 2.5.5 · pydantic 2.14.3 · typing-extensions 4.16.0 Aprovado
"""Counts the drafting model's failure codes over the dev items, per variant, and prints one table and one labelled lineper count.The point rests on the table's reading of each mode: the codes were made by the drafting model, as one coder, and are nothuman labels. The codes live in data/failure-codes.json; the checks below stop a reply being counted twice or left out.The labelled lines are the numbers the chapter's prose quotes."""import lib  # first: fixes the thread counts and seeds before anything else loadsimport jsonfrom collections import Counterfrom pathlib import Pathfrom lib.testset import load_itemsCODES = Path(__file__).resolve().parent / "data" / "failure-codes.json"VARIANTS = ("baseline", "unfiltered", "second-model")book = json.loads(CODES.read_text(encoding="utf-8"))assert 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 usesassert book["variants"] == list(VARIANTS), "the variants in the file are the three the chapter names"dev_ids = {item.id for item in load_items(split="dev")}n = len(dev_ids)codes = book["codes"]assert {code["item"] for code in codes} <= dev_ids, "a code names an item that is not in the dev split"pairs = [(code["item"], code["variant"]) for code in codes]# One code per dev item and variant: a pair repeated would be counted twice, a missing one would go unseen.assert len(pairs) == len(set(pairs)) == n * len(VARIANTS), "expected one code per dev item and variant"assert all(code["mode"] in book["modes"] for code in codes), "a code uses a mode the file does not define"counts = Counter((code["variant"], code["mode"]) for code in codes)print(f"dev items: {n}")print(f"replies coded: {len(codes)}")print(f"labelled: {book['labelled']}")print(f"{'mode':<22}" + "".join(f"{variant:>14}" for variant in VARIANTS))for mode in book["modes"]:  # the file's order: ok first, then the failure modes    total = sum(counts[(variant, mode)] for variant in VARIANTS)    if total == 0:  # a mode no variant shows is printed as zero of N, so the reader sees it was looked for        print(f"{mode}: 0 of {n}")        continue    print(f"{mode:<22}" + "".join(f"{counts[(variant, mode)]:>14}" for variant in VARIANTS))totals = {variant: sum(counts[(variant, mode)] for mode in book["modes"]) for variant in VARIANTS}assert all(total == n for total in totals.values()), "each variant's counts add up to the dev items"print(f"{'all modes':<22}" + "".join(f"{totals[variant]:>14}" for variant in VARIANTS))print()for variant in VARIANTS:  # one labelled line per count, the form the chapter's prose binds to    for mode in book["modes"]:        print(f"{mode}, {variant}: {counts[(variant, mode)]}")    print(f"defective, {variant}: {n - counts[(variant, 'ok')]}")
Saídapython tally-failure-modes.py
dev 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

Leia a linha ok, depois as linhas abaixo dela. A linha de base tem o maior número de respostas sem defeito, 56, e a variante com o segundo modelo tem o menor, 24. A recusa excessiva é o maior defeito em cada variante. Na variante com o segundo modelo ela representa mais da metade dos defeitos: 31 de 56.

A linha de base não escapa dos defeitos mais graves. Ela dá 2 respostas com a versão errada, em q-0023 e q-0029, e a variante sem filtro dá o maior número, 3. As recusas que deixaram de ser feitas aparecem apenas nas variantes, e a linha de base não tem nenhuma. Todo modo aparece pelo menos uma vez. Um modo que nenhuma variante tivesse mostrado seria impresso como zero, para que o leitor visse que ele foi procurado.

Regra prática: Dê a cada resposta uma anotação e um modo, e imprima uma linha rotulada por contagem, para que todo número dado na prosa possa ser conferido com a saída.

Recusa excessiva

Uma resposta com recusa excessiva recusa um item que a documentação responde. É o defeito que o leitor encontra primeiro, porque uma recusa parece cuidadosa, e falha com o usuário tanto quanto uma resposta errada. Os termos usados aqui, a frase de recusa, o item sem resposta e as variantes, estão definidos em como são as respostas. A contagem abrange todos os itens que a documentação responde, inclusive os que dependem da versão, por isso, para a linha de base, ela é maior que a taxa de recusa indevida do capítulo 10, que conta apenas os itens respondíveis. O item q-0004 é o caso dependente da versão que o capítulo 1 explica por completo. As três variantes recusam esse item com as mesmas palavras, portanto a linha de base também faz isso.

Contar recusas tem uma armadilha, e ela está no analisador. O item q-0080 é respondível, e a resposta da variante sem filtro a esse item dá duas frases dizendo que as seções não definem a diferença, e termina com a frase de recusa. A documentação responde a pergunta, então a resposta é uma recusa excessiva. O analisador só conta uma recusa quando a frase é a resposta inteira, então lê esta como uma resposta que cita uma seção. Um leitor que procura a frase a encontra, e uma verificação construída sobre o analisador a deixa passar.

O candidato a verificação é que uma resposta a um item cuja referência nomeia uma seção de apoio não pode recusar, em nenhuma forma de dizer. Verificações em código constrói verificações desse tipo. Se uma recusa está certa num item que a documentação não cobre é uma questão de julgamento, que o capítulo 10 aborda.

Regra prática: Conte uma recusa pelo que a resposta faz, não pelo fato de a frase aparecer sozinha, e conte a recusa excessiva separadamente das respostas erradas, porque suas verificações são diferentes.

Respostas de versão errada

Uma resposta de versão errada apresenta o comportamento de outra versão para a versão sobre a qual a pergunta trata, e pode ser fluente e citada e, ainda assim, estar errada. Na q-0029, a linha de base diz que sim, sync --apply cria uma pasta ausente na 1.0, e cita a seção sobre criação de pastas. A nota sobre a resposta diz que esse é o comportamento da 2.0, e que a 1.0 não tem nenhuma opção --apply.

A variante sem filtro faz isso com mais frequência. Na q-0021, ela responde que sim à pergunta sobre se check devolve um código de saída diferente de zero para divergência na 1.0, enquanto a linha de base e a variante com o segundo modelo respondem que não. A nota diz que a resposta sem filtro aplicou a regra da 2.0 a uma pergunta sobre a 1.0. O contexto dela contém todas as versões, de modo que a regra da 2.0 fica ao lado da regra da 1.0.

As citações não resolvem a questão. Na q-0023, a linha de base responde que sim sobre um resultado da 2.0, e cita uma seção da 1.0. Uma verificação de que toda citação aponta para uma seção da versão perguntada aprova essa resposta. Somente a afirmação, lida em confronto com a referência da 1.0, revela o erro.

Regra prática: Verifique a versão de cada resposta em dois pontos. Suas citações devem pertencer à versão perguntada, e sua afirmação deve corresponder à referência dessa versão. A verificação de citações, por si só, aprova uma resposta que está certa sobre a versão errada.

Recusas perdidas

Uma recusa perdida responde a um item sem resposta com conteúdo que a documentação não contém. É o modo em que o leitor tem mais chance de acreditar, porque a resposta parece qualquer outra. Os termos usados aqui estão definidos em como são as respostas. Os itens de desenvolvimento mostram esse caso apenas nas variantes, 2 vezes na variante sem filtro e 2 na variante com o segundo modelo, e cada um é curto o bastante para ser lido por inteiro.

No q-0018, a variante sem filtro diz que um token de login pode ser enviado com uma busca remota de modelo, e cita uma seção sobre novas tentativas. No q-0034, a variante com o segundo modelo dá uma dica sobre o arquivo de lock, citada em uma seção que não trata da pergunta. No q-0036, ela diz que --quiet suprime a saída do diff, citando uma seção que nunca menciona a opção. No q-0039, a variante sem filtro responde sobre check quando a pergunta trata de diff. A linha de base recusa todos eles.

Uma verificação por código pode exigir uma recusa em todos os itens sem resposta, e capturaria cada um deles. Em um item respondível, a mesma falha passa despercebida: uma resposta que cita uma seção real, mas que não diz nada sobre a afirmação, seria aprovada, porque responde, como se espera de uma resposta ali. Ler a afirmação contra a seção citada é o trabalho do capítulo 9 e do capítulo 10.

Regra prática: exija uma recusa em todo item sem resposta, e leia cada resposta a um item desses contra a seção que ela cita antes de considerá-la correta.

Da falha à verificação

Um modo de falha é útil quando tem um candidato a verificação, e um candidato tem quatro partes: o modo, a entrada que a verificação lê, a afirmação que ela testa e o que ela não consegue enxergar. Um candidato sem limite declarado não foi bem pensado. Um candidato também ainda não é uma verificação. Verificações em código constrói as verificações que um programa pode executar, e os julgamentos ficam a cargo de um juiz. A lista dá a cada um dos sete modos de falha de codificando as falhas o seu candidato, e nomeia o caso que o demonstra.

  • Recusa excessiva. Uma resposta a um item cuja referência nomeia uma seção de apoio não deve recusar, com quaisquer palavras. A verificação não consegue distinguir uma recusa correta em um item que a documentação não cobre de uma recusa errada, então esse julgamento vai para o capítulo 10.
  • Respostas de versão errada. Toda citação deve pertencer à versão pedida, e a afirmação deve corresponder à referência dessa versão. A primeira metade é uma verificação de código em verificações em código. A segunda, que captura q-0023, é a correção de versão do capítulo 9. Ela não consegue enxergar uma afirmação que a referência não cobre.
  • Respostas erradas. A afirmação deve corresponder à resposta de referência para a versão pedida, e uma resposta a um item ambíguo deve responder a cada leitura, como um juiz expõe. Um juiz com uma rubrica escrita compara cada afirmação com a sua referência, como no capítulo 5. Seu caso de teste é q-0005, em que a linha de base diz que 2.0 nunca lê sablefile.lock e a referência diz que ele recorre a ele. Para itens ambíguos, a rubrica deve colocar as duas leituras na referência, como q-0048 exige: a variante sem filtro diz que sim e a variante do segundo modelo diz que não, e cada uma está errada sobre uma leitura. O juiz também pode errar, o que o capítulo 6 mede.
  • Recusas perdidas. Toda resposta a um item sem resposta recusa, ou então um leitor confere sua citação com a seção que ela nomeia. A primeira é uma verificação de código. A segunda é o trabalho do capítulo 9. A verificação de código não lê o texto das seções, então, em um item respondível, ela aprova uma resposta que cita uma seção real silenciosa sobre a sua afirmação.
  • Respostas incompletas. A referência lista cada número, passo e leitura que uma resposta correta precisa, e uma verificação de código poderia procurar cada um na resposta. Este livro não constrói tal verificação. Em q-0011 a linha de base diz que a contagem de tentativas é fixa e que nenhum sinalizador a altera, mas nunca dá o número. A variante sem filtro o informa, então uma verificação pelo número da referência reprovaria a resposta da linha de base. Seu limite: um número pode aparecer na resposta sem ser a resposta.
  • Problemas de citação. Toda citação deve ser uma das seções de apoio do item. Em q-0057 a linha de base está certa ao dizer que check não vê mudanças em um servidor remoto, mas cita uma seção que o item não lista como apoio, então a citação é não listada. Uma verificação de código contra essa lista a captura. Seu limite: uma seção listada ainda pode não apoiar a afirmação, o que exige um leitor, como verificações em código explica.
  • Respostas malformadas. Uma verificação da forma da resposta, contra o formato que o prompt pede, captura uma resposta que sai na ordem errada. A resposta do segundo modelo a q-0030 coloca sua citação primeiro e embaralha a sua frase, embora a sua resposta esteja certa. Seu limite: a forma nada diz sobre a resposta, então uma resposta pode passar na verificação de forma e ainda assim estar errada. As verificações de formato em verificações em código a constroem.

Cada candidato da lista nomeia a resposta que teria capturado, e esse é o seu primeiro teste. Se um candidato não sinaliza a resposta para a qual foi escrito, ele ainda não é uma verificação para o modo.

Construa primeiro as verificações de código. Elas rodam em segundos e não exigem chamada a modelo, então podem rodar a cada mudança. Um juiz custa uma chamada de modelo para cada resposta e precisa de calibração própria, então fica reservado aos modos que uma referência e uma citação não resolvem. Respostas erradas precisam de um para a afirmação. Respostas de versão errada precisam de um apenas para a parte que confronta uma afirmação com a sua referência, e recusas perdidas precisam de um apenas para a parte que confronta uma afirmação com a seção que cita.

Em produção os modos não chegam rotulados. Um usuário relata uma resposta errada, e a primeira pergunta é qual modo é, porque uma verificação escrita para o modo errado aprova a resposta que falhou. Quando nenhum modo serve, releia as respostas com falha, codifique-as, acrescente um modo e escreva sua verificação. É por isso que este capítulo lê e codifica as respostas antes de contar qualquer coisa.

A lista não é fechada: os itens reservados e qualquer variante posterior mostrarão modos que estes itens não têm, e cada um precisará de sua própria nota e de seu próprio candidato.

O capítulo tomou estas decisões:

  • Um único codificador fez os códigos: o modelo de redação. Eles estão rotulados como tal, e nenhuma concordância é medida.
  • Os itens de desenvolvimento são os únicos lidos aqui; as contagens de recusa dos itens reservados aparecem no capítulo 10.
  • As respostas da linha de base são contadas junto com as variantes, então suas 2 respostas de versão errada são relatadas como tais.

Regra prática: Codifique as respostas pelo seu principal defeito antes de escolher uma verificação, e escreva cada verificação para um único modo. Uma verificação construída a partir das falhas que você esperava testa apenas essas falhas, e deixa passar as que você não esperava.

Este capítulo, nesta edição

Edição 2026.11.3Exemplos aprovados em 21 de nov de 20262 de 2 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.3.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 2 de 11: Leia as respostas para descobrir o que medir

  1. Como são as respostas
  2. Codificando as falhas
  3. Recusa excessiva
  4. Respostas de versão errada
  5. Recusas perdidas
  6. Da falha à verificação

Voltar ao topoTodos os capítulos