[Code Quality] Explain .md vs .lock.yml workflow file relationship

[github-actions]

Description

The Quick Start guide mentions editing .md files and compiling to .lock.yml files but never explains the relationship between these files. This is a critical concept that beginners need to understand.

Problem

Current Confusion: Guide mentions:

• "Edit .github/workflows/daily-repo-status.md"
• "Run compile to create .lock.yml"

But never explains:

• Why there are two files
• What .lock.yml is or does
• Whether users should edit .lock.yml (they shouldn't)
• What happens if files get out of sync
• Which file GitHub Actions actually runs

Impact: Beginners wonder "Do I need both files? Which one do I edit? Can I delete one?"

Suggested Changes

Add a callout box early in the Quick Start guide (after Step 2):

:::tip[Understanding Workflow Files]
Agentic workflows use a **two-file system**:

- **`.md` files** - You write your workflow instructions here in plain English (Markdown)
- **`.lock.yml` files** - The compiler automatically generates these GitHub Actions files

**Key points:**
- ✅ Edit only the `.md` file
- ✅ Run `gh aw compile` to update the `.lock.yml` file
- ✅ GitHub Actions runs the `.lock.yml` file
- ❌ Never edit `.lock.yml` directly (changes will be overwritten)

Think of it like source code (`.md`) and compiled binary (`.lock.yml`).
:::

Files Affected

• docs/src/content/docs/setup/quick-start.md (add after Step 2)

Success Criteria

• Explains the purpose of both file types
• Clarifies which file to edit (only .md)
• Uses beginner-friendly analogy (source vs compiled)
• Prevents common mistakes (editing .lock.yml)
• Reduces confusion about file relationship

Source

Extracted from Documentation Noob Test Report discussion #12885

Priority

High - Fundamental concept that affects all workflow editing

Estimated Effort

10 minutes

AI generated by Discussion Task Miner - Code Quality Improvement Agent

• expires on Feb 14, 2026, 9:08 AM UTC