| name | nx-docs-iterate |
| description | Validate-and-ship loop for nx astro-docs changes. Runs prettier, vale, the STYLE_GUIDE structural pass, an anchor sweep, then amends the squashed commit and force-pushes. Use after every docs edit round in the nx repo. Triggers on "docs iterate", "amend and push the docs", "ship the docs change", "docs validate and push". |
nx-docs-iterate
The per-iteration loop for nx astro-docs PRs that keep a single squashed commit and amend
on every review round (NXC-4453 ran this ~15 times). Run it AFTER each edit round, BEFORE
telling Jack it's pushed.
Process
All paths relative to the nx repo root (or worktree).
1. Format
npx prettier --write <changed .mdoc/.mts/.mjs files>
Prettier may reflow Markdoc - re-check {% aside %} blocks with lists (blank line before
{% /aside %} or parsing breaks).
2. Vale (mechanical tier)
cd astro-docs && vale <changed files under src/content/docs/>
Target: 0 errors, 0 warnings. Suggestions in UNTOUCHED sections may stay; fix any in
paragraphs you added.
3. Structural pass (what vale can't see)
Per astro-docs/STYLE_GUIDE.md, on every paragraph added or rewritten:
- Claim calibration: no unsupportable absolutes ("less chance of issues", never "will not
introduce issues").
- Terminology table: "workspace" not "monorepo"; generator not script (gloss once);
Nx Cloud/Console capitalized.
- Bold only for UI labels and term definitions - never emphasis.
- No semicolons, no em/en dashes, ASCII only:
git diff master -- astro-docs/ | grep "^+" | grep -E ';|—|–|→|·' must be empty.
- No trust words (easily/simply/just), no banned AI phrases, no list completing an intro
sentence.
- Golden path check: feature pages teach the default workflow with ONE command form; flags
appear only where the reader makes a real choice (brief why + link), with constraints and
edge cases in the advanced/KB guide; converged sections get merged, not duplicated.
