02 — Assessment Flow: bringing the AHU AI pattern to Koperasi

Status: proposal for review · Date: 2026-07-31
Companion to: koperasi.md (01 — System Map, the read-only survey this is built on)
Precedents it copies: tasks/prd-ptp-ai-transformation.md, tasks/prd-apostille-ai-transformation.md, docs/specs/apostille-build-plan.md

0. What this document is — and what it is not

This is the assessment flow, not the assessment. It defines the stages, the probes to run in each, the artifact each stage must produce, and the gate that must be passed before spending money on the next one. Running it produces the PRD + build plan; running it badly produces the two failure modes we have already paid for once each:

• PTP: we designed an akta-extraction flow before discovering PTP has no akta uploads anywhere (prd-ptp-ai-transformation.md §2.1). The document layer was assumed, not surveyed.
• Apostille: the extraction catalog over-claimed code reuse and had to be corrected adversarially before build ("Authoritative corrections" in docs/specs/apostille-extraction-catalog.md). Reuse was assumed, not inventoried.

Both failures are stages in this flow now: A1 (document reality) and A4 (reuse inventory).

The one-line framing. The system map answers "what is the koperasi system?" extremely well. It does not answer the only question our product depends on: which paper documents does a notary actually upload, and which typed form fields could those documents have filled? That is the assessment's centre of gravity. Everything else is sequencing.

1. The flow in one picture

Effort legend (one engineer; S ≤ 1 day · M 2–4 days · L 1–2 weeks): A0 S–M · A1 L · A2 M · A3 M · A4 M · A5 S · A6 M. Total assessment ≈ 3–4 weeks, of which A1 is half. A0–A1 are mostly waiting on AHU, so start them on day one and run A4 (pure in-repo work) in parallel.

2. Knowledge ledger — what the map gives us vs what the product needs

Read this table as the work order. Every ❌ is a probe in A0/A1; every ⚠️ is a confirmation task.

3. Stage-by-stage

A0 — Access & feasibility probes (effort S–M, mostly lead time)

Purpose: find out in week one whether this project is even executable, before anyone designs anything.

Artifact: koperasi-a0-access-report.md — grants obtained, real schemas, allow-list findings, volume table, corpus status.
Gate G0: DB read is live AND a document corpus is committed with a date. Anything less → park and escalate; do not proceed on assumptions.

A1 — Document reality survey ⭐ (effort L — the stage that decides the product)

Purpose: establish, per flow, the mapping uploaded document → form field it could auto-fill. This is the entire value proposition; everything else is plumbing.

Probes:

1. Doc-type taxonomy. SELECT DISTINCT whatever type column kop_t_pendirian_dokumen carries, per jenis_transaksi_id. Cross-check with the UI's upload screen labels. Output: the koperasi analogue of our DocumentType enum (backend/prisma/schema.prisma:20-60).
2. Required-bundle matrix. flow × doc-type × required/optional. Drives requiredDocs in a future defineFlow (backend/src/flow-engine/types.ts).
3. Is the akta on the critical path? The map's API response shape includes an akta_notaris section plus rapat, pengawas_pengurus, modal_koperasi, periode_pengurus, koperasi_pembentuk (§6.1) — strong evidence a real notarial deed (NPAK) is in the loop, unlike PTP. Confirm it, don't assume it. If confirmed, our akta extractor stack is directly on the critical path and this project is materially cheaper than Apostille was.
4. Field-by-field manual-entry census. For pendirian, list every field the notary types and tag each: from-akta / from-KTP / from-NPWP / from-bukti-setor / from-domisili / master-data-pick / genuinely-typed. The ratio of the first five to the last is the headline number of the whole assessment. (PTP's equivalent: ~40 fields, most extractable.)
5. Roster shapes. kop_data_anggota (members/officers) and kop_pemilik_manfaat (beneficial owners) — cardinality distribution, and which document each row is transcribed from. These two tables have no rules() at all (§7.3), i.e. nothing validates them today; that is an unusually clean value story for us, and it mirrors work we have already done for PP BO.
6. Corpus quality read. Take the A0.5 corpus and answer: scan vs native PDF? photo-of-screen? multi-doc-per-file? Determines whether our existing OCR config transfers or needs re-tuning.
7. Sample run. Push 20–30 corpus files through the existing pipeline unchanged (classifier + KTP/NPWP/domisili/bukti-setor extractors) and score field-level accuracy. Cheap, and it converts A4's reuse claims from theory to measurement.

Artifact: koperasi-extraction-catalog.md — the per-document-type extraction & validation catalog, same shape as docs/specs/apostille-extraction-catalog.md, with [CERTAIN] / [INFER] confidence tags per claim.
Gate G1: ≥60% of manually typed pendirian fields are traceable to an uploaded document, on real samples. Below that, the honest move is to rescope to validation-assist + name-similarity rather than sell an extraction product.

A2 — Flow inventory & AI-value scoring (effort M)

Purpose: rank the six flows so Phase 1 ships against the highest-value one instead of the alphabetically first one.

Score each flow: annual volume (A0.7) × manual fields eliminated (A1.4) × extractability (A1.7) ÷ build cost (A4), with a hard modifier for whether a back-office reviewer is in the loop (verifier time saved counts double — it is the scarce resource).

First-pass hypothesis, to be validated in A2, not treated as findings:

Artifact: ranked backlog table with the score inputs shown, so the ranking can be re-run when numbers change.

A3 — Integration & write-back decision (effort M)

Purpose: decide the read path, the write path, and — the political question — who owns the front door.

Recommendation going in (to be confirmed, not assumed): R1 + R2 for read (R1 for analysis/backfill, R2 as the supported runtime interface), and W1 standalone for Phase 1 — exactly the 2026-06-23 Apostille scope decision, which de-risked that project by removing an integration dependency from the critical path.

W3 is flagged red and should stay red. The map shows why: rows marked is_ods/is_migrasi skip nomor_transaksi generation entirely (§7.2, TransaksiKoperasi.php:381), the ODS clone path explicitly writes nomor_transaksi = '' (§7.2), and the notary identity check is skipped when is_migrasi = 1 (§7.4). Writing through that door means our submissions inherit the exact defect class that required eight repair runs and a rollback script in Feb 2026 (§7.1).

Probes: confirm A0.3's allow-list result end-to-end with a real service account; confirm whether /service/* errors still page an ops Telegram group (§6.1) and get a non-paging path for our traffic; get a written answer on who owns the front door — this is a product decision, not an engineering one, and it silently determines half the frontend scope.

Artifact: koperasi-integration-decision.md — one page, options, chosen path, signed off by product.

A4 — Reuse vs net-new inventory (effort M — run in parallel with A0/A1)

Purpose: produce an honest component ledger. The Apostille lesson is that the first draft of this always over-claims reuse, so this stage ends with an adversarial review pass.

Provisional ledger against the current engine:

Exit: an adversarial pass (a second reader whose job is to refute each ♻️) converts the ledger into build-ready truth. Every downgraded row is effort we would otherwise have discovered mid-build.

A5 — Data-quality & risk register (effort S)

Purpose: turn the map's §7 — unusually candid and the most valuable section for us — into concrete engineering consequences.

Artifact: a risk table carried forward into the PRD, each row tagged design constraint / validator severity / ops ask.

A6 — Scope lock (effort M)

Purpose: produce the two documents that end the assessment: a PRD in the prd-ptp-ai-transformation.md shape (context, codebase findings that changed the design, revamped process per flow, out-of-scope) and a phased build plan in the apostille-build-plan.md shape (Phase 0 scaffold → … with per-task files, deps, effort, and an explicit exit criterion per phase).

Non-negotiables to carry into the plan:
- Phase 0 is always scaffold-only — enum + registry entry + route + page shell + rematch dispatch wiring. It exits when a submission can be created and the shell renders, with no extraction.
- The first value phase is identity (KTP → identity block + cross-validation), because it is the cheapest ship-able win and the #1 typo field. Apostille Phase 2, PTP step 5 — same shape both times.
- All model/OCR egress goes through the gateway with the standard headers and queue semantics (ahu-gpu-manager/docs/CONVENTIONS.md); engine changes stay dormant until the env flip.
- Read-only means read-only — Phase 1 writes nothing back to AHU_KOPERASI.

4. Gate summary

5. Where this sits in the queue — say it out loud

The standing priority is PP → Apostille/Legalisasi → PT. Koperasi is a fourth domain, and this assessment is ~3–4 engineer-weeks before any build starts. Two honest options:

1. Assess now, build later. A0/A1 have long external lead times (DB grants, document corpora) that do not consume engineering capacity while waiting. Filing those requests now costs almost nothing and means the build can start the moment the queue clears. Recommended.
2. Defer entirely until PP + Apostille are shipped, and accept a cold start later.

What is not on the table is starting the build in parallel: koperasi introduces net-new registry clients, a net-new classifier taxonomy, and new akta schemas — it is not a configuration of an existing flow.

6. Asks for AHU (file these on day 1)

1. Read-only MySQL grant on AHU_KOPERASI + AHU_BADAN_HUKUM (analyst-level, our IP range).
2. A document corpus — ≥50 files per document type, across years and provinces, with the matching kop_t_pendirian_dokumen rows.
3. information_schema dump for the core kop_* tables (the repo has no CREATE TABLE — §4.1).
4. SELECT on AHU_KOPERASI_DCMS.allowed / group / auth_assignment, and on kop_setting.
5. A staging/sandbox koperasi instance, plus an oss/ods-class service account if API integration survives A3.
6. A named product owner who can answer the front-door question in §A3.
7. Confirmation of who owns the NPAK notary registry and whether it is queryable.

Appendix — open questions this flow inherits from the map

The map's nine open questions are not loose ends; they are assigned: