@@ -122,22 +122,34 @@ Closes #456
122122
123123## Shell and CLI Handling
124124
125- ### Multiline Content Management
125+ ### Multiline Content Management (CRITICAL - HEREDOC RULES)
126+
127+ ** 🚨 MANDATORY HEREDOC FORMAT:**
126128``` bash
127- # Uses cat with heredoc for proper shell escaping
128- cat << 'EOF ' > /tmp/pr-description.md
129+ # ALWAYS use single quotes around EOF delimiter to prevent variable expansion
130+ cat << 'EOF ' > /tmp/pr-description.md
129131## Summary
130- Comprehensive PR description with proper formatting.
132+ Your PR description content here.
133+
134+ ## Implementation Details
135+ - Bullet points work fine
136+ - Code blocks with `backticks` are safe
137+ - Variables like $VAR will NOT be expanded (good!)
131138
132- ## Details
133- - Multiple lines
134- - Code blocks with `backticks`
135- - No shell interpretation issues
139+ Closes #123
136140EOF
137141
138- gh pr create --title " feat: new feature" --body-file /tmp/pr-description.md
142+ # THEN use the file with gh CLI
143+ gh pr create --title " your title" --body-file /tmp/pr-description.md
139144```
140145
146+ ** 🚨 CRITICAL RULES:**
147+ 1 . ** ALWAYS use ` cat << 'EOF' ` ** (with single quotes)
148+ 2 . ** NEVER use ` cat <<EOF ` ** (without quotes) - causes variable expansion
149+ 3 . ** NEVER use ` cat <<"EOF" ` ** (with double quotes) - allows some expansion
150+ 4 . ** NEVER put content directly in ` --body ` ** - use ` --body-file ` always
151+ 5 . ** ALWAYS clean up:** ` rm /tmp/pr-description.md ` after creation
152+
141153### Error Handling
142154- Validates ` gh ` CLI authentication
143155- Checks remote branch existence
@@ -178,11 +190,31 @@ gh pr create --title "feat: new feature" --body-file /tmp/pr-description.md
178190
179191## Target Branch Logic
180192
181- ### Branch Priority
182- 1 . ** Remote rc/ branches:** ` origin/rc/v0.14.0 `
183- 2 . ** Local rc/ branches:** ` rc/v0.14.0 `
184- 3 . ** User specification:** Prompts if no rc/ branch found
185- 4 . ** Fallback:** Uses repository default branch
193+ ### Branch Priority (CRITICAL - NEVER USE STABLE)
194+ 1 . ** Remote rc/ branches:** ` origin/rc/v0.14.0 ` - PRIMARY TARGET
195+ 2 . ** Local rc/ branches:** ` rc/v0.14.0 ` - SECONDARY TARGET
196+ 3 . ** User specification:** MANDATORY prompt if no rc/ branch found
197+ 4 . ** FORBIDDEN:** Never use ` stable ` branch - PRs to stable are ONLY for version releases
198+
199+ ### Branch Detection Rules
200+ ``` bash
201+ # REQUIRED: Always check for rc/ branches first
202+ RC_BRANCH=$( git branch -r | grep ' origin/rc/' | head -1 | sed ' s/.*origin\///' )
203+ if [ -z " $RC_BRANCH " ]; then
204+ RC_BRANCH=$( git branch -l | grep ' rc/' | head -1 | sed ' s/^[* ] *//' )
205+ fi
206+
207+ # CRITICAL: If no rc/ branch exists, STOP and ask user
208+ if [ -z " $RC_BRANCH " ]; then
209+ echo " ❌ ERROR: No rc/ branch found. Cannot proceed."
210+ echo " Available branches:"
211+ git branch -r | grep -v HEAD
212+ exit 1
213+ fi
214+
215+ # Use detected rc/ branch as base
216+ BASE_BRANCH=" $RC_BRANCH "
217+ ```
186218
187219### Version Detection
188220- Uses ` .scripts/semver.sh ` for version information
@@ -224,22 +256,45 @@ feature ui complexity-medium
224256v0.14.0
225257```
226258
227- ### GitHub CLI Command
259+ ### GitHub CLI Command (CORRECTED)
228260``` bash
261+ # CRITICAL: Always detect rc/ branch first - NEVER hardcode stable
262+ RC_BRANCH=$( git branch -r | grep ' origin/rc/' | head -1 | sed ' s/.*origin\///' )
263+ if [ -z " $RC_BRANCH " ]; then
264+ echo " ❌ No rc/ branch found - cannot create PR"
265+ exit 1
266+ fi
267+
268+ # Create PR with detected rc/ branch
229269gh pr create \
230270 --title " feat(day-diet): add copy previous day functionality" \
231271 --body-file /tmp/pr-description.md \
232272 --label feature,ui,complexity-medium \
233273 --milestone " v0.14.0" \
234- --base rc/v0.14.0
274+ --base " $RC_BRANCH "
275+
276+ # Clean up
277+ rm /tmp/pr-description.md
235278```
236279
237280## Error Recovery
238281
282+ ### CRITICAL ERRORS TO AVOID
283+
284+ ** 🚨 NEVER USE STABLE BRANCH:**
285+ - ** Problem:** Creating PR to ` stable ` instead of ` rc/ ` branch
286+ - ** Fix:** Always detect and use ` rc/ ` branch as base
287+ - ** Rule:** PRs to ` stable ` are ONLY for version release merges
288+
289+ ** 🚨 EOF APPEARING IN PR DESCRIPTION:**
290+ - ** Problem:** Using ` cat <<EOF ` without quotes causes shell expansion
291+ - ** Fix:** Always use ` cat << 'EOF' ` with single quotes
292+ - ** Result:** Prevents literal "EOF" text in PR descriptions
293+
239294### Common Issues
240- - ** No rc/ branch:** Prompts user for correct base branch
295+ - ** No rc/ branch:** STOP execution and prompt user - never fallback to stable
241296- ** Unpushed commits:** Automatically pushes before PR creation
242- - ** Formatting issues:** Retries with corrected heredoc formatting
297+ - ** Formatting issues:** Use proper heredoc with single quotes around EOF
243298- ** Label conflicts:** Removes invalid labels and continues
244299
245300### Graceful Failures
0 commit comments