Step Name Alignment Issues
Found in three workflows that each start the Starlight/Astro documentation preview server (port 4321) and wait for it to become ready. The same two logical steps are named three different ways.
Summary
docs-noob-tester, visual-regression-checker, and daily-multi-device-docs-tester all perform the identical pair of actions — (1) start the docs dev server in the background, (2) poll until port 4321 is open — but use inconsistent step names. Aligning them on the majority forms improves cross-workflow consistency and makes the docs-testing suite easier to scan.
Issues Identified
1. [Medium Priority] Inconsistent "Start" step name: Start documentation server vs Start docs server
Current step names (same action — nohup/make dev-docs/npm run dev on port 4321):
docs-noob-tester.md:46 → Start docs servervisual-regression-checker.md:60 → Start docs serverdaily-multi-device-docs-tester.md:79 → Start documentation server
Issue: Two of the three workflows use Start docs server; the third uses Start documentation server for the same action. docs server is the majority form (2 of 3) and matches the project's shorter docs-related step names (e.g. Install docs dependencies).
Suggested improvement: Rename daily-multi-device-docs-tester's step to Start docs server.
2. [Medium Priority] Inconsistent "Wait" step name: Wait for dev server vs Wait for server readiness
Current step names (same action — until loop polling 127.0.0.1:4321 with a MAX_WAIT timeout):
docs-noob-tester.md:55 → Wait for server readinessdaily-multi-device-docs-tester.md:92 → Wait for server readinessvisual-regression-checker.md:67 → Wait for dev server
Issue: Two of the three workflows use Wait for server readiness; visual-regression-checker uses Wait for dev server for the same readiness poll. Wait for server readiness is the majority form (2 of 3) and more accurately describes the action (it waits for readiness, not merely for the server to exist).
Suggested improvement: Rename visual-regression-checker's step to Wait for server readiness.
Agentic Task Description
To resolve these inconsistencies:
- Confirm equivalence — verify the three start steps and the three wait steps perform the same action (they currently all target the Starlight dev server on port 4321).
- Apply changes in the source
.md files (not the .lock.yml):
daily-multi-device-docs-tester.md:79: Start documentation server → Start docs servervisual-regression-checker.md:67: Wait for dev server → Wait for server readiness
- Recompile — run
gh aw compile daily-multi-device-docs-tester and gh aw compile visual-regression-checker to regenerate the .lock.yml files.
- Verify the regenerated lock files show the aligned names and the workflows still function.
Related Files
.github/workflows/docs-noob-tester.md / .lock.yml (already uses the canonical names).github/workflows/visual-regression-checker.md / .lock.yml.github/workflows/daily-multi-device-docs-tester.md / .lock.yml- Project glossary:
docs/src/content/docs/reference/glossary.md
Priority
Medium Priority — purely cosmetic (no functional impact), but the three workflows form a single docs-testing suite where consistent step naming has clear scanning value.
AI generated by Step Name Alignment for daily maintenance
Generated by 📋 Step Name Alignment · 507.3 AIC · ◷
Step Name Alignment Issues
Found in three workflows that each start the Starlight/Astro documentation preview server (port
4321) and wait for it to become ready. The same two logical steps are named three different ways.Summary
docs-noob-tester,visual-regression-checker, anddaily-multi-device-docs-testerall perform the identical pair of actions — (1) start the docs dev server in the background, (2) poll until port 4321 is open — but use inconsistent step names. Aligning them on the majority forms improves cross-workflow consistency and makes the docs-testing suite easier to scan.Issues Identified
1. [Medium Priority] Inconsistent "Start" step name:
Start documentation servervsStart docs serverCurrent step names (same action —
nohup/make dev-docs/npm run devon port 4321):docs-noob-tester.md:46→Start docs servervisual-regression-checker.md:60→Start docs serverdaily-multi-device-docs-tester.md:79→Start documentation serverIssue: Two of the three workflows use
Start docs server; the third usesStart documentation serverfor the same action.docs serveris the majority form (2 of 3) and matches the project's shorter docs-related step names (e.g.Install docs dependencies).Suggested improvement: Rename
daily-multi-device-docs-tester's step toStart docs server.2. [Medium Priority] Inconsistent "Wait" step name:
Wait for dev servervsWait for server readinessCurrent step names (same action —
untilloop polling 127.0.0.1:4321 with aMAX_WAITtimeout):docs-noob-tester.md:55→Wait for server readinessdaily-multi-device-docs-tester.md:92→Wait for server readinessvisual-regression-checker.md:67→Wait for dev serverIssue: Two of the three workflows use
Wait for server readiness;visual-regression-checkerusesWait for dev serverfor the same readiness poll.Wait for server readinessis the majority form (2 of 3) and more accurately describes the action (it waits for readiness, not merely for the server to exist).Suggested improvement: Rename
visual-regression-checker's step toWait for server readiness.Agentic Task Description
To resolve these inconsistencies:
.mdfiles (not the.lock.yml):daily-multi-device-docs-tester.md:79:Start documentation server→Start docs servervisual-regression-checker.md:67:Wait for dev server→Wait for server readinessgh aw compile daily-multi-device-docs-testerandgh aw compile visual-regression-checkerto regenerate the.lock.ymlfiles.Related Files
.github/workflows/docs-noob-tester.md/.lock.yml(already uses the canonical names).github/workflows/visual-regression-checker.md/.lock.yml.github/workflows/daily-multi-device-docs-tester.md/.lock.ymldocs/src/content/docs/reference/glossary.mdPriority
Medium Priority — purely cosmetic (no functional impact), but the three workflows form a single docs-testing suite where consistent step naming has clear scanning value.