Case Studies

№ 146

DoCoDeGo Starter Recap

Scene STA

Case study · 146 starter / reference

The starter, by the numbers.

Three engineers. Twenty-six working days. One reference implementation that everyone after them inherits.

180

Files

incl. specs

7

Apps

web · cli · api

7

Packages

shared kernel

9

Phases

spec → ship

9 phases · spec → ship 26 days

#	Phase	Output	Days	ICS
01	Intent capture	SPEC-001 · charter	2	78
02	Domain model	SPEC-014 · entities	3	84
03	Kernel packages	7 packages · types-first	4	88
04	Composition graph	agent · planner · reviewer	2	90
05	Web surface	astro · 22 routes	5	92
06	CLI + API	6 commands · 14 endpoints	3	91
07	Governance gates	kill-switch · audit log	2	95
08	Telemetry	ICS · AAR · GTR	2	89
09	Hardening · ship	v1.0.0 tagged	3	91
	Totals · avg		26	88.7

№ 147

First-Team Adoption Story

Scene STA

Case study · 147 first-team adoption · 6 weeks

From ICS 41 to ICS 88, in six weeks.

A 7-person product team, no prior DoCoDeGo exposure, inheriting a year of un-spec'd code. What they did, week by week.

ICS climb · weekly average

41 → 88 · +47

W1W2W3W4W5W6

W1 ICS 41 Audit + intent capture

Inherited 14 specs averaging ICS 41. Half were stale. Team spent the week reading code to recover intent.
W2 ICS 56 First clean SPEC

Rewrote SPEC-003 from scratch using the four-block template. First spec to clear the linter at ICS 72.
W3 ICS 64 Pillar role assignment

@author / @architect / @governor named explicitly. Standups dropped from 4× to 2× per week — roles absorbed the coordination.
W4 ICS 73 First agent composition

Planner + coder + reviewer wired to SPEC-007. First PR shipped from spec without human intervention in the diff loop.
W5 ICS 79 Kill-switch fires

Governance caught drift > 30% on SPEC-011. Team treated it as a win, not a failure. Cultural turning point.
W6 ICS 88 Cruise

Average ICS across active specs hit 88. Founder signed off on framework adoption company-wide.

"Six weeks. I was budgeting six months. The team didn't change — the artefact they ship changed."

— @founder · sign-off memo, week 6

№ 148

Incident Prevented By Governance

Scene STA

Case study · 148 post-incident review

The PR that didn't ship.

Nine minutes, end to end. An agent drifted from SPEC-204. Drift-bot caught it. Kill-switch fired. Spec was tightened. The fix re-ran clean. No customer ever saw anything.

Incident: INC-0184
Sev: SEV-2
Status: RESOLVED

Audit trail · INC-0184 UTC · newest top

14:02:11 CLEAR governor

Re-run accepted. Diff against SPEC-204 v1.3 = 4%. Within tolerance. Merge unblocked.
13:58:40 RERUN AGENT-7

Composed new diff against SPEC-204 v1.3. 122 lines. Tests pass.
13:51:09 SPEC @architect

Patched SPEC-204 → v1.3. Added explicit currency-precision constraint, refund-window edge case.
13:47:22 KILL KILL-SWITCH

Auto-reverted PR #4471. Reason: drift 41% > threshold 30%. PR closed, branch quarantined.
13:46:55 WARN drift-bot

Drift detected: SPEC-204 §3.2 unfulfilled; agent introduced unspec'd rounding logic on line 88.

SPEC-204 · diff v1.2 → v1.3 §3.2 · pricing

  ## Constraints- All monetary values are stored as integers (cents).+ All monetary values are stored as integers (cents) with currency-explicit rounding.+ Refund window: 30 days; partial refunds prorate per-day to the cent — never round up.  ## Failure Modes+ 4. Silent rounding-up on partial refunds (caught INC-0184).

№ 149

Spec Improved By Iteration

Scene STA

Case study · 149 SPEC-074 · 17 days · 8 revisions

From stub to sign-off, in eight revs.

Most specs are not born — they are debugged. SPEC-074's climb from ICS 42 to 92 is what that looks like in practice.

Started: 42
Shipped: 92

ICS by revision

8 revs · +50 pts

42

v0.1

51

v0.2

58

v0.3

64

v0.4

71

v0.5

79

v0.6

86

v0.7

92

v1.0

Key revisions · what moved the score 3 of 8

v0.5 +7 Failure modes block introduced. Two modes, one edge case.
v0.6 +8 Intent rewritten — separated "what" from "why". Big jump.
v1.0 +6 Sign-off rev. Owner + governor co-signed. Frozen.

Before · v0.1 ICS 42

## Intent
Sync inventory from supplier feed every hour
so the website has fresh stock counts.

After · v1.0 ICS 92

## Intent
WHAT: Reconcile our authoritative stock counts
with the supplier feed once per hour.
WHY: Oversell incidents cost us 0.4% of GMV
last quarter; sub-60-min staleness eliminates
the bulk of them.

"v0.1 → v0.6 is the rev I'd skip if I could. Separating WHAT from WHY in the Intent block should have been step zero. Every later jump came from constraints and failures I could only see once intent was clean."

— @author · post-sign-off note · SPEC-074

№ 150

Multi-Agent Orchestration · Day One

Scene STA

Case study · 150 first day · 5 agents · 1 feature

Spec at 09:02. Shipped by 11:47.

Five agents, one human gate, one feature. The team's first attempt at multi-agent composition on SPEC-118 (search relevance), captured event-by-event.

Spec → ship: 2h 45m
Human time: 7 min

The composition · 5 agents

A1 Planner

decompose intent → task graph

A2 Coder

implement tasks → diff

A3 Tester

generate cases → verdict

A4 Reviewer

gate diff vs spec → sign-off

A5 Deployer

roll out → release tag

Hand-offs · SPEC-118 8 events · ↓ oldest first

09:02 auto spec → A1

SPEC-118 v1.0 ingested
09:14 auto A1 → A2

task graph · 7 nodes
10:31 auto A2 → A3

diff · 412 LOC · 14 files
10:58 auto A3 → A4

test results · 38 pass · 0 fail
11:04 gate A4 → @governor

sign-off requested · drift 6%
11:11 human @governor → A5

sign-off ✓ · proceed
11:23 auto A5 → ship

tag v0.18.0 · canary 10%
11:47 auto ship → done

canary green · 100% rollout

№ 1281

Case · Greenfield SaaS, Day Zero

Scene STA do

Case study · 1281 greenfield · 4 engineers · 90 days

Day zero. Spec one. Paid customers by day ninety.

A four-person founding team at an anonymised workflow-automation SaaS adopted DoCoDeGo from the first commit. No legacy, no inherited intent, no political cost. The bill came due in weeks one — three. The payoff arrived in week thirteen.

Avg ICS: 87
P1 incidents: 0

Day 0 ICS 71 Charter + first SPEC ★★★★★

SPEC-001 · 1-page product charter, signed by all four founders
Day 7 ICS 78 Domain spine ★★★★★

8 entity specs, 14 acceptance criteria, one shared glossary
Day 21 ICS 83 First agent composition ★★★★☆

Planner · coder · reviewer triad wired to SPEC-007
Day 38 ICS 86 Closed beta ship ★★★★★

v0.5 to 12 design-partner accounts, zero post-ship hotfixes
Day 61 ICS 90 Kill-switch hardened ★★★★☆

Drift threshold 25%, audit log retention 90d, two near-misses caught
Day 90 ICS 92 First paying customers ★★★★★

GA · 7 paid seats · 0 P1 incidents in first 30d of revenue

"The cost of writing specs on day zero felt extravagant — we were four people and the README still said TODO. We wrote SPEC-001 anyway. Nine weeks later it was still readable and still correct. That was the entire ROI argument, settled."

— the CTO · post-GA retro, day 95

№ 1282

Case · Brownfield Bank Migration

Scene STA go

Case study · 1282 tier-2 retail bank · 23 services · 6 quarters

Fourteen years of un-spec'd intent, recovered in six quarters.

The original authors had retired. The runbooks were Word documents. The bank's core-platform group ran a patient, governed recovery — 19 of 23 services ratified, zero regulator findings across two audits.

Recovered: 19 / 23
Audit findings: 0

Services governed · cumulative

target 23

1

Q1

3

Q2

6

Q3

10

Q4

15

Q5

19

Q6

Service status · 8 of 23 shown avg ICS 76

svc-ledger ICS 94 Governed
svc-statements ICS 88 Governed
svc-card-auth ICS 91 Governed
svc-aml-screening ICS 86 Governed
svc-batch-clearing ICS 72 Partial
svc-fraud-rules ICS 81 Governed
svc-onboarding-legacy ICS 54 In-flight
svc-archive-tape ICS 41 Backlog

"We did not migrate code. We migrated intent. The code was a hostage held by people who had moved on. The framework gave us an extraction protocol."

— the lead architect · programme exit memo

№ 1283

Case · Pivot Validated By Spec

Scene STA do

Case study · 1283 Series-A · 7 engineers · 10-day decision

Three pivots. Three specs. Ten days. One survivor.

Instead of building three half-prototypes, the founders wrote three candidate specs and grilled them. Two failed on paper — the third one survived four pillar reviews and became the pivot.

Days to decide: 10
Code written: 0

Candidate A 65 / 100

Match-as-a-Service API

Open the matching engine as a paid API for other consumer apps.

DO

22
CO

14
DE

18
GO

11

Verdict Fail

CO + GO too thin — no story for abuse-rate governance on third-party callers.

Candidate B 90 / 100

Vertical for hiring

Re-aim matching at job-candidate / role pairing in the SMB segment.

DO

24
CO

22
DE

23
GO

21

Verdict Survive

Every pillar cleared. GO had the cleanest story (consent + bias audits already mapped).

Candidate C 69 / 100

AI travel concierge

Repurpose matching as an itinerary-builder against partner-supplier inventory.

DO

19
CO

24
DE

17
GO

9

Verdict Fail

GO score collapsed under partner data-handling constraints. CO was strong but irrelevant.

"Candidate C had the best CO story by a country mile — the engineers were excited. GO killed it. Without the grilling structure we would have built C, hit the partner-data wall in month four, and never recovered the runway."

— the founder · pivot-decision memo, day 11

№ 1284

Case · Internal Platform Adoption

Scene STA co

Case study · 1284 platform · 9 engineers · 14 consumer teams · 2 quarters

A platform team treats DoCoDeGo as the product.

Nine engineers, fourteen consumer teams, two quarters. Adoption wasn't mandated — it was sold, supported, and measured. Six of fourteen teams crossed into cruise; one bounced out. The funnel shows where the leakage happened.

Adopted: 8 / 14
Cruising: 6 / 14

Adoption funnel · 14 consumer teams survivor %

Aware

14 · 100%
Curious

12 · 86%
Trialled

10 · 71%
Adopted

8 · 57%
Cruising

6 · 43%

ICS uplift · per consumer team baseline → current

T-01 38→88

+50
T-02 41→91

+50
T-03 44→86

+42
T-04 36→81

+45
T-05 52→90

+38
T-06 47→84

+37
T-07 39→78

+39
T-08 42→89

+47
T-09 48→71

+23
T-10 33→64

+31
T-11 51→70

+19
T-12 45→58

+13
T-13 40→47

+7
T-14 37→41

+4

"We had spent five years pushing platforms onto teams. The week we stopped pushing and started selling was the week adoption stopped being a fight."

— the principal engineer · end-of-quarter retro

№ 1285

Case · Regulated Health-Tech

Scene STA go

Case study · 1285 regional health-tech · HIPAA-adjacent · audit cleared

An auditor's view of a governed release.

The vendor had failed two previous audit cycles before adopting DoCoDeGo. The third was their first under the framework. Zero major findings. Three minor advisories. One cycle to clear, where the previous baseline was three.

Controls mapped: 29 / 29
Major findings: 0

Compliance map · 6 of 29 controls shown control → spec → evidence

Control	Spec criterion	Evidence
CTL-04 · access logging	SPEC-118 §AC-3	audit-log retention · 90d · checksummed
CTL-09 · encryption-at-rest	SPEC-118 §AC-5	KMS rotation policy · q90d · evidenced
CTL-12 · break-glass access	SPEC-204 §AC-2	two-person rule · 14 invocations · all reviewed
CTL-17 · data minimisation	SPEC-118 §AC-7	de-id transform · spec'd + tested · 0 drift
CTL-22 · incident response	SPEC-301 §AC-4	2 incidents · MTTR 11m / 8m · post-mortem links
CTL-29 · vendor risk	SPEC-301 §AC-6	4 subprocessors · all DPA-signed · attested q1/q2

Audit-trail completeness · 12 months

avg 91 · floor 78

M01

M02

M03

M04

M05

M06

M07

M08

M09

M10

M11

M12

"The evidence package was, frankly, easier to audit than the controls catalogue itself. Every control mapped to a named criterion in a versioned specification, every criterion to a dated artefact. We cleared in one cycle. That is uncommon."

— the external auditor · cover letter to attestation report

№ 1286

Case · Five-Team Rollout

Scene STA de

Case study · 1286 B2B logistics · 5 teams · 12 weeks

Three waves. Five teams. Twelve weeks. One cadence.

Rollout staggered in waves of two — never all-at-once, never one-at-a-time. The first wave became the second wave\'s tutorial, the second wave became the third wave\'s template, and reuse compounded.

Teams cruising: 5 / 5
Reuse edges: 5

Rollout Gantt · weeks 0 — 12 kickoff · gate · cruise

Team A W1

0→3→7
Team B W1

0→4→8
Team C W2

3→6→10
Team D W2

3→7→11
Team E W3

6→9→12

W0W2W4W6W8W10W12

Inter-team spec reuse · 5 edges emerged organically

Team A → Team C lifted SPEC-104 acceptance criteria for retry semantics
Team B → Team D reused SPEC-118 audit-log template wholesale
Team A → Team E forked SPEC-201 failure-modes block (saved ~2 days)
Team C → Team D shared SPEC-307 currency-precision constraint
Team D → Team E adopted SPEC-302 kill-switch threshold (drift 25%)

"We had budgeted six months. Twelve weeks in, all five teams were cruising and the first wave was teaching the third wave. We had been treating rollout as a procurement; it was a teaching."

— the VP of engineering · q3 board memo

№ 1287

Case · Failed Adoption · Honest Post-mortem

Scene STA go

Case study · 1287 analytics vendor · 30 eng · rolled back wk 11

We tried, we failed, here is what failed.

Eleven weeks in, the team voted to roll back to their previous workflow. Six months later they ran this post-mortem. The framework was not the failure; the rollout was. Five anti-patterns, candidly named.

Lost eng-weeks: ~20
Would retry?: Yes

Five anti-patterns · self-identified non-defensive

AP-01 Top-down mandate, no champion ~6 eng-weeks

Executive memo announced framework adoption without a named owner on the floor. Specs were written grudgingly, scored at floor ICS, and nobody iterated them.
AP-02 Skipped the audit ~4 eng-weeks

Team adopted templates without first recovering intent from the existing 60-spec corpus. New specs and old code talked past each other.
AP-03 Tooling without governance ~5 eng-weeks

Spec linter and ICS scorer installed; kill-switch and drift detector were not. Agents drifted into unspec'd territory, nobody noticed for three weeks.
AP-04 No retreat path defined ~3 eng-weeks

When friction accumulated, the team had no agreed point at which to pause, retro, and re-plan. They limped instead of stopping.
AP-05 Measured adoption, not value ~2 eng-weeks

Leadership tracked "% of work spec'd first" instead of "% of incidents prevented by spec." The metric drove ritual, not outcome.

"I led this rollout. I want to be clear that the rollback was the right call, and that the framework was not what failed. We pushed it through the org the way we push tools through the org, and DoCoDeGo is not a tool — it is a working agreement. You cannot procure those."

— the engineering lead · six-month post-mortem

№ 1288

Case · Spec Grilling Saves The Day

Scene STA do

Case study · 1288 SPEC-209 · grilling · 2h

A two-hour grilling. A $400k mistake un-shipped.

Twelve questions. Four pillars. Three things the spec author had not noticed. The session ended with the spec sent back — and a hand-shake instead of an incident.

Questions: 12
Liability avoided: ~$400k

Pillar · DO 3 questions

Q1

What is the WHY here, separate from the WHAT?

→ Reduce abandoned-checkout rate by lowering buyer perceived-risk via longer refund window.
Q2

Which acceptance criterion will catch a refund issued after the 90th day?

→ … we don't have one. Added: §AC-7.
Q3

What is the negative criterion — what does this spec promise NOT to do?

→ Missing. Adding: "Does not apply to digital goods or marketplace-of-marketplaces resale flows."

Pillar · CO 3 questions

Q1

Which existing service owns refund timing logic today?

→ svc-refunds. Last touched 11 months ago.
Q2

Does the planner agent need access to ledger writes for this?

→ No — ledger writes go through svc-ledger. Adding constraint: planner is read-only on ledger.
Q3

Does this require a schema migration?

→ Yes — refund_window_days column. Surfaced in §CST-3.

Pillar · DE 3 questions

Q1

How is partial rollout gated?

→ Feature flag on seller-tier. Rollout to top-decile sellers first.
Q2

What is the rollback if refund rate spikes above 1.5x baseline?

→ Auto-revert via the existing kill-switch, threshold tuned.
Q3

What's the smallest releasable slice?

→ A two-seller pilot, no UI changes, manual refund flow. Two days of work.

Pillar · GO 3 questions

Q1

Which jurisdictions ALREADY mandate >60-day refund windows?

→ Two EU markets. Adding §AC-8: spec must reconcile with statutory floor per region.
Q2

What is the unfunded refund liability if a chargeback exceeds the new window?

→ Original answer: "minimal." Re-modelled: ~$400k worst-case quarterly. Spec sent back.
Q3

Who is the named governor for this spec?

→ Was unset. Named: head of payments risk. Co-sign required.

"I wrote the original spec. I had reviewed it three times. The grilling found three things I had not seen — one of them was a quarter of a million dollars. The cost of two hours of four people\'s time is the cheapest insurance we run."

— the payments lead · post-grilling note

№ 1289

Case · Drift Detector Catches A Silent Bug

Scene STA go

Case study · 1289 SPEC-411 · drift 38% · 03:09 — 03:14 UTC

Green CI. Silent bug. Drift detector tripped at 03:09.

Every test passed. The agent had "improved" the rounding mode to the IEEE default. Drift detection noticed the spec said half-up. Two invoices over £1.20, the rest fractions of a penny — but rounding bugs are how lawsuits start.

Drift: 38%
Detect → revert: 2s

Detection log · 6 events · oldest first UTC

03:14:08 CLEAR governor PR re-opened. Agent re-ran against SPEC-411 v2.2 unchanged. Diff against spec = 3%. Merge restored.
03:13:41 RERUN AGENT-2 Reverted half-even change. Restored half-up rounding mode. 38 LOC adjusted.
03:11:02 TRIAGE @reliability On-call paged. Spec §AC-2 mandates half-up. Agent introduced half-even silently. Hold the line, do not roll forward.
03:09:55 KILL KILL-SWITCH Auto-reverted PR #8821. Reason: drift 38% > threshold 25% on SPEC-411 §AC-2 (rounding).
03:09:53 WARN drift-bot Drift 38% detected. Rounding mode mismatch: spec=HALF_UP, code=HALF_EVEN. 411 invoices in last hour potentially affected.
02:47:10 PASS CI All tests pass. Merge unblocked. Spec coverage 100% (but spec did not test the rounding-mode constant directly).

Spec § AC-2 · canonical SPEC-411 v2.2

// Acceptance §AC-2
// Currency amounts are rounded HALF_UP
// to the smallest unit of the active
// currency (e.g. 1p for GBP, 1c for EUR).
const ROUND_MODE = RoundingMode.HALF_UP;

Agent diff · drift PR #8821

- const ROUND_MODE = RoundingMode.HALF_UP;
+ // banker's rounding — IEEE default
+ const ROUND_MODE = RoundingMode.HALF_EVEN;

Customer zero · invoices affected before revert 411 total · all reissued

JD-GB · GBP < 1c: 287 > 1c: 2
JD-IE · EUR < 1c: 119 > 1c: 0
JD-US · USD < 1c: 3 > 1c: 0

"The agent\'s reasoning was correct in isolation — half-even IS the IEEE default. It was wrong here because the spec said otherwise, and the spec said otherwise for a reason a court would understand. Drift detection is the part of governance that asks \"do you have a reason\" before \"is this clever.\""

— the reliability engineer · incident note, same morning

№ 1290

Case · Convention Promotion Pays Off

Scene STA co

Case study · 1290 CONV-014 · retry-with-jitter · 6 months

Three specs re-invented the wheel. The fourth wouldn't.

The team noticed the duplication in April, promoted the pattern in a fortnight, and watched twenty-two specs reuse it over the next six months. Median spec-authoring time on retry-touching work dropped 41%.

Adopting specs: 22
Authoring-time saved: −41%

Reuse heatmap · CONV-014 · 6 months specs adopting per category

Spec category	Apr	May	Jun	Jul	Aug	Sep
service-to-service	3	4	5	5	6	6
webhook-delivery	0	1	2	3	3	4
batch-ingest	0	0	1	2	3	5
partner-api	0	0	0	1	2	4
background-jobs	0	0	0	0	2	3

Promotion timeline · 3 steps notice → promote → enforce

Apr 11 STEP 1 Noticed: three specs (-091, -098, -103) each define retry-with-jitter independently. None reference each other.
Apr 22 STEP 2 Promoted: CONV-014 written, ratified by architect council, added to convention index.
May 04 STEP 3 Enforced: linter checks new specs touching retry — must reference CONV-014 or include a "deviation" block justifying alternative.

"Promote on the fourth re-invention, not the second. Two is a coincidence and you don\'t yet know the right shape. Four is a pattern. Promoting too early calcifies a half-formed idea; promoting too late leaks compounding interest."

— the architect · convention-council retro

№ 1291

Case · From L1 To L3 In One Quarter

Scene STA co

Case study · 1291 infra · 6 engineers · L1 → L3 in 12 weeks

Trust budgets, burned down deliberately.

Autonomy is earned, not announced. Three consecutive weeks under the drift allowance unlock the next level. The team rode the budget down from five incidents-per-week to one — and then stopped there on purpose.

Human hours / week: 28 → 6
Gates cleared: 2 / 3

Trust budget · weekly · allowance vs incidents

12 weeks · L1 → L3

4

W01

2

W02

1

W03

0

W04

2

W05

1

W06

3

W07

0

W08

0

W09

0

W10

0

W11

1

W12

Yellow-green: weekly allowance · Ink: incidents observed · Red: breach

GATE-1 W04

L1 → L2 Cleared

Three consecutive weeks at or under allowance. Drift detector tuned, kill-switch tested live (1 successful trip in W02).

GATE-2 W10

L2 → L3 Cleared

Three more consecutive weeks at or under allowance. Spec coverage on auto-mergeable scope = 100%. Governor co-sign.

GATE-3 —

L3 → L4 Held

Held. Team deliberately stayed at L3 — anonymised governor judgment that L4 (auto-deploy) needs another quarter of evidence.

"L3 was not the goal. The goal was that the level the team is at, the team can justify with evidence. We held at L3 because L4 needed another quarter of clean weeks, and the budget didn\'t lie."

— the team lead · end-of-quarter review

The framework is real.The community is forming now.

The framework is real.
The community is forming now.