# Robot capability specification

**Template version:** 0.1
**Published:** 14 November 2026
**Maintainer:** Embodied Software Labs (Synthari AI LLC)
**Licence:** CC BY 4.0 — use it, change it, publish your filled-in version, no attribution to us required in the filled-in copy itself.

---

## What this is, and what it is not

This is **a proposal for how to describe one robot capability** so that the person
packaging it and the person deploying it are talking about the same thing.

It is **not** an industry standard. It is not published by a standards body, it has
not been adopted by anyone, and filling it in does not certify, approve or qualify
anything. If a supplier hands you one of these completed, it is a claim they have
made, not a test anyone has witnessed.

It is also **not a safety assessment**. Nothing in section 4 substitutes for a risk
assessment carried out by a competent assessor for your specific installation.

Use it as a checklist for the questions that otherwise get discovered late.

---

## How to use it

1. Copy everything below the line into a new file, one file per capability.
2. Fill every field. `Not applicable` and `Not tested` are both valid answers.
   A blank field is not — a blank means nobody has thought about it yet, and
   that is exactly the information this document exists to surface.
3. Version it alongside the code it describes. A specification that drifts from
   its implementation is worse than none, because people trust it.
4. Anything you cannot evidence, mark `Declared, not tested`. That phrase is the
   most useful one in the whole template.

---
---

# CAPABILITY SPECIFICATION

| | |
|---|---|
| **Capability name** | |
| **Capability ID** | |
| **Specification version** | |
| **Status** | Draft / Declared / Tested / Deployed / Withdrawn |
| **Date** | |
| **Spec owner** | |
| **Implementation repository** | |
| **Implementation version or commit** | |

---

## 1. The task and the intended users

**1.1 What this capability does, in one sentence.**
> Write it as an action on an object in a place. If the sentence needs an "and",
> consider whether this is two capabilities.

**1.2 Who is expected to invoke it.**
> A supervising operator? A task scheduler? Another capability? Name the caller,
> because the error handling in section 3.4 depends on who is listening.

**1.3 Who is expected to be nearby while it runs.**
> Nobody / trained operator / untrained personnel / public. This single answer
> changes the entire safety picture and belongs at the top, not buried.

**1.4 What this capability explicitly does not do.**
> The most-read field in the document. List the adjacent things a reader might
> reasonably assume are included and are not.

**1.5 What problem it replaces or augments.**
> The manual process today, or the capability it supersedes.

---

## 2. Robot, sensor and software dependencies

**2.1 Robot platforms this has run on.**

| Platform | Make and model | Firmware / controller version | Status |
|---|---|---|---|
| | | | Tested / Declared, not tested / Known incompatible |

> One row per platform. `Declared, not tested` means the supplier believes it
> works. It is not evidence and must never be presented as evidence.

**2.2 Minimum robot characteristics.**

| Characteristic | Requirement | Why |
|---|---|---|
| Degrees of freedom | | |
| Reach | | |
| Payload at full extension (including the end effector) | | |
| Repeatability | | |
| Mounting | | |

> Payload at full extension, not the headline figure, and with the tool fitted.

**2.3 End effector.**
> Type, make and model, and whether the capability assumes a specific one or a
> class. If grasp planning assumes two opposing surfaces, say so here.

**2.4 Required sensing.**

| Sensor | Purpose | Minimum spec | Frame | Rate | Required? |
|---|---|---|---|---|---|
| | | | | | Required / Optional / Degraded mode |

**2.5 Compute.**
> Target device, sustained rather than peak requirement, memory ceiling, and
> whether it was measured in an enclosure at operating temperature or on a bench.

**2.6 Software dependencies.**

| Dependency | Version tested | Licence | Notes |
|---|---|---|---|
| | | | |

> Pin versions. "ROS 2" is not a version. Record the distribution and the
> package version actually used in the test in section 5.

**2.7 Calibration this capability assumes is already correct.**
> Hand-eye, tool centre point, camera intrinsics, frame tree. Name who is
> responsible for each and how the capability behaves when one has drifted.

---

## 3. Interface

> Terminology below follows ROS 2 interface conventions — topics, services and
> actions — because it is the most widely understood vocabulary, not because
> this template requires ROS. Substitute your own if you use something else.

**3.1 Inputs.**

| Name | Kind | Type | Units | Frame | Rate or trigger | Required? |
|---|---|---|---|---|---|---|
| | Topic / Service / Action / Parameter | | | | | |

**3.2 Outputs.**

| Name | Kind | Type | Units | Frame | Rate | Meaning |
|---|---|---|---|---|---|---|
| | | | | | | |

**3.3 Nominal timing.**

| Phase | Nominal | Worst observed | Measured on |
|---|---|---|---|
| Time to accept a request | | | |
| Time to first motion | | | |
| Time to completion | | | |
| Time to stop on command | | | |

> Worst observed, not average. The average is what it does; the worst is what
> you have to design the surrounding system around.

**3.4 Result and error states.**

| State | Meaning | What the caller should do |
|---|---|---|
| Success | | |
| Failed — recoverable | | |
| Failed — needs a human | | |
| Refused — precondition not met | | |
| Aborted — commanded to stop | | |
| Timed out | | |

> Every state a caller can observe must appear here. A state that exists in the
> code and not in this table is how integrations break in month three.

**3.5 What the caller must guarantee before invoking.**
> Preconditions: gripper empty, workspace clear, robot homed, a valid frame
> transform available. State what happens if each is false.

---

## 4. Operating limits and refusal behaviour

> This section is about the boundary of competence. It is **not** a safety
> assessment and does not establish that any configuration is safe.

**4.1 The envelope this was built for.**

| Dimension | Range it handles | Outside that range it will |
|---|---|---|
| Object mass | | Refuse / Degrade / Untested |
| Object dimensions | | |
| Object surface | | |
| Presentation or pose variation | | |
| Lighting | | |
| Temperature and humidity | | |
| Surrounding clutter | | |
| Floor or mounting condition | | |

**4.2 Conditions under which it refuses to act.**
> List them. A capability that never refuses has not been thought about.

**4.3 What it does when it refuses.**
> Stops where it is? Returns to a named pose? Releases or retains the payload?
> Who is told, and how?

**4.4 Behaviour on loss of a dependency.**
> Separately for: a sensor stops publishing, the network drops, the caller
> disappears, compute is saturated, power is interrupted mid-motion.

**4.5 Things this capability must never be allowed to do.**
> Written as constraints for the integrator to enforce outside this software.

**4.6 Safety note.**
> Required text, do not delete: *this specification is not a risk assessment and
> not a compliance document. The operator of the installation is responsible for
> assessing the application, and that assessment governs regardless of anything
> recorded here.*

---

## 5. Test evidence

**5.1 Tested configuration.**
> The exact robot, end effector, sensors, software versions, site and date.
> If this does not match section 2, say which row differs.

**5.2 What was measured.**

| Metric | Definition used | Value | Trials | Date |
|---|---|---|---|---|
| Task completion | completed ÷ attempted | | | |
| Human interventions | interventions ÷ 100 attempts | | | |
| Mean time to recover | | | | |
| Sustained rate | over what period | | | |

> Record the definition you used, not just the number. "Success rate" means
> nothing without knowing what counted as a success and who decided.

**5.3 How an intervention was counted.**
> An intervention is not necessarily a failed task, and a failed task is not
> necessarily an intervention. Define both.

**5.4 Conditions excluded from the test, and why.**

**5.5 Known failure modes observed during testing.**

| What happened | How often | Detected automatically? | Mitigation |
|---|---|---|---|

**5.6 Evidence links.**
> Logs, recordings, test reports, dates. A specification with no link in this
> field is a declaration, and section 2.1 should say `Declared, not tested`.

**5.7 What was not tested at all.**
> The honest answer is usually long. Write it anyway.

---

## 6. Ownership, maintenance and escalation

**6.1 Who maintains the implementation.**

**6.2 Who to contact when it misbehaves, and what response is actually committed.**
> Distinguish best effort, a response target and a contracted commitment.
> If nothing is committed, write "no commitment".

**6.3 Dependency and security update ownership.**
> Who watches the upstream dependencies in 2.6, and on what cadence.

**6.4 What happens when the robot, firmware or site configuration changes.**
> Who re-tests, and does the specification's status in the header drop back to
> `Declared` until they have?

**6.5 Licence and rights.**

| | |
|---|---|
| Licence covering the implementation | |
| Licence covering any model weights | |
| Licence covering configuration and tuning data | |
| Who owns data produced during operation | |
| Who owns improvements made by the deployer | |

**6.6 End of support and migration.**

**6.7 Review.**

| | |
|---|---|
| Specification last reviewed | |
| Reviewed by | |
| Next review due | |
| Changes since the previous version | |

---
---

# WORKED EXAMPLE — ENTIRELY HYPOTHETICAL

> **Read this first.** The capability below does not exist. It is not a product,
> it has never run on a robot, and every number in it was invented to show what a
> filled-in field looks like. It is included because an empty template teaches
> nothing about the level of detail that makes one useful.
>
> Do not cite these figures. They are illustrative arithmetic, not results.

| | |
|---|---|
| **Capability name** | Supervised tote transfer, bench to conveyor |
| **Capability ID** | `cap.tote-transfer.bench-to-conveyor` |
| **Specification version** | 0.3.0 — HYPOTHETICAL |
| **Status** | Tested (in this fictional example) |
| **Date** | 14 November 2026 |
| **Spec owner** | Example Integrator Ltd — not a real company |

**1.1** Lifts a single plastic tote from a fixed bench position and places it on a
moving conveyor, under the supervision of a trained operator.

**1.3** A trained operator is present throughout. This capability was not designed
for use near untrained personnel, and nothing about it has been assessed for that.

**1.4 Does not:** locate totes that are not at the bench position; handle stacked,
nested, lidded, wet, damaged or overfilled totes; open or close totes; read
labels; decide which tote to move; recover a dropped tote; or operate while the
conveyor is stopped.

**2.1**

| Platform | Make and model | Firmware | Status |
|---|---|---|---|
| Arm A | Example Arm 7-DOF, 12 kg class | 4.2.1 | Tested |
| Arm B | Example Arm 6-DOF, 10 kg class | 4.2.1 | Declared, not tested |

**2.2** Payload at full extension including a 1.4 kg vacuum array: **6.5 kg**.
A full tote in this example is 5.8 kg, leaving 0.7 kg of margin — which is why
4.1 refuses above 6.0 kg rather than at the arm's rating.

**3.3**

| Phase | Nominal | Worst observed | Measured on |
|---|---|---|---|
| Accept request | 40 ms | 180 ms | Arm A, 200 trials |
| First motion | 0.6 s | 1.9 s | Arm A, 200 trials |
| Completion | 11.4 s | 23.0 s | Arm A, 200 trials |
| Stop on command | 0.3 s | 0.5 s | Arm A, 40 trials |

**4.1 (extract)**

| Dimension | Range it handles | Outside that range it will |
|---|---|---|
| Object mass | 1.0 – 6.0 kg | Refuse before lifting |
| Object dimensions | 600 × 400 mm totes, 120 – 320 mm tall | Refuse |
| Object surface | Dry, clean, rigid plastic | Untested — may fail to seal |
| Presentation | ±15 mm, ±5° from the bench fixture | Refuse |
| Lighting | 200 – 1200 lux, no direct sun on the bench | Degrade: more retries |

**5.2**

| Metric | Definition used | Value | Trials | Date |
|---|---|---|---|---|
| Task completion | tote placed on conveyor, upright, within the lane ÷ attempts | 190 ÷ 200 = **95%** | 200 | 02 Nov 2026 |
| Interventions | operator touched the robot, the tote or the e-stop ÷ 100 attempts | 20 ÷ 200 = **10 per 100** | 200 | 02 Nov 2026 |

> Note what these two rows do **not** say together. Ten interventions per hundred
> and ninety-five per cent completion are not contradictory: some interventions
> rescued an attempt that then completed successfully, and some failures needed
> no intervention at all because the capability refused cleanly before moving.
> This is precisely why 5.3 exists. **No threshold here is universally
> acceptable** — whether 95% and 10 per 100 is good depends entirely on what the
> task costs when it goes wrong, and that is a judgement for the operator of the
> site, not for a specification.

**5.7 Not tested at all:** totes under 1.0 kg; any non-plastic container; operation
with the bench fixture removed; recovery from a tote dropped in transit;
continuous operation beyond 90 minutes; any temperature outside 15–26 °C;
any site other than the single fictional test bench.