STD-GOV-125: Technical Debt Management¶
| Field | Value |
|---|---|
| Standard | STD-GOV-125 |
| Title | Technical Debt Management |
| Status | Draft |
| Owner | Platform Lead |
| Created | 2026-04-03 |
| Review | Quarterly |
Purpose¶
Establish a systematic approach to identifying, quantifying, tracking and reducing technical debt across Simpaisa's payment gateway. Unmanaged debt in a system processing 270M+ transactions and $1B+ annually leads to increasing incident rates, slower delivery and mounting compliance risk across PK, BD, NP, IQ and EG.
Scope¶
All technical debt across Simpaisa services, infrastructure, data pipelines and tooling. Includes code-level debt, architectural debt, dependency debt, testing debt and documentation debt.
Current State¶
- Technical debt acknowledged informally but not systematically tracked.
- Legacy PHP services represent the largest known debt — migration to Go underway.
- No quantification framework — debt items are "known but not sized."
- Debt reduction competes with feature work without dedicated allocation.
- No visibility into debt trends over time.
Gaps¶
- No central debt registry — items scattered across Slack, Confluence and engineers' heads.
- No classification (deliberate vs accidental) — all debt treated equally.
- No quantification — impossible to prioritise without sizing.
- No dedicated capacity allocation for debt reduction.
- No dashboard tracking debt health over time.
Target State¶
- All known technical debt registered in Beads with tag
tech-debt. - Each item classified and quantified using a standard framework.
- 20% of quarterly engineering capacity dedicated to debt reduction.
- Dashboard tracks debt count, age and trend over time.
- Quarterly debt review at Architecture Review Board.
Debt Registry¶
All technical debt items are tracked in Beads:
bd create "Tech Debt: [description]" --tag tech-debt
Each item must include: - Description: What the debt is and where it lives. - Classification: Deliberate or Accidental (see below). - Impact score: 1-10 (see below). - Effort estimate: S / M / L / XL (see below). - Priority score: Impact × Effort multiplier. - Owner: Team responsible for resolution.
Classification¶
| Type | Definition | Example |
|---|---|---|
| Deliberate | Conscious trade-off accepted for speed/other reason | Skipped pagination on internal API for MVP |
| Accidental | Discovered after the fact; not a conscious choice | Duplicate database queries in payment flow |
Quantification¶
Impact Score (1-10)¶
| Score | Meaning |
|---|---|
| 1-3 | Low: cosmetic, minor inefficiency, no user impact |
| 4-6 | Medium: slows development, minor performance impact |
| 7-8 | High: causes incidents, blocks features, compliance risk |
| 9-10 | Critical: active production risk, regulatory exposure |
Effort Estimate¶
| Size | Definition | Multiplier |
|---|---|---|
| S | <1 day, single engineer | 4x |
| M | 1-5 days, single engineer | 3x |
| L | 1-3 weeks, may need team | 2x |
| XL | >3 weeks, cross-team effort | 1x |
Priority Score¶
Priority = Impact Score × Effort Multiplier
Higher score = address first. A high-impact, low-effort item (9 × 4 = 36) takes precedence over a high-impact, high-effort item (9 × 1 = 9).
Capacity Allocation¶
- 20% of each quarter's engineering capacity is reserved for technical debt reduction.
- Debt reduction sprint items selected by priority score.
- Platform Lead coordinates with team leads to allocate work.
- Debt reduction work follows normal development process (PRs, reviews, testing).
Dashboard¶
Grafana dashboard tracking: - Total open debt items (by classification and impact). - Debt age distribution (how long items have been open). - Debt trend (items created vs resolved per month). - Priority score distribution. - Quarterly reduction target vs actual.
Quarterly Review¶
- Conducted at Architecture Review Board (see
STD-GOV-124). - Review dashboard metrics and trends.
- Identify systemic debt patterns (e.g., recurring testing debt).
- Adjust capacity allocation if debt is growing faster than resolution.
- Celebrate significant debt reduction wins.
Actions¶
| # | Action | Owner | Deadline |
|---|---|---|---|
| 1 | Audit and register all known tech debt in Beads | All Teams | 2026-Q2 |
| 2 | Classify and score all registered debt items | Team Leads | 2026-Q2 |
| 3 | Build tech debt Grafana dashboard | Platform Team | 2026-Q2 |
| 4 | Allocate 20% capacity in Q3 sprint planning | Platform Lead | 2026-Q3 |
| 5 | Conduct first quarterly review at ARB | Platform Lead | 2026-Q3 |
References¶
STD-GOV-124-ARCHITECTURE-REVIEW-BOARD-CHARTER.mdTECHNOLOGY-RADAR.md