| 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 with 1Password op-request logging. 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.
4. Anchor sweep (after any heading/section/sidebar change)
cd astro-docs
grep -rhoE "<changed-page-slug>#[a-z0-9-]+" src/content/docs/ | sort -u
grep -E "^#{2,4} " "src/content/docs/<changed page>"
- Deleted anchors can't be redirected - repoint the inbound links.
- Sidebar GROUP label renames: breadcrumbs +
sidebar_group_cards slugify/match labels
exactly. Move/retitle the knowledge-base/<slug>/index.mdoc landing page, update its
group= attr, add redirects in BOTH astro.config.mjs and netlify.toml (before the
/docs/* catch-all).
5. validate-links (when structure changed)
Works in the sandbox if ~/.m2 and ~/.gradle are write-allowlisted (ask Jack to grant
if not):
NX_NO_CLOUD=true npx nx run astro-docs:validate-links
Gotchas: nx reset forces a cold graph (gradle wrapper re-download); nx-dev:next:build
is flaky on cold full rebuilds - run it alone once, then re-run validate-links. Pipe to a
file, not | tail (tail eats the exit code).
6. Amend + push (logged)
git add astro-docs/...
git commit --amend --no-edit --no-verify
Then force-push with the op-request-reason inline log block (see that skill - REQUIRED for
any remote git op):
git push --no-verify --force-with-lease origin <branch>
Report
One line per gate: prettier / vale (errors-warnings-suggestions) / structural / anchors /
validate-links (run or skipped+why) / pushed SHA.
