git:20260929.cd009fc to git:20260930.412913a

17 added, 0 removed. Audit A to A.

---

name: blueprint-polish-survey

description: "Measure the named documents with chaff and choose which to polish, within the agreed number — changing nothing yet."

---

# Choose what to polish

`.blueprint/answers.json` names the documents (`targets`), the style, how far to go (`scope`), the most

files to polish (`maxFiles`) and what to leave alone (`avoid`). The person may not be an engineer: say

what you do in plain words.

Change nothing in the repository: this step only reads and measures. The person approves the list before

any file is touched.

## Measure

Run chaff through the base pack's wrapper, from the folder: `sh <base pack>/checks/chaff.sh <file>`

(add `--compact` for one line per finding). The folder's `chaff.yaml` applies when the answer `style` is

the folder's style; if it is and there is no `chaff.yaml`, stop and say the style has to be made first.

+ With chaff's own style, the answer `kind` says what kind of document this is: measure it as that kind by

+ adding `--genre <genre>` to every chaff run, taking the genre for the answer from `<usecase pack>/kinds.json`

+ (a kind whose genre is `null` adds nothing). The checks measure the same way, so a count taken without it

+ will not match.

For each Markdown or text file under the named paths, count the warnings and errors. Leave out what

`avoid` names.

## Choose

- With `scope` "chaff が指摘した所だけ", or no `scope` at all (it is asked only with this folder's style, so

chaff's default style has no guide to follow), choose files that have findings, most findings first.

- With `scope` including the guide, a file without findings may still be worth polishing against

`STYLE.md`; say why for each.

+ - When the answer `kind` has viewpoints in `<usecase pack>/viewpoints.json`, every named document is worth

+ polishing, findings or not: the polish step reads each for its kind. Choose them all, most findings first.

- No more than `maxFiles`. The rest are for another run: name them in the report.

Write `.blueprint/polish.json`:

```json

{ "targets": [{ "file": "docs/setup.md", "before": 7, "status": "todo" }] }

```

`before` is the number of warnings and errors chaff reports for that file now; the check measures it

again and refuses a number that does not match.

+ **When nothing needs polishing** — every named document has no finding, or has one only in a file `avoid`

+ asks you to leave alone, and the kind has no viewpoints — that is an answer, not a failure: write an empty list, naming the files left

+ alone, and do not ask the person how to go on.

+ ```json

+ { "targets": [], "avoided": ["notes/draft.md"] }

+ ```

+ The check measures every Markdown or text file under the named paths again, and refuses an empty list while

+ one that is not in `avoided` has a finding.

## Done when

`node <usecase pack>/checks/targets.mjs survey` (with `BLUEPRINT_BASE` and `BLUEPRINT_USECASE` set to the

pack folders from your prompt) passes.