Context-Heavy Development Workflow
A four-phase task lifecycle with branch protection, mandatory documentation, and advisory review councils. Every decision, constraint, and assumption is captured in a central, durable document — not in private DMs, calls, or memory.
4
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. May is a grace period for adoption; religious enforcement begins June 2026.
Guiding Principles
Seven 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. Phases are not strictly sequential — work in later phases can surface gaps that send a task back to an earlier one.
Phase Ownership
| Phase | Primary Owner | Engineer's Role |
|---|---|---|
| TID | Product (or task originator) — NOT the implementing engineer | Follow up to ensure the TID exists and is complete; do not start TIA until it does |
| TIA | The engineer, in consultation with leads from impacted areas | Author, in consultation with leads of impacted surfaces |
| ARC | Convening lead (typically unit lead) | Attendee; defends the design |
| TIP | The implementing engineer | Author |
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
Pull Request Required
With TIP document attached
Required Protections
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.
Data models, request/response types, shared structures
.specAPI endpoints (method, path, headers, body, responses)
.specTransaction {
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.
Task Tiers & Lightweight Flows
Not every change needs the full lifecycle. We classify tasks into three tiers, each with a different process expectation.
Tier Assignment Flow
Full Flow
TID + TIP
Lightweight
When in doubt, escalate one tier up.
Lightweight Flow (Tier 3 Only)
A change qualifies for the lightweight flow if ALL of the following are true:
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 Tier 3
Severe-Incident Bypass
Some incidents do not wait for process. Active money loss, vulnerabilities exposing customer funds, and ongoing security breaches may bypass the lifecycle entirely.
Eligibility (one of):
- •Active production incident causing measurable harm (money loss, data exposure, total service unavailability)
- •A vulnerability has been identified that places customer funds or sensitive data at imminent risk
Retroactive documentation (within 3 business days):
- •A TID describing the incident, the affected surfaces, and customer impact
- •A TIA capturing what the fix changed and any cross-team or shared-component effects
- •A TIP documenting the actual implementation, including observability changes
- •An incident postmortem reference
The 3-day deadline is a hard ceiling. "Retroactive without a deadline" tends to mean "never."
Definition of Done (CI Gate)
A PR is mergeable only when ALL of the following are satisfied
Pre-deploy gate (load testing)
For changes that triggered the load-testing requirement, load test must run and results attached to TIP as an addendum before production deploy. Merge can happen without results; production deploy cannot.
Product-Driven Mock Testing
Because we have reproducible mocks across our core packages, non-technical reviewers — typically product — can validate engineer work without writing code.
Example probe:
"What happens if the counterparty split values exceed the transaction amount?"
This is translated by an agent into a runnable mock test, and the result is reported back in human-readable form.
PRs that touch behaviour described in the TID should expect this kind of probing. Engineers should keep their mocks in a state that supports it.
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
Naming Convention
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.
Foundations We Are Building On
This RFC is viable because of work the team has already done
SpecML and ASPECML
Adopted across our codebases for over a year. Everyone is fluent. The community at large has begun adopting them too.
Reproducible Mocks
Exist for MongoDB, TigerBeetle, ClickHouse, Redis, the queue system, and the cache layer. Anyone can clone a service, install packages, and run business-logic tests with no infrastructure setup.
Standard Boilerplate
Across services means an engineer moving from the payouts codebase to the cards codebase finds a familiar layout, not a foreign one.
AI-Assisted Documentation
Voice notes in any language — English, pidgin, Yoruba, Igbo, Hausa — can be fed to an LLM and returned as a structured TID, TIA, or TIP draft. The bar is captured context, not technical writing skill.
The 2026 Advantage
We are starting a fintech in 2026. We have the benefit of a decade of public lessons from companies that learned these things the expensive way. That is an edge. We should use it.
Out of Scope (Future RFCs)
This RFC covers the development workflow up to merge. The following are deliberately out of scope:
Incident Management
How we define and classify incidents, on-call rotation, postmortem template, root-cause analysis methodology.
Deployment Workflow
CI/CD pipeline structure, environment promotion, feature flag governance, smoke tests, rollback procedures.
Observability Standards
What to log, metric naming conventions, alert thresholds, dashboard structure, trace context propagation.
Test Coverage Policy
Concrete coverage thresholds per repository, unit vs integration test definitions, mutation testing adoption.
Rollout Plan
Phased rollout from May 1, 2026. Grace period in May, religious enforcement from June.
Branch protection enforced from May 1. Four-phase process adopted on best-effort basis. Learn what works, identify friction, iterate on this RFC.
Full four-phase process required for all backend Tier 1 and Tier 2 work. Tier 3 follows lightweight flow. Severe-incident bypass remains available.
Lessons from backend adoption inform a parallel rollout to frontend and mobile teams.
Branch Protection is Non-Negotiable
Even during the May grace period, branch protection on main is active from May 1. The risk of an unverified merge to a production-deployed branch is too high to defer. The grace applies to documentation rigour, not to merge controls.
The full process applies to backend engineering first because the backend is the last line of defence — UIs can be bypassed, the backend cannot. Frontend and mobile inherit a refined version of the process after backend has worked through the kinks.
Internal Tooling Roadmap
These are not blockers for adoption. The process works manually; tooling makes it pleasant:
- •Automatic linkage between PRs, TIPs, TIAs, and TIDs
- •Reviewer assignment based on impacted surfaces declared in the TIA
- •Inline-edit tooling for highlighted business constraints
- •Dashboards for in-flight TIPs, ratification queues, and ARC turnaround
- •Agent-driven mock testing surfaced to product reviewers
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 on documentation. 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.
Grace-Period Ambiguity
May will see uneven adoption. Some teams will move faster than others. That is acceptable for one month; not beyond.
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?
- 6.How do we capture context updates from informal conversations into existing documents — addendum sections, comment threads on highlighted text, or something else?
Document Templates
Ready-to-use templates for each phase of the task lifecycle
# TID: <task title>
**Task ID:** <ticket / RFC reference>
**Owner:** <product / originator — not the implementing engineer>
**Implementing engineer:** <name>
**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>