Skip to content

How to write a return spec

Method

Status: Locked. Version: 0.1 Date: 2026-08-11

A return specification is the contract between the supervisor and the platform. It is what the supervisor signs off, and it is what Return Studio is configured from. If a spec is right, configuring the template is transcription. If a spec is vague, the ambiguity surfaces six months later as a dispute with a firm.

Rules

  1. Every field has an identifier. Use the requirement's convention: Rnn-Fnn for common fields and Rnn-Xnn for return-specific figures. Identifiers are permanent — a field's meaning may never be reused under the same id in a later version.
  2. Every field declares input or derived. If the platform can compute it, it is derived and the firm cannot enter it. State the formula.
  3. Every rule cites its authority. A directive, statutory instrument, or template policy. "Business rule" is not a citation. A rule without one cannot be written.
  4. Every rule has a severity. FAIL blocks acceptance, ADVISORY flags without blocking, INFO records context. Choose deliberately — over-using FAIL trains reviewers to override.
  5. State the checklist and the outcome set. Both are per template, both are configuration.
  6. Include worked examples. At least one passing case and one failing case with real figures. These become the test fixtures for the DMN decision tables.
  7. Name what is unresolved. An open question in the spec is honest. A guess in the spec is a future defect.

Structure

Follow this skeleton so specs are diffable against one another.

# Rnn Return Name

<div class="kovent-eyebrow">Category</div>

> **Status:** Drafted | Specified
> **Template:** Rnn vN.N
> **Version:** 0.1
> **Date:** YYYY-MM-DD

## Attributes
Frequency, applicable entities, purpose, legal basis, late-filing treatment.

## Core fields
The common fields every return carries.

## Return-specific fields
Sections, each a table of id / label / type / mode / validation notes.

## Derived figures
Formulas, spelled out.

## Automated validations
Table of id / rule / severity / citation.

## Reviewer checklist
The five items and what each means for this return.

## Outcomes
The permitted outcome set.

## Worked examples
Passing and failing figures.

## Open questions

## Related

Field type vocabulary

Keep to this set. A new type is a platform change and needs a decision record.

Type Notes
CURRENCY Stored minor-unit-free as numeric. Currency is a template attribute, not per field.
RATIO Decimal, typically 2–3 places. State the floor or cap if one applies.
INTEGER Counts — breaches, exceptions, clients, accounts.
PERCENT Distinguish from RATIO; used where the directive expresses a percentage.
DATE Business dates. Never a timestamp.
TEXT Short free text. State a length limit.
NARRATIVE Long free text — management explanations.
BOOLEAN Declarations and confirmations.
ENUM State the permitted values and whether they come from a reference table.
FILE Attachment. State accepted formats and whether required.

Severity guidance

The distinction is the most common mistake in a first draft.

Situation Severity Why
Required field missing FAIL The return is incomplete
Required attachment missing FAIL The requirement says it prevents final submission
Ratio below a regulatory floor FAIL A breach of a directive
Negative capital surplus ADVISORY A deficit is a reportable fact; the template permits it so it can be declared
Variance above tolerance, explanation given ADVISORY The firm complied with the explanation requirement
Variance above tolerance, no explanation FAIL The explanation requirement was not met
Period does not overlap a prior accepted return INFO Context, confirming an integrity check ran

The pattern: fail the process failure, advise the substantive concern. A firm reporting a deficit honestly should not be blocked; a firm failing to explain a swing should be.

Citation format

Quote the instrument as the supervisor names it, then narrow to the control:

  • Directive on Capital Adequacy for Securities Market Intermediaries · early warning control
  • Directive on Prudential and AML-CFT Returns and Penalties for Non-Compliance
  • Securities and Exchange (Registration, Licensing and Corporate Governance) Rules
  • Variance tolerance · template version — for a platform policy rather than an instrument

Where the legal name is unconfirmed, mark it. The requirement itself notes that final legal names, due dates, penalties, and applicability need supervisor confirmation, and a spec must not launder that uncertainty into false precision.

Workshop inputs

A spec cannot be completed from the requirement alone. Before marking one ✅, confirm with the supervisor:

  • The legal name and instrument reference
  • The due date policy: notice days and calendar adjustment
  • Applicability by licence category, including exemptions
  • Thresholds and tolerances, with the instrument that sets each
  • Whether the return is audited, and if so what changes in the audited version
  • Late-filing treatment and penalty parameters
  • Which figures are computed and which are supplied