blueprint-polish-polish

Polish one file

Take the first file in .blueprint/polish.json whose status is "todo". Polish that file only; the next round takes the next one. When the list is empty, the survey found nothing to polish: change nothing and stop.

First, keep the original

Copy the file to .blueprint/originals/<the same path> before changing anything (create the folders). The check compares against it, and it is how the person undoes a change.

What may change, and what may not

The document must still say the same thing. What changes is how it is said.

• May change: wording, sentence length and endings, spacing, spelling to the team's terms, splitting a long sentence or paragraph, removing padding.
• May not change — the check compares these with the original and fails on any difference:
  • the headings, in order and word for word (other documents link to them);
  • the articles, sections and items chaff reads as the document's structure (chaff tree), so a reference such as "第3条第2項" or "Section 4.2" still points at the same place;
  • code blocks, byte for byte;
  • link targets.
• Never add a fact, a number, a date or a name that is not in the original. Never drop one.

Follow STYLE.md when the answer scope includes the guide; otherwise, and when there is no scope, fix only what chaff reports.

Check it

sh <base pack>/checks/chaff.sh <the file> — with the same --genre as the survey when the answer kind gives one (see <usecase pack>/kinds.json), and --show-baseline when the answer shelved asks for the shelved findings too — must report no warning or error, except the ones you set aside. Set a finding aside — never change the meaning to satisfy a rule — in one of two cases, by adding it to the file's entry in .blueprint/polish.json:

{ "file": "guide.md", "before": 4, "status": "done",
  "dismissed": [{ "rule": "max-sentence-length", "line": 12, "because": "meaning", "why": "条文の引用で、切ると原文と違ってしまう" }] }

• "because": "wrong" — chaff misread the text (a heading it took for a sentence, a name it took for jargon). Each one becomes a draft report to chaff in the report step.
• "because": "meaning" — chaff is right, but fixing it would change what the document says.