Menambang Loop: Bagaimana Perubahan Menjadi Memori Institusional

Angka dalam tulisan ini mencerminkan sistem pada saat publikasi (Februari 2026). Lihat halaman tim kami untuk angka terkini.

Setiap tim engineering menghadapi tantangan yang sama: perubahan terjadi terus-menerus, tetapi alasan di balik perubahan itu menghilang. Enam bulan kemudian, seseorang bertanya “kenapa kita memakai DuckDB untuk stage pipeline?” dan jawabannya hanya hidup di kepala siapa pun yang membuat keputusan itu — jika orang itu masih ada.

Kami membangun sebuah mining workflow yang menutup loop ini. Perubahan mengalir lewat commit git, diproses oleh pipeline mining kami, menjadi entri changelog terstruktur dan catatan keputusan arsitektural, lalu mengalir kembali ke agen AI kami lewat query CLI. Hasilnya: memori institusional yang bisa diakses baik oleh manusia maupun AI.

Masalahnya: Keputusan Menguap

Bayangkan skenario yang umum. Seorang developer melakukan commit:

feat(canonical): add DuckDB runtime for pipeline stages

Commit ini merepresentasikan sebuah pilihan arsitektural yang signifikan. Tim mengevaluasi opsi, mempertimbangkan trade-off, dan akhirnya memilih DuckDB karena alasan-alasan spesifik. Tetapi seluruh konteks itu hanya hidup di:

• Sebuah thread Slack (mungkin sudah terhapus)
• Ingatan seseorang (pasti memudar)
• Sebuah komentar di kode (mungkin, kalau Anda beruntung)

Tiga bulan kemudian, anggota tim baru bertanya: “Haruskah saya pakai DuckDB atau SQLite untuk stage baru ini?” Tanpa memori institusional, mereka akan menciptakan ulang roda atau membuat pilihan yang tidak konsisten.

Loop-nya: Dari Commit ke Konteks

Mining workflow kami mengubah histori git menjadi pengetahuan yang bisa di-query:

Git Commits
    │
    ▼
┌─────────────────────┐
│  mine sync          │  ← Build index from git history
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  mine candidates    │  ← Surface commits for review
└─────────────────────┘
    │
    ▼
┌─────────────────────┐
│  Classification     │  ← Human or LLM assessment
│  (changelog or ADR) │
└─────────────────────┘
    │
    ├──────────────────────┐
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ Changelog   │    │ Decisions     │
│ Ledger      │    │ Registry      │
│ (JSONL)     │    │ (YAML files)  │
└─────────────┘    └───────────────┘
    │                      │
    ▼                      ▼
┌─────────────┐    ┌───────────────┐
│ CHANGELOG.md│    │ orkestra CLI  │
│ per package │    │ queries       │
└─────────────┘    └───────────────┘
    │                      │
    └──────────────────────┘
              │
              ▼
      ┌───────────────┐
      │ AI Agents     │
      │ (via CLI)     │
      └───────────────┘

Wawasan kuncinya: baik changelog maupun architectural decision mengalir dari histori git yang sama, diproses lewat satu pipeline terpadu. Ini memastikan tidak ada yang lolos begitu saja.

Bagaimana Mining Bekerja

Langkah 1: Sinkronkan Indeks

uv run orkestra mine sync

Perintah ini memindai histori git dan membangun indeks dari semua commit. Ia mengekstraksi sinyal terstruktur dari setiap commit:

• Tipe conventional commit (feat, fix, chore, docs)
• Scope (package atau area mana)
• Penanda breaking change
• File yang tersentuh dan metrik kompleksitas

Langkah 2: Periksa Status Cakupan

uv run orkestra mine status

Beginilah status kami saat ini:

Mining Status
=============

Decisions
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Extracted:       476
    Skipped:       15161

Changelog
---------
  Coverage:        100.0%
    Processed:     15637  (of 15637)
    Released:       6799
    Skipped:        8838

15.637 commit diproses. 476 menjadi architectural decision. 6.799 menjadi entri changelog. Setiap commit terklasifikasi.

Langkah 3: Ambil Kandidat untuk Ditinjau

uv run orkestra mine candidates --limit 50 --full

Ini memunculkan commit yang belum diproses, lengkap dengan konteks untuk klasifikasi:

on
{
  "sha": "90571786d99166c0039ca2e80e4d9cd96184bd85",
  "date": "2026-01-26",
  "subject": "feat(canonical): add DuckDB runtime for pipeline stages",
  "signals": {
    "commit_type": "feat",
    "scope": "canonical",
    "breaking": false,
    "is_releasable_type": true,
    "domains_affected": ["pipeline", "data-architecture"]
  },
  "body": "Establishes DuckDB as canonical in-process analytical database...",
  "files_changed": ["packages/canonical/pipelines/stages/duckdb_runtime.py", "..."],
  "stats": {"files": 8, "insertions": 450, "deletions": 120}
}

Sinyal-sinyal ini membantu memandu klasifikasi: is_releasable_type: true menunjukkan ini seharusnya muncul di changelog. Jumlah insertion yang besar dan file infrastruktur menunjukkan ini mungkin juga sebuah architectural decision.

Langkah 4: Klasifikasikan Commit

Dua jalur bercabang di sini: entri changelog dan architectural decision.

Untuk entri changelog:

uv run orkestra mine classify abc123 --changelog added

Ini mencatat bahwa commit abc123 seharusnya muncul di changelog di kategori “Added.”

Untuk architectural decision:

Pertama, dapatkan ID decision yang sungguhan:

uv run orkestra decisions new --domain pipeline --dry-run
# Returns: DEC-PL-143

Lalu klasifikasikan dengan ID decision tersebut:

uv run orkestra mine classify abc123 --decision DEC-PL-143

Ini menautkan commit ke sebuah decision record yang akan dibuat atau diperbarui.

Untuk pemrosesan batch (apa yang sebenarnya kami lakukan):

# Generate classifications file with LLM assistance
uv run orkestra mine commit --input classifications.jsonl

Format JSONL mendukung kedua domain dalam satu proses:

on
l
{"sha":"abc123","domain":"changelog","action":"release","category":"added","summary":"Add DuckDB runtime for pipeline stages"}
{"sha":"abc123","domain":"decisions","action":"extract","decision_id":"DEC-PL-142"}
{"sha":"def456","domain":"changelog","action":"skip","reason":"Chore: dependency update"}

Langkah 5: Render Output

uv run orkestra changelog render --package <pkg>

Ini menghasilkan file CHANGELOG.md per package dari ledger. Changelog adalah artefak turunan — hapus saja, dan mereka akan terbangun ulang secara sempurna dari ledger sumbernya.

Struktur Decision Record

Decision hasil ekstraksi menjadi file YAML dengan metadata yang kaya:

id: DEC-PL-142
title: Adopt DuckDB as Canonical Processing Runtime for Pipeline Stages
domain: pipeline
status: active
created: '2026-01-26'
summary: |
  Establishes DuckDB as the canonical in-process analytical database for pipeline
  stage transformations. Provides a shared runtime module that resolves settings
  from pipeline defaults with stage-level overrides.

context: |
  Pipeline stages performing data transformations each independently configured
  DuckDB connections. This led to inconsistent settings, duplicated configuration
  code, and no way to tune DuckDB globally for a pipeline run.

rationale:
  - DuckDB provides efficient in-process OLAP with zero configuration deployment
  - Centralized runtime module eliminates duplicated DuckDB setup across stages
  - Hierarchical settings enable global tuning with stage-level overrides
  - Memory limits and thread counts can be adjusted per-pipeline

impact:
  positive:
    - Consistent DuckDB configuration across all pipeline stages
    - Single point of control for memory/thread tuning
    - Reduced code duplication in conversion and export stages
  negative:
    - Adds dependency on shared runtime module
    - Stages must adopt new configuration pattern

source_commits:
  - sha: 90571786d99166c0039ca2e80e4d9cd96184bd85
    message: 'feat(canonical): add DuckDB runtime for pipeline stages'
    date: '2026-01-26'
    role: primary

files:
  - packages/canonical/pipelines/stages/duckdb_runtime.py
  - packages/canonical/pipelines/runner.py
  - packages/canonical/pipelines/stages/convert_hdx_admin_boundaries_to_geoparquet.py

related:
  - DEC-DA-014  # Data architecture decisions that influenced this

Setiap decision menaut kembali ke commit sumbernya. Setiap decision menyebutkan file mana yang terpengaruh. Relasi antar decision bersifat eksplisit.

Integrasi CLI: Meng-query Memori Institusional

Di sinilah loop-nya menutup. Agen bisa meng-query decision lewat CLI:

# Search by topic
uv run orkestra decisions search --query "retry"

Mengembalikan decision tentang logika retry, error handling, pola pemulihan.

# Get full details on a specific decision
uv run orkestra decisions info DEC-PL-142

Mengembalikan decision record lengkap dengan konteks, rationale, dan dampaknya.

# List recent decisions for context
uv run orkestra decisions list --limit 15

Menunjukkan pilihan arsitektural apa yang baru-baru ini dibuat.

Bagaimana Agen Menggunakan Ini

Instruksi baseline orchestrator kami mencakup:

**Essential CLI commands:**
- `orkestra decisions search "X"` — Temukan keputusan arsitektur

Ketika seorang agen diminta mengimplementasikan sesuatu yang berkaitan dengan DuckDB, ia bisa memeriksa terlebih dahulu:

uv run orkestra decisions search --query "DuckDB"

Dan menemukan DEC-PL-142, mempelajari:

• Mengapa kami memilih DuckDB (konteks)
• Bagaimana menggunakannya dengan benar (agent_guidance)
• File apa yang perlu dilihat (files)
• Decision terkait apa yang ada (related)

Agen tidak menciptakan ulang roda. Ia membangun di atas pola yang sudah mapan.

Uji Tiga Pertanyaan

Tidak setiap commit layak mendapat decision record. Kami menggunakan Uji Tiga Pertanyaan untuk menyaring:

1. Apakah ini sulit dibuat? Apakah butuh analisis signifikan, evaluasi trade-off, atau perdebatan?
2. Apakah mahal untuk diubah? Akankah membalikkan keputusan ini membutuhkan rework yang signifikan?
3. Apakah berdampak lintas sistem? Apakah ini memengaruhi banyak package atau menetapkan pola yang akan diikuti orang lain?

Jika sebuah commit menjawab “ya” untuk setidaknya satu dari pertanyaan ini, commit itu menjadi kandidat untuk ekstraksi decision. Tingkat khas kami: 1-4 decision per 100 commit (sekitar 1-4%).

Untuk entri changelog, batasnya lebih rendah: setiap perubahan yang terlihat pengguna (fitur, perbaikan, peningkatan) akan dicatat. Chore internal, pembaruan dokumentasi, dan refactor biasanya dilewati. Tingkat khas kami: 30-50 entri changelog per 100 commit.

Penyimpanan Data: Ledger Append-Only

Sistem mining menggunakan ledger JSONL append-only untuk operasi multi-agen yang bebas konflik:

packages/orchestration/ai_assets/reference/changelog/
├── commits_processed.jsonl  # Classification ledger (both domains)
├── release_notes.jsonl      # Changelog entries
└── commits_index.yaml       # Derived index (gitignored)

packages/orchestration/ai_assets/reference/decisions/
├── registry.yaml            # Decision index
└── records/
    ├── DEC-AD-001.yaml
    ├── DEC-AD-002.yaml
    └── ...

Format JSONL dengan merge=union dalam .gitattributes berarti beberapa agen bisa mengklasifikasikan commit secara bersamaan tanpa merge conflict. Setiap baris berdiri sendiri.

Validation Gate

Sebelum sesi mining apa pun, kami menjalankan validasi:

uv run orkestra mine validate --quick

Ini memeriksa:

• Validitas format SHA
• Kepatuhan format ID decision
• Tidak ada entri duplikat untuk SHA yang sama
• Decision yang dirujuk benar-benar ada

Setelah klasifikasi, kami memvalidasi lagi sebelum melakukan commit perubahan.

Mengapa Ini Penting

Feedback loop yang kami bangun memecahkan beberapa masalah:

Untuk anggota tim baru: Alih-alih bertanya “kenapa kita melakukan X?”, mereka bisa mencari di registry decision. Konteksnya terjaga.

Untuk agen AI: Mereka tidak beroperasi dalam ruang hampa. Mereka bisa meng-query pengetahuan institusional sebelum membuat rekomendasi. Ketika diminta menambahkan stage pipeline baru, mereka bisa menemukan pola DuckDB dan mengikutinya.

Untuk konsistensi arsitektural: Decision bersifat eksplisit dan bisa dicari. Ketika seseorang mengusulkan pendekatan yang bertentangan dengan decision yang sudah ada, sistem bisa memunculkan konfliknya.

Untuk pembuatan changelog: Release note bukan lagi kepanikan menit terakhir. Mereka adalah produk sampingan dari klasifikasi berkelanjutan selama pengembangan.

Untuk onboarding: Agen baru mewarisi seluruh konteks basis kode. Mereka tidak sekadar melihat kode — mereka melihat decision yang membentuknya.

Keadaan Saat Ini

Per hari ini:

• 15.637 commit diproses lewat pipeline
• 476 architectural decision diekstraksi dan didokumentasikan
• 6.799 entri changelog tercatat
• Cakupan 100% di kedua domain

Setiap commit sejak kami mulai sudah terklasifikasi. Memori institusionalnya lengkap dan bisa di-query.

Memulai

Jika Anda ingin mengimplementasikan sesuatu yang serupa:

1. Mulai dengan conventional commit. Pipeline mining bekerja paling baik ketika commit punya prefix terstruktur (feat:, fix:, chore:).

2. Definisikan domain Anda. Kami menggunakan domain seperti pipeline, agent-design, observability, data-modeling. Ini mengorganisasi decision berdasarkan area.

3. Bangun kebiasaan klasifikasi. Mining berjalan baik ketika tim secara rutin mengklasifikasikan commit. Pemrosesan batch dengan bantuan LLM membantu penskalaan.

4. Buat decision bisa di-query. Nilainya berlipat ganda ketika agen bisa mencari decision lewat CLI. Strukturkan output Anda untuk konsumsi mesin.

5. Tutup loop-nya. Decision seharusnya memengaruhi pekerjaan mendatang. Sertakan referensi decision dalam instruksi agen dan checklist code review.

Tujuannya bukan dokumentasi yang sempurna. Ini soal membuat alasan di balik perubahan bisa diakses oleh manusia maupun AI, hari ini dan enam bulan dari sekarang. Ketika perubahan menjadi memori institusional, tim membangun di atas pola yang sudah mapan, bukan menciptakannya ulang.

---

Mining workflow adalah bagian dari orchestration engine kami, khususnya modul context engine dalam package orchestration kami.