Problem
Quick Start Step 2 says add-wizard adds "the workflow file (.md) and its generated GitHub Actions lock file (.lock.yml)" but never explains:
- What a
.lock.yml is
- Why it exists alongside the
.md
- Whether the user should edit it (answer: no — regenerated)
New users are left guessing, and several open community issues touch the lock model (e.g. #34886), suggesting this is a real confusion point.
Evidence
From today's Documentation Noob Test Report (#34871):
A new user has no idea what a .lock.yml file is or why it exists alongside the .md file. This is confusing — why are there two files? What do I do with the .lock.yml? Can I edit it? No explanation is given.
Expected impact
Reduces onboarding confusion and supports the project's docs-noob NPS.
Suggested agent
doc-healer or delight — 2-3 sentence addition + link to the lockfile reference.
Effort
~15 min.
Identified by DeepReport intelligence run on 2026-05-26.
Generated by 🔬 DeepReport - Intelligence Gathering Agent · opus47 11.4M · ◷
Problem
Quick Start Step 2 says
add-wizardadds "the workflow file (.md) and its generated GitHub Actions lock file (.lock.yml)" but never explains:.lock.ymlis.mdNew users are left guessing, and several open community issues touch the lock model (e.g. #34886), suggesting this is a real confusion point.
Evidence
From today's Documentation Noob Test Report (#34871):
Expected impact
Reduces onboarding confusion and supports the project's docs-noob NPS.
Suggested agent
doc-healerordelight— 2-3 sentence addition + link to the lockfile reference.Effort
~15 min.
Identified by DeepReport intelligence run on 2026-05-26.