docs: add preflight template, shell join guide, and --resume gotcha#17
Merged
khaliqgant merged 1 commit intomainfrom Apr 23, 2026
Merged
docs: add preflight template, shell join guide, and --resume gotcha#17khaliqgant merged 1 commit intomainfrom
khaliqgant merged 1 commit intomainfrom
Conversation
Three new subsections in the Failure Prevention area, all distilled from
debugging sessions where each papercut cost 20+ minutes of retries:
- 2b. Standard preflight template — the allow-list pattern for files the
workflow owns (package-lock.json plus every file the edit steps will
rewrite), with full-line grep matching, |+ true against set -e, and the
quoted-dot escaping gotcha. Prevents the "preflight fails on my own
dirty file" loop.
- 2c. Picking the right .join() for multi-line shell commands — when to
use .join(' && ') vs .join('\\n'), why heredocs cannot be joined with
'&&' (results in shell syntax errors), and the printf + mktemp pattern
that sidesteps the entire class of nested-heredoc bugs for commit
messages and PR bodies.
- 7a. --resume vs --start-from when fixing a buggy step — counterintuitive
but critical: --resume replays the config stored in the run's DB record
and IGNORES file edits. --start-from reads the fresh file. If you
edited the workflow to fix the failing step, always use --start-from,
never --resume.
Each subsection includes copy-pasteable templates, concrete failure
modes, and links to the surrounding guidance.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds three new subsections to the Failure Prevention area of the
writing-agent-relay-workflowsskill. All three are distilled from debugging sessions where each papercut cost 20+ minutes of retries and all three are currently unwritten anywhere.Sections added
2b. Standard preflight template for resumable workflows
The allow-list pattern for files the workflow owns (always including
package-lock.jsonplus every file the edit steps will rewrite), with:grep -vE "^(...)$"to avoid substring bleed across unrelated files|| trueon the grep to surviveset -ewhen the result is emptygh auth statuscheckPrevents the "preflight fails on my own dirty file" loop that happens on every resume after a partial run.
2c. Picking the right
.join()for multi-line shell commandsWhen to use
.join(' && ')vs.join('\\n'), and why heredocs and&&joining are fundamentally incompatible (results in shell syntax errors when the join inserts&&between heredoc body lines).Also covers the
printf + mktemppattern that sidesteps the entire class of nested-heredoc bugs for commit messages and PR bodies (git commit -F+gh pr create --body-fileinstead of-m "$(cat <<EOF ...)").7a.
--resumevs--start-fromwhen fixing a buggy stepCounterintuitive but critical:
--resumereplays the workflow config stored in the run's DB record. It IGNORES file edits. Useful for transient failures, broken for fixing bugs in step definitions.--start-from <step> --previous-run-id <id>reads the fresh workflow file. Use this after any edit to the workflow.Both flags share the same cache layer, so
--start-fromstill avoids re-running expensive upstream agent steps.Why this matters
Three separate sessions this week hit each of these papercuts at least once. The preflight one has hit four times. Each one is individually survivable but collectively they eat hours of retries. Documenting them in the skill means the next agent (or the next me) doesn't have to re-discover them from scratch.
Test plan
🤖 Generated with Claude Code