RFC-2026-04-29-001

Write-Heavy Development Workflow

A four-phase task lifecycle with branch protection, mandatory documentation, and advisory review councils. Designed for money-movement systems where mistakes have real consequences.

Lifecycle Phases

main

Protected Branches

100%

Review Required

1-2 days

Added Lead Time

The Core Compromise

This process will add 1-2 days to most tasks. That is an acceptable cost. It is preferable to ship two days late than to rush production and lose customer funds.

Effective Date: May 1, 2026 for backend engineering. No exceptions; the process is mandatory from that date.

Guiding Principles

Six principles that underpin every decision in this workflow

The Four-Phase Task Lifecycle

Every non-trivial task passes through up to four phases. Click each phase to learn more.

Non-Sequential

Phases are not strictly sequential. Work in later phases can surface gaps that send a task back to an earlier one.

Parallel Analysis

Impact assessments for frontend, mobile, and backend can run in parallel.

Four Phases Deep Dive

Detailed requirements for each phase of the task lifecycle

Purpose

Capture what needs to be done and why, with enough supporting evidence that any engineer could pick up the task without backchannel context.

Inputs may include:

•Product PRDs
•Bug reports, screen recordings, screenshots
•Slack threads, line items from sheets, rough sketches
•Call recordings and Gemini meeting summaries — if a call happened, the recording and summary are first-class TID artifacts

Output:

Task title and a one-line summary
Background and motivation
Goals and non-goals
Links or embedded copies of all supporting artifacts
Open questions

Review

At least one peer or unit lead reviews the TID for completeness before the task moves to Phase 2.

Branch Protection

The main branch will be protected on every service repository

GitHub Enterprise Upgrade

Nuvion will upgrade to the GitHub Enterprise team plan to enable advanced branch protection rules.

main

Protected Branch

Protection Gate

Pull Request Required

With TIP document attached

feature/splits

fix/validation

chore/deps

Required Protections

No direct pushes to main

All merges via Pull Request

PR must reference attached TIP document

At least one peer review required

Lead or stakeholder ratification required

Status checks (CI, tests, linters) must pass

Scope: Every service repository, including the SDK and shared core packages. Effective May 1, 2026.

SPECML & ASPECML

All schema and API definitions in TIPs use the SpecML toolchain

Why SpecML?

A single source of truth for data structures and API contracts that generates TypeScript types, JSDoc, OpenAPI specs, and Java models. This eliminates drift between docs, validators, and client code — the same drift that hides bugs in money-movement systems.

SPECML

Data models, request/response types, shared structures

.spec

ASPECML

API endpoints (method, path, headers, body, responses)

.spec

Transaction {
  id string<ulid>
  amount number<min:0>
  currency string(NGN|USD|EUR|GBP)
  status string(pending|processing|settled|failed)
  counterparties[] {
    accountId string<ulid>
    sharePercent number<min:0|max:100>
  }
  createdAt string<isISO>
}

Both files live alongside the TIP and are committed to the same PR.

The Fast Path

Discretionary lightweight flow for low-risk changes

Not every change needs the full lifecycle

Typo fixes, small bug patches, dependency bumps, and similar low-risk changes may take a fast path.

Eligibility Criteria

A change qualifies for the fast path if ALL of the following are true:

Single-file or single-module scope

No change to API contracts (no new fields, no removed fields, no changed types)

No change to database schema or migrations

No new external dependencies (npm packages, services, env vars)

No change to authentication, authorisation, signing, or other security-sensitive surfaces

No change to money-handling logic (amounts, fees, splits, settlement, ledger writes)

New Change

All 6 criteria met?

Yes

Fast Path

Full Flow

Even on the fast path:

A short TIP-style note (title, what is being fixed, test plan)

Peer review and lead ratification still required

PR description must state why this qualifies for the fast path

Default to Full Flow

Leads may grant or revoke fast-path eligibility based on judgement. If there is any doubt, the change defaults to the full flow.

The RFC Repository

A new repository to host all RFCs, organised by date

Why date-based organisation?

RFCs are organised by date, not category. This mirrors traditional standards bodies and avoids the bikeshedding that comes with category taxonomies. Numeric months ensure file browsers and CLI tools sort folders chronologically.

Folder Structure

RFC-2026-04-29-001-development-workflow.md

RFC-2026-05-03-001-specml-toolchain.md

Naming Convention

RFC-YYYY-MM-DD-NNN-short-slug.md

Where NNN is a per-day sequence number starting at 001

What goes in an RFC?

An RFC is a Request for Comments. It documents a proposal — not a final decision. The expectation is that reviewers will leave comments, the document will be revised, and a decision will be recorded explicitly.

RFCs are living documents until they reach a Status: Accepted or Status: Rejected state.

TIDs and TIPs may also be published as RFCs when the change warrants broader visibility.

Rollout Plan

Backend-first rollout from May 1 to July 31, 2026

Phase 1: Backend

May 1 - July 31, 2026

The backend is the last line of defence; it is where this discipline matters most.

Phase 2: Frontend

August 2026+

Lessons from backend rollout inform frontend adoption.

Phase 3: Mobile

TBD

Mobile teams adopt the refined process.

Lessons Feed Forward

Whatever we learn in the backend rollout — friction points, useful shortcuts, template improvements — will inform how the frontend and mobile teams adopt the process from August onwards.

Acknowledged Trade-offs

Speed

Most tasks will take one to two days longer. This is the explicit compromise.

Process Overhead

Engineers will spend more time writing documents. The expectation is that this time is recovered later in fewer incidents and faster onboarding.

Review Load on Leads

Leads will be the bottleneck for ratification. We should monitor this and consider designating additional ratifiers if review queues grow.

Open Questions

These questions are intentionally left open for review comments:

1.Where do TIDs, TIAs, and TIPs physically live — in the RFC repository, in the service repository, or in a separate documentation repository?
2.What is the SLA for peer reviews and lead ratifications? Without one, work will stall on review queues.
3.How do we handle tasks that span multiple services and therefore multiple TIPs?
4.What tooling do we want for tracking which TIPs have been completed, in flight, or stalled?
5.Should ARC decisions have an explicit time-boxed turnaround commitment?

Document Templates

Ready-to-use templates for each phase of the task lifecycle

# TID: <task title>

**Task ID:** <ticket / RFC reference>
**Owner:** <engineer>
**Created:** <date>
**Status:** Draft | Reviewed | Approved

## Summary
One paragraph: what is this task and why does it exist?

## Background and motivation
Where did this come from? What problem does it solve?

## Goals
- ...

## Non-goals
- ...

## Supporting artifacts
- [PRD link]
- [Slack thread]
- [Call recording + Gemini summary]
- [Bug reports / screenshots]

## Open questions
- ...

## Reviewers
- [ ] Peer: <name>
- [ ] Lead: <name>

Dev Workflow