Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Authoring Acceptance Probe?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/acendas-authoring-acceptance-probe)
---
name: authoring-acceptance-probe
description: Author a runnable acceptance probe from criteria.
disable-model-invocation: true
---
# Authoring an Acceptance Probe
**Render before asking.** Render the decision context as chat text before any AskUserQuestion (rules printed at startup under SHIPYARD_STARTUP_RULES).
A probe is the smoke-test contract that proves wiring works end-to-end. Without one, a task cannot be dispatched in 2.0 — `dispatching-task-loop` refuses to run a task whose `acceptance_probe:` is missing or empty. So **authoring the probe is part of authoring the task**, not an optional polish step.
A task too speculative for a probe is not ready for execution: refine it, or mark it `kind: research` (no probe needed; deliverable is a findings doc).
## The Authoring Question
Ask exactly this:
> **"What single shell command, run from a clean state against the merged change, would print observable evidence that the wiring works?"**
If you cannot answer that question in one sentence, the acceptance criteria are too vague. Refine the criteria first, then return.
## Source Material
A probe is *derived* from:
1. **Acceptance criteria** in the step file's `## Acceptance Criteria` section. Each AC describes an observable outcome; the probe demonstrates at least one of them happens.
2. **Technical Notes** in the parent story file. These often spell out the exact endpoints, function signatures, table columns, or CLI flags involved.
3. **`config.md` test commands** — for the scoped test pattern that proves a unit slice ran. Useful only when paired with a wiring check, not as a probe by itself.
## Probe Patterns by Task Shape
### HTTP / REST endpoint
```
curl -fsS -X POST http://localhost:3000/api/users \
-H "Content-Type: application/json" \
-d '{"name":"probe","email":"p@p.io"}' | jq -e '.id and .name == "probe"'
```
Exit 0 only when the response has `id` and `name == "probe"`. `-f` makes curl exit non-zero on HTTP error. `-S` shows errors. `jq -e` exits non-zero on false.
### CLI subcommand
```
node bin/mytool.mjs new-subcommand --help | grep -q "synopsis line text"
# OR, if it does work:
node bin/mytool.mjs new-subcommand --dry-run input.txt | grep -q "expected output marker"
```
### Library / module export
```
node -e 'const m = require("./dist/index.js"); if (typeof m.newFn !== "function") process.exit(1); const r = m.newFn(42); if (r !== 84) process.exit(1); console.log("OK:", r);'
```
### Database migration
```
psql "$DATABASE_URL" -c "SELECT 1 FROM information_schema.columns WHERE table_name='users' AND column_name='new_col'" | grep -q '1 row'
```
### Refactor with no behavior change
The probe is the test suite scoped to the touched module:
```
npm run build && npm test -- --testPathPattern='module-touched'
```
This is the one case where the probe and a test command overlap legitimately — a refactor's contract IS that tests still pass.
### Frontend route or component
A Playwright check is ideal:
```
npx playwright test e2e/new-feature.spec.ts --reporter=line
```
If Playwright isn't set up yet:
```
curl -fsS http://localhost:3000/the-new-page | grep -qE 'data-testid="new-feature"|<NewFeature'
```
### Background job / scheduled task
Probe by triggering it manually and observing its output:
```
node bin/run-job.mjs new-job-name --once 2>&1 | grep -q "job completed: new-job-name"
```
### Configuration change
Read it back:
```
node -e 'const c = require("./config/loaded.json"); if (c.newKey !== "expected") process.exit(1)'
```
## Anti-Patterns to Reject
| Don't write | Why |
|---|---|
| `npm test` (the full suite) | A test suite is not a probe — it doesn't prove THIS task's wiring; it could pass against a stub the task didn't fix. |
| `echo "done"` | No observable evidence; it can't fail. |
| `cat fixtures/expected.json` | Reads a file the task didn't write; doesn't exercise new code. |
| `node -e '"use strict"; console.log("ok")'` | Doesn't import or call any of the task's code. |
| Multi-line scripts requiring setup state | Probes must be self-contained. If setup is needed, fold it into the probe with `&&` or refactor the task. |
| Interactive prompts | Probes must run unattended. |
| Curl against an external service | Non-deterministic and not under the change's control. Use a local mock or skip. |
| Anything that takes >5 minutes | Probe is too broad. Split the task or narrow the probe. |
| `! command_that_fails_today` | "Negative" probes that pass *because* something is broken are ambiguous after a fix lands. |
## Verification Type Routing
E2E acceptance criteria have a `verification_type` field that determines how they are verified. The authoring approach differs per type:
### verification_type: "probe" (default)
Standard probe authoring — same as all patterns above. The probe is a shell command that exits 0 on pass. This covers all core AC and most E2E AC.
### verification_type: "tool"
The AC requires a specific testing tool for verification (e.g., Playwright for visual checks, k6 for load testing, lighthouse for accessibility). The probe is still a shell command, but it invokes a specialized tool binary. Author the probe normally, but note the tool dependency in the step file:
```yaml
acceptance_probe: |
npx playwright test e2e/timeout-handling.spec.ts --reporter=line
verification_tool: playwright
```
The `verification_tool` field is informational — it tells the reviewer what tooling is needed. The probe itself must still be self-contained and exit 0 on pass.
### verification_type: "manual"
The AC requires human judgment and cannot be meaningfully automated (e.g., "degraded mode messaging is user-friendly", "admin dashboard layout is intuitive"). This is valid for feature-level `user_flow_probe.kind: manual`, but a `kind: feature` task still needs an executable `acceptance_probe:` before `dispatching-task-loop` can run it.
For task decomposition, route manual-only criteria explicitly:
- If the task also changes executable behavior, author a narrow machine probe for the behavior and add the human judgment as a `## Manual Verification` checklist in Technical Notes.
- If the task is purely subjective/manual, do **not** make it `kind: feature`; make it `kind: operational` with a `verify_command` that prepares or opens the verification surface, then carry the checklist into `/ship-review` quality gates.
- If neither path is clear, refine or split the task before approval.
Checklist format:
```markdown
## Manual Verification
- [ ] [What to observe — concrete, specific]
- [ ] [Expected behavior — what "correct" looks like]
- [ ] [How to trigger the scenario]
```
Manual verification items are presented as a checklist during `/ship-review` Stage 5. The reviewer must confirm each item before the sprint can be approved. They do not satisfy the `acceptance_probe:` requirement for `kind: feature` tasks.
**When to convert manual to probe:** If you can describe the check as "run X, expect Y", it's a probe — even if it requires a browser automation tool. Reserve `manual` for genuinely subjective checks: visual aesthetics, copy quality, workflow intuitiveness, accessibility judgment calls.
## Quality Checklist Before Saving
Before writing the probe to the step file, confirm:
- [ ] **One command.** Multi-step setup belongs in the task's prerequisites, not the probe. Allowed connectors: `&&` (sequential), `|` (pipe), `;` (only if every step is independently meaningful — rare).
- [ ] **Self-contained.** Could be run by anyone, in any clone, with the standard project setup, and produce the same exit code.
- [ ] **Exit 0 ↔ pass.** No "exit 0 means probably ok"; exit 0 means the AC is satisfied.
- [ ] **Observable output.** When passing, the probe prints something that demonstrates the wiring (a value, a row count, a matched text). Bare exit-0 with empty output is suspicious.
- [ ] **Deterministic.** Run twice without changes → same exit code. Network calls to external APIs, time-based checks, or randomized inputs are red flags.
- [ ] **Bounded.** Default budget is 60s; hard cap 5m. A probe that needs >60s is testing too much — narrow it.
- [ ] **Doesn't pass today.** Run the probe on the current working branch *before* implementation. It should FAIL — if it passes pre-implementation, the probe isn't testing the change. (This is the probe-equivalent of TDD's "watch it fail" rule.)
## Where the Probe Lands
In the step file's frontmatter:
```yaml
---
id: P042
title: Add user creation endpoint
kind: feature
feature: S007
status: approved
effort: M
acceptance_probe: |
curl -fsS -X POST http://localhost:3000/api/users \
-H "Content-Type: application/json" \
-d '{"name":"probe","email":"p@p.io"}' | jq -e '.id and .name == "probe"'
---
```
Use a YAML block scalar (`|`) when the probe is multi-line or contains characters that would need escaping. Otherwise inline:
```yaml
acceptance_probe: 'node -e ''require("./dist").newFn(42) === 84 || process.exit(1)'''
```
## When Probe Authoring is Hard
Hard cases: async features (bounded retry loop: `for i in {1..10}; do <check> && exit 0 || sleep 1; done; exit 1`), log-only observability (grep the log), UI-only change (Playwright or `curl` + grep a unique marker), internal refactor (scoped test suite), config-only change (read it back via the loader).
Before asking, render as chat text: the task's acceptance criteria, one plain line each, and which of the patterns above were attempted and why each failed — the user cannot choose between refine/split/research without seeing the criteria. Criteria sitting in a Read result do not count as shown. Then surface to the user via AskUserQuestion: *"This task's acceptance criteria don't reduce to a single observable command. Should we (a) refine the criteria, (b) split into smaller tasks, or (c) mark this task `kind: research` and produce a findings doc instead?"* Recommend (a) by default.
## Pairing With Other Skills
- **`running-acceptance-probe`** runs what this skill writes. The contracts must align: the probe shape this skill produces is exactly what that skill expects.
- **`anti-stub-scan`** flags stub-shaped probes (`echo done`); a probe that does not exercise the added code is itself a stub.
- **`dispatching-task-loop`** consumes the `acceptance_probe:` field at dispatch time. A missing or empty probe blocks dispatch — author one or mark `kind: research`.
- **`/ship-review`** re-runs probes during review; flaky probes surface here and cycle back to this skill for re-authoring.