Inconsistent placeholders cost more than looks: every reuse needs manual editing, and edits get missed. Fix a convention and afterwards you only change values.
Placeholders: brackets with a type prefix
| Form | Means | Example |
|---|---|---|
| [path: ...] | A file or directory | [path: pdfs/] |
| [field: ...] | A column or field name | [field: amount] |
| [range: ...] | A count or interval | [range: first 5] |
| [output: ...] | Artifact filename and format | [output: index.md] |
| [constraint: ...] | A hard limit | [constraint: do not modify originals] |
Why brackets rather than {{double braces}}: recipes often quote code, and double braces collide with template syntax; brackets are never parsed as syntax and read as fill-me-in at a glance.
Three-part read-failure marker
Bad-data handling must be uniform, or you re-decide every time:
[READ FAILED] file: xxx.pdf | reason: no text layer | tried: character extraction
All three parts are required: which file, why it failed, what was attempted. 'Read failed' alone is not enough — the reader cannot tell whether another tool might succeed.
Two companion rules
- No guessing: anything in the body must come from the source; anything derived from a filename is labelled as such.
- The totals equation: every artifact ends with
total = successes + failuresto catch silent skipping.
This does not need to be elegant. Its value is never having to re-decide, not appearance. Once fixed, write it into your recipe template, not into memory.