Skip to content

Commit 393ac6b

Browse files
doquanghuyclaude
andcommitted
docs(workflows): clarify on_reject:skip semantics — engine returns COMPLETED, not auto-skip
Copilot finding on b8982a7: The README example's gate message said "reject to skip the rest of this branch", and the explanatory paragraph claimed [approve, reject] map to "continue" vs "skip the rest of this branch". The engine does not implement automatic branch-skipping. `on_reject: skip` returns `StepStatus.COMPLETED` (gate/__init__.py:65-66); the next sibling step runs unconditionally unless the author wires a downstream `if` reading `{{ steps.<gate-id>.output.choice }}`. Two fixes: 1. Restructured the YAML example so it actually demonstrates the manual-branching pattern: added a `recover` if-step after the gate that conditions on `steps.review.output.choice == 'approve'`. Now the example shows the real workflow author's responsibility instead of implying the engine does it. 2. Replaced the trailing paragraph with three precise notes: - both gate options return COMPLETED; `on_reject: skip` controls abort behaviour only, not sibling-skipping - all three `on_reject` values enumerated with their actual engine semantics (FAILED+aborted / COMPLETED / PAUSED) - the original retry-loop guidance retained as the third bullet Updated the gate message in the example to match — "reject to leave the failure recorded and move on" instead of "reject to skip the rest of this branch". Audited the whole PR diff for the same overclaim: no other instance. Engine semantics, validation, and test bodies are unchanged. Docs-only. 161/161 tests/test_workflows.py pass locally. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
1 parent b8982a7 commit 393ac6b

1 file changed

Lines changed: 24 additions & 6 deletions

File tree

‎workflows/README.md‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -242,18 +242,36 @@ remains available on `steps.<id>.output.exit_code` so downstream
242242
then:
243243
- id: review
244244
type: gate
245-
message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Approve to continue, or reject to skip the rest of this branch."
245+
message: "Step failed (exit {{ steps.heavy-thing.output.exit_code }}). Approve to run the recovery path, or reject to leave the failure recorded and move on."
246246
on_reject: skip
247+
- id: recover
248+
type: if
249+
condition: "{{ steps.review.output.choice == 'approve' }}"
250+
then:
251+
- id: rerun
252+
command: speckit.recovery
247253
else:
248254
- id: next-thing
249255
command: speckit.next-thing
250256
```
251257

252-
The gate's default `options: [approve, reject]` map directly to "continue
253-
the run" vs. "skip the rest of this branch" — gates do not automatically
254-
re-run the failed step. To express a retry path, either define custom
255-
gate options and branch on the choice downstream, or wrap the failing
256-
step in your own loop.
258+
A few things worth knowing about that example:
259+
260+
- Both gate options (`approve`, `reject`) return `StepStatus.COMPLETED`;
261+
`on_reject: skip` controls only whether the engine aborts on reject
262+
(it doesn't, with `skip`) — it does **not** auto-skip subsequent
263+
sibling steps in the `then:` list. Downstream branching is the
264+
workflow author's responsibility: read
265+
`{{ steps.<gate-id>.output.choice }}` in a follow-up `if`, `switch`,
266+
or expression, as the `recover` step above does.
267+
- `on_reject` has three values: `abort` (default — reject → `FAILED`
268+
with `output.aborted = True`, halts the run), `skip` (reject →
269+
`COMPLETED`, author handles branching as shown), and `retry`
270+
(reject → `PAUSED` so the next `specify workflow resume` re-runs
271+
the gate).
272+
- Gates do not automatically re-run the failed step. To express a
273+
retry path, either define custom gate options and branch on the
274+
choice downstream, or wrap the failing step in your own loop.
257275

258276
**Notes:**
259277

0 commit comments

Comments
 (0)