diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index cad109e9d4a..95694b7b915 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -362,7 +362,7 @@ Every agent-created PR automatically runs:
 - `make build` - Ensures Go code compiles
 - `make test` - Runs all unit and integration tests
 - `make lint` - Checks code quality and style
-- `make recompile` - Recompiles all workflows to ensure compatibility
+- `make recompile` - Recompiles all workflows to ensure compatibility. If you edit `.github/workflows/*.md`, run this before committing so the paired `.lock.yml` files stay in sync with CI.
 - `make fmt` - Formats Go code
 - `make lint-errors` - Validates error message quality
 
diff --git a/actions/setup/md/workflow_recompile_issue.md b/actions/setup/md/workflow_recompile_issue.md
index 81509bba9b3..a52e2113173 100644
--- a/actions/setup/md/workflow_recompile_issue.md
+++ b/actions/setup/md/workflow_recompile_issue.md
@@ -8,8 +8,16 @@ The workflows need to be recompiled to regenerate the lock files from the markdo
 
 ## Instructions
 
+If the repository provides a wrapper such as `make recompile`, prefer that command so compilation uses the repository's canonical flags. In `github/gh-aw`, any edit under `.github/workflows/*.md` should be followed by `make recompile` before committing.
+
 Recompile all workflows using one of the following methods:
 
+### Using the repository wrapper
+
+```bash
+make recompile
+```
+
 ### Using gh aw CLI
 
 ```bash
diff --git a/docs/src/content/docs/guides/editing-workflows.md b/docs/src/content/docs/guides/editing-workflows.md
index bb7b2f5f68b..d79fb0f9475 100644
--- a/docs/src/content/docs/guides/editing-workflows.md
+++ b/docs/src/content/docs/guides/editing-workflows.md
@@ -9,6 +9,9 @@ Agentic workflows have two parts: the **YAML frontmatter**, which is compiled in
 
 See [Creating Agentic Workflows](/gh-aw/setup/creating-workflows/) for guidance on creating workflows with AI assistance.
 
+> [!TIP]
+> Working in `github/gh-aw` itself? Treat any edit under `.github/workflows/*.md` as a cue to run `make recompile` before committing. CI checks the generated `.lock.yml` files for drift, so this is the safest default even when you're only changing markdown instructions. For early feedback while iterating locally, you can run `gh aw compile --watch --schedule-seed github/gh-aw`, then finish with `make recompile`.
+
 ## Editing Without Recompilation
 
 You can edit the **markdown body** directly on GitHub.com or in any editor without recompiling. That includes task instructions, output templates, conditional guidance, context, and examples.
@@ -55,6 +58,7 @@ For priority, consider:
 ```
 
 ✅ This change takes effect immediately without recompilation.
+In `github/gh-aw`, still run `make recompile` before committing so CI sees fresh `.lock.yml` files alongside the markdown change.
 
 ## Editing With Recompilation Required
 
diff --git a/scripts/check-stale-lock-files.sh b/scripts/check-stale-lock-files.sh
index 3144b34aae3..f16effc14b3 100755
--- a/scripts/check-stale-lock-files.sh
+++ b/scripts/check-stale-lock-files.sh
@@ -147,6 +147,8 @@ fi
 
 echo -e "${YELLOW}Fix:${NC} Recompile the workflow lock files, then commit them together with their .md sources:"
 echo ""
+echo "If you edited any .github/workflows/*.md file in this repository, run make recompile before committing so the matching .lock.yml files stay in sync."
+echo ""
 echo "  make recompile"
 echo ""
 exit 1
diff --git a/scripts/check-stale-lock-files_test.sh b/scripts/check-stale-lock-files_test.sh
index 0d7a95dec7c..ded3b2ef53d 100755
--- a/scripts/check-stale-lock-files_test.sh
+++ b/scripts/check-stale-lock-files_test.sh
@@ -137,10 +137,10 @@ create_fixture_repo "$T6" "stale-workflow"
 printf '%s\n' "# stale-workflow (edited)" > "$T6/.github/workflows/stale-workflow.md"
 T6_OUT="$TMP_ROOT/t6-output.txt"
 (cd "$T6" && bash "$STALE_SCRIPT" >"$T6_OUT" 2>&1) || true
-if grep -q "make recompile" "$T6_OUT"; then
-    pass "remediation message mentions 'make recompile'"
+if grep -Fq "make recompile" "$T6_OUT" && grep -Fq ".github/workflows/*.md" "$T6_OUT"; then
+    pass "remediation message mentions 'make recompile' and workflow markdown edits"
 else
-    fail "remediation message did not mention 'make recompile'" "$(cat "$T6_OUT")"
+    fail "remediation message did not mention the workflow markdown reminder" "$(cat "$T6_OUT")"
 fi
 
 # ---------------------------------------------------------------------------
diff --git a/scripts/check-workflow-drift.sh b/scripts/check-workflow-drift.sh
index 0e19a3de369..a21d4496f3e 100755
--- a/scripts/check-workflow-drift.sh
+++ b/scripts/check-workflow-drift.sh
@@ -101,6 +101,8 @@ if ! "$BINARY" compile --validate --no-check-update --purge 2>&1; then
     echo ""
     echo -e "${RED}ERROR${NC}: Workflow compilation failed — fix the errors above, then run:"
     echo ""
+    echo "If you edited any .github/workflows/*.md file in this repository, run make recompile before committing so the matching .lock.yml files stay in sync."
+    echo ""
     echo "  make recompile"
     echo ""
     exit 1
@@ -138,6 +140,8 @@ while IFS= read -r file; do
     echo "  $file"
 done <<< "$all_drift"
 echo ""
+echo "If you edited any .github/workflows/*.md file in this repository, run make recompile before committing so the generated .lock.yml files stay in sync."
+echo ""
 echo -e "${YELLOW}Fix:${NC} Regenerate and stage the lock files, then use report_progress:"
 echo ""
 echo "  make recompile"
diff --git a/scripts/check-workflow-drift_test.sh b/scripts/check-workflow-drift_test.sh
index 104464d75fb..cc0157c0160 100644
--- a/scripts/check-workflow-drift_test.sh
+++ b/scripts/check-workflow-drift_test.sh
@@ -64,6 +64,7 @@ trap 'rm -rf "$TMP_ROOT"' EXIT
 TEST1_OUTPUT="$TMP_ROOT/test1-output.txt"
 TEST2_OUTPUT="$TMP_ROOT/test2-output.txt"
 TEST3_OUTPUT="$TMP_ROOT/test3-output.txt"
+TEST4_OUTPUT="$TMP_ROOT/test4-output.txt"
 
 # Test 1: matching lock file exits 0.
 echo "Test 1: matching lock file exits 0..."
@@ -86,6 +87,8 @@ create_fake_binary "$TEST_REPO/fake-gh-aw"
 if (cd "$TEST_REPO" && FAKE_COMPILE_MODE=mutate bash "$DRIFT_SCRIPT" "$TEST_REPO/fake-gh-aw" >"$TEST2_OUTPUT" 2>&1); then
   fail "drift should exit 1" "$(cat "$TEST2_OUTPUT")"
 elif grep -q ".github/workflows/example.lock.yml" "$TEST2_OUTPUT" \
+  && grep -Fq ".github/workflows/*.md" "$TEST2_OUTPUT" \
+  && grep -q "make recompile" "$TEST2_OUTPUT" \
   && grep -q "report_progress" "$TEST2_OUTPUT" \
   && grep -q "^lock: original$" "$TEST_REPO/.github/workflows/example.lock.yml"; then
   pass "drift is reported and the original file is restored"
@@ -106,6 +109,21 @@ else
   fail "missing binary error message was incorrect" "$(cat "$TEST3_OUTPUT")"
 fi
 
+# Test 4: compile failures include the workflow markdown reminder.
+echo "Test 4: compile failures remind contributors to run make recompile..."
+TEST_REPO="$TMP_ROOT/compile-fail"
+mkdir -p "$TEST_REPO"
+create_fixture_repo "$TEST_REPO"
+create_fake_binary "$TEST_REPO/fake-gh-aw"
+if (cd "$TEST_REPO" && FAKE_COMPILE_MODE=fail bash "$DRIFT_SCRIPT" "$TEST_REPO/fake-gh-aw" >"$TEST4_OUTPUT" 2>&1); then
+  fail "compile failure should exit 1" "$(cat "$TEST4_OUTPUT")"
+elif grep -Fq ".github/workflows/*.md" "$TEST4_OUTPUT" \
+  && grep -q "make recompile" "$TEST4_OUTPUT"; then
+  pass "compile failures include the workflow markdown reminder"
+else
+  fail "compile failure reminder was incorrect" "$(cat "$TEST4_OUTPUT")"
+fi
+
 echo
 echo "Tests passed: $TESTS_PASSED"
 echo "Tests failed: $TESTS_FAILED"