Appropriate use
Use for shift changes, leave, cross-team ownership, incident handoff, long-running tests, blocked work, or platform-specialist continuation.
Scope and intent
A controlled workflow specification
This page defines the behaviour, controls, evidence, and outputs required from the skill. It does not claim that a language model can enforce security or correctness by wording alone.
Non-goals
Do not use to replace source artifacts, transfer secrets, or state that work is complete when required scope remains.
- 8
- versioned workflow phases
- 3
- explicit approval gates
- 5
- defined result states
- 9
- versioned output artifacts
Material changes to the source, environment, identity, approved actions, or expected behaviour invalidate dependent approvals and require revalidation.
Workflow
The 8 phases
Each phase has explicit inputs and outputs. Approval gates are hard stops bound to exact versions and hashes.
Phase 1: Handoff boundary preflight Gate 1 · approve audience
Confirm receiving person or team, timezone, urgency, access level, products, environments, and whether restricted evidence requires a separate channel.
sender · receiver · window · audience · access
Phase 2: Current-state snapshot
Capture ticket, plan, build, environment, role, data, test state, device, logs, and current application state at the handoff time.
exact state · timestamp · version · resource IDs
Phase 3: Completed-work extraction
List executed scenarios, outcomes, evidence, defects, decisions, and cleanup already performed. Link sources rather than duplicating large reports.
done · result · evidence · confidence
Phase 4: Remaining-work extraction
List untested and blocked scenarios, priority, prerequisites, expected evidence, stop conditions, and why each remains.
next scenario · priority · dependency · owner
Phase 5: Known traps and recovery
Document fragile setup, expiring sessions, device quirks, temporary configurations, long-running timers, retry restrictions, and how to restore state safely.
trap · symptom · safe recovery · prohibited action
Phase 6: Next-action recipe
Provide the exact first action, command or navigation, expected starting state, success signal, and escalation path.
first step · expected state · owner · escalation
Phase 7: Receiver review Gate 2 · accept handoff
Review whether the receiver has access, understands the state, and can continue without guessing. Resolve ambiguities before transfer.
access confirmed · questions · accepted responsibility
Phase 8: Publish and ownership transfer Gate 3 · transfer
Publish the handoff, record acceptance, preserve the source snapshot, and update ownership in the relevant system where authorised.
handoff ID · accepted at · owner · expiry
Approval contract
Every gate approves an exact decision object
An approval cannot be reused after its environment, source, action plan, or approved document changes.
| Gate | Decision | Required binding |
|---|---|---|
| 1 | Gate 1 · approve audience | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 2 | Gate 2 · accept handoff | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
| 3 | Gate 3 · transfer | Approval stores approver, role, timestamp, context hash, approved document hash, expiry, and invalidation state. |
Result model
Defined states prevent vague conclusions
Attempt outcomes remain separate from these workflow results. Errors, cancellations, and invalid context are never silently converted into a pass.
READY
The receiver has enough verified context and access to continue safely.
READY WITH RISKS
Continuation is possible with explicit uncertainty or fragile state.
BLOCKED
Missing access, build, device, data, or decision prevents continuation.
STALE
The environment or source state changed after the handoff was prepared.
CANCELLED
The work no longer needs transfer and the reason is recorded.
Evidence contract
Evidence must directly support the claim
Evidence has provenance, capture context, privacy classification, retention, and integrity metadata. A convenient artifact is not automatically sufficient proof.
| Claim | Primary evidence | Required validation |
|---|---|---|
| Current state | Timestamped context snapshot | Build, environment, role, data, and device are exact. |
| Completed work | Source execution records | Results and uncertainty are preserved. |
| Remaining work | Approved plan references | Priority and prerequisite are clear. |
| Evidence | Accessible links or bundle references | Receiver permissions match evidence sensitivity. |
| Temporary state | Configuration and resource ledger | The receiver knows what must not be reset or deleted. |
| Acceptance | Receiver acknowledgement | Questions and ownership transfer are recorded. |
Trust and safety
Controls that must be enforced outside the prompt
These controls belong in the runtime, connector permissions, sandbox, renderer, storage layer, and review process.
Runtime control
No secret transfer
Credentials are provided through approved access systems, never the handoff text.
Runtime control
State freshness
A changed build, environment, or ticket invalidates or updates the handoff.
Runtime control
No hidden incompleteness
Not-tested and blocked work is as visible as completed work.
Runtime control
Restricted channels
Security, customer, and incident evidence uses appropriate access.
Runtime control
First-action clarity
The receiver should not need to infer where to start.
Runtime control
Ownership confirmation
Sending a document is not the same as accepted transfer.
Decision policy
Ordered outcomes, not averaged pass counts
The first applicable high-severity outcome takes precedence. A manual override is recorded separately and never rewrites the calculated result.
STALE
Refresh the handoff because the source state changed.
BLOCKED
Resolve access or prerequisite gaps before transfer.
READY WITH RISKS
Transfer with explicit uncertainty and recovery guidance.
READY
Transfer ownership with a verified continuation path.
Known limitations
Uncertainty and coverage limits remain visible
The workflow documents what it cannot prove and what further evidence would change confidence.
- Limit 1. A handoff can become stale quickly in active releases or incidents.
- Limit 2. Some physical device state cannot be captured fully in text.
- Limit 3. Receiver availability and access may change after acceptance.
- Limit 4. Long-running observations need explicit clocks and ownership.
- Limit 5. Large evidence bundles may require separate restricted storage.
- Limit 6. The handoff should remain short enough to use while linking deeper sources.
Outputs
Versioned records for review and continuation
Human summaries are generated from validated structured records. They are not maintained as separate, drifting sources of truth.
handoff-context.jsonVersioned output produced by the workflow.
state-snapshot.jsonVersioned output produced by the workflow.
completed-work.mdVersioned output produced by the workflow.
remaining-work.mdVersioned output produced by the workflow.
known-traps.mdVersioned output produced by the workflow.
next-action.mdVersioned output produced by the workflow.
access-check.mdVersioned output produced by the workflow.
acceptance.jsonVersioned output produced by the workflow.
handoff.htmlVersioned output produced by the workflow.
artifacts/qa/qa-handoff/<run-id>/ ├── handoff-context.json ├── state-snapshot.json ├── completed-work.md ├── remaining-work.md ├── known-traps.md ├── next-action.md ├── access-check.md ├── acceptance.json └── handoff.html
Example
Example request and controlled output
Input
Prepare a handoff for the tester continuing SCOS 3.1.14 tomorrow. Include completed OTA paths, missing assets, device state, exact next step, and what not to reset.
Output excerpt
Handoff status: READY WITH RISKS Current state: Two SCOS devices remain paired to the staging organisation and are on the current 3.1.14 candidate. Completed: - OTA update - Reboot - Wi-Fi to Ethernet switch - Cached playback Blocked: SD flasher validation because the release image is missing. First action: Confirm the published artifact hash, then execute scenario SCOS-OTA-07. Do not: Clear cache, reset pairing, or overwrite the current SD card before preserving the existing logs.
Production readiness
Required before operational use
The written skill is only one layer. The repository, runtime, connectors, evidence storage, and publication path must implement these requirements.
- Required. Tool, filesystem, repository, command, secret, and network permissions are enforced outside the model.
- Required. Every source, environment, build, plan, and approval has a version or content hash.
- Required. Untrusted values are escaped, length-bounded, path-safe, and separated from executable instructions.
- Required. Attempt outcomes, scenario verdicts, workflow decisions, and publication status remain separate.
- Required. Raw evidence, publishable evidence, access control, retention, redaction, and deletion are defined.
- Required. Concurrent runs use unique IDs, locks, idempotency keys, and conflict-aware updates.
- Required. Material changes invalidate dependent approvals and outcomes.
- Required. The repository validator passes before the skill is considered production-ready.
In one line
/qa-handoff
Creates a precise handoff so another tester or team can continue from the correct build, state, evidence, and next action without repeating work or losing uncertainty.