Mining the Loop: Paano Nagiging Institutional Memory ang mga Pagbabago

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Pebrero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Parehong hamon ang hinaharap ng bawat engineering team: patuloy na nangyayari ang mga pagbabago, pero nawawala ang bakit sa likod ng mga pagbabagong iyon. Anim na buwan pagkatapos, may magtatanong ng “bakit namin pinili ang DuckDB para sa mga pipeline stage?” at ang sagot, nasa ulo lang ng taong gumawa ng desisyong iyon—kung nandiyan pa siya.

Gumawa kami ng mining workflow na nagsasara ng loop na ito. Dumadaloy ang mga pagbabago sa pamamagitan ng git commits, pino-proseso ng mining pipeline namin, nagiging structured changelog entries at architectural decision records, tapos pinapakain pabalik sa mga AI agent namin sa pamamagitan ng CLI queries. Ang resulta: institutional memory na puwedeng i-access ng parehong tao at AI.

Ang Problema: Nawawala ang mga Desisyon

Isipin ang isang karaniwang senaryo. May kina-commit ang isang developer:

feat(canonical): add DuckDB runtime for pipeline stages

Kumakatawan ang commit na ito sa isang makabuluhang architectural choice. Sinuri ng team ang mga opsyon, isinaalang-alang ang mga trade-off, at napunta sa DuckDB dahil sa mga specific na dahilan. Pero lahat ng context na iyon, nakatira sa:

• Isang Slack thread (malamang burado na)
• Alaala ng isang tao (siguradong nawawala na)
• Isang comment sa code (baka, kung maswerte ka)

Tatlong buwan pagkatapos, may magtatanong na bagong miyembro ng team: “Dapat ba akong gumamit ng DuckDB o SQLite para sa bagong stage na ito?” Kung walang institutional memory, uulitin nila ang wheel o gagawa ng hindi magkatugmang mga pagpili.

Ang Loop: Mula sa Commits Papunta sa Context

Ginagawang queryable knowledge ng mining workflow namin ang git history:

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)     │
      └───────────────┘

Ang key insight: parehong nagmumula ang changelogs at architectural decisions sa parehong git history, na pinoproseso sa pamamagitan ng iisang unified pipeline. Sinisiguro nito na walang mahuhulog sa mga bitak.

Paano Gumagana ang Mining

Hakbang 1: I-sync ang Index

uv run orkestra mine sync

Sini-scan ng command na ito ang git history at gumagawa ng index ng lahat ng commit. Kinukuha nito ang structured signals mula sa bawat commit:

• Conventional commit type (feat, fix, chore, docs)
• Scope (aling package o area)
• Mga marker ng breaking change
• Mga file na nagalaw at complexity metrics

Hakbang 2: I-check ang Coverage Status

uv run orkestra mine status

Ganito ang itsura ng kasalukuyang status namin:

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 commits ang naproseso. 476 ang naging architectural decisions. 6,799 ang naging changelog entries. Nauri ang bawat commit.

Hakbang 3: Kumuha ng mga Candidate para sa Review

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

Ito ang naglalabas ng mga commit na hindi pa naproseso, kasama ng buong context para sa classification:

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}
}

Tumutulong ang mga signal sa pag-guide ng classification: iminumungkahi ng is_releasable_type: true na dapat lumitaw ito sa changelog. Iminumungkahi naman ng malaking insertion count at mga infrastructure file na puwede rin itong maging architectural decision.

Hakbang 4: I-classify ang mga Commit

Dalawang landas ang nagkakahiwalay dito: changelog entries at architectural decisions.

Para sa changelog entries:

uv run orkestra mine classify abc123 --changelog added

Naitatala nito na dapat lumitaw ang commit na abc123 sa changelog sa ilalim ng kategoryang “Added.”

Para sa architectural decisions:

Una, kumuha ng tunay na decision ID:

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

Tapos i-classify gamit ang decision ID:

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

Nag-uugnay ito sa commit sa isang decision record na gagawin o iu-update.

Para sa batch processing (ang talagang ginagawa namin):

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

Sinusuportahan ng JSONL format ang parehong domain sa isang pass:

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"}

Hakbang 5: I-render ang mga Output

uv run orkestra changelog render --package <pkg>

Nagbubunga ito ng mga per-package na file na CHANGELOG.md mula sa ledger. Ang mga changelog, derived artifacts—burahin mo sila at magre-regenerate sila nang perpekto mula sa source ledger.

Ang Structure ng Decision Record

Nagiging mga YAML file na may mayamang metadata ang mga na-extract na decision:

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

Bawat decision, may link pabalik sa source commits nito. Bawat decision, tinutukoy kung aling mga file ang naaapektuhan nito. Explicit ang mga relationship sa pagitan ng mga decision.

CLI Integration: Pagqu-query ng Institutional Memory

Dito nagsasara ang loop. Puwedeng mag-query ng mga decision ang mga agent sa pamamagitan ng CLI:

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

Nagbabalik ng mga decision tungkol sa retry logic, error handling, recovery patterns.

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

Nagbabalik ng kumpletong decision record na may context, rationale, at impact.

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

Ipinapakita kung anong mga architectural choice ang ginawa kamakailan.

Paano Ginagamit Ito ng mga Agent

Kasama sa baseline instructions ng orchestrator namin:

**Essential CLI commands:**
- `orkestra decisions search "X"` — Find architectural decisions

Kapag hiniling sa isang agent na mag-implement ng may kinalaman sa DuckDB, puwede muna itong mag-check:

uv run orkestra decisions search --query "DuckDB"

At matuklasan ang DEC-PL-142, matutunan ang:

• Bakit pinili ang DuckDB (context)
• Paano ito gamitin nang tama (agent_guidance)
• Aling mga file ang titingnan (files)
• Anong mga related na decision ang umiiral (related)

Hindi na uulitin ng agent ang wheel. Bubuo ito sa itinatag nang mga pattern.

Ang Three Questions Test

Hindi karapat-dapat ang bawat commit sa isang decision record. Ginagamit namin ang Three Questions Test para i-filter:

1. Mahirap ba itong gawin? Kailangan ba ito ng makabuluhang analysis, trade-off evaluation, o debate?
2. Mahal bang baguhin? Kailangan ba ng makabuluhang rework para baligtarin ang desisyong ito?
3. May system-wide na epekto ba ito? Naaapektuhan ba nito ang maraming package o nagtatatag ba ito ng mga pattern na susundin ng iba?

Kung “oo” ang sagot ng isang commit sa kahit isa sa mga tanong na ito, isa itong candidate para sa decision extraction. Ang karaniwang rate namin: 1-4 na decision kada 100 commit (mga 1-4%).

Para sa changelog entries, mas mababa ang bar: naitatala ang anumang user-facing na pagbabago (features, fixes, improvements). Karaniwang nili-skip ang internal chores, documentation updates, at refactors. Ang karaniwang rate namin: 30-50 na changelog entry kada 100 commit.

Pag-imbak ng data: append-only na ledger

Gumagamit ang mining system ng append-only JSONL ledgers para sa conflict-free na multi-agent operation:

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
    └── ...

Ang JSONL format na may merge=union sa .gitattributes, ibig sabihin, puwedeng mag-classify ng mga commit ang maraming agent nang sabay-sabay nang walang merge conflicts. Independent ang bawat linya.

Mga gate ng validation

Bago ang anumang mining session, nagpapatakbo kami ng validation:

uv run orkestra mine validate --quick

Sini-check nito:

• Bisa ng SHA format
• Pagsunod sa decision ID format
• Walang duplicate entries para sa parehong SHA
• Talagang umiiral ang mga na-reference na decision

Pagkatapos ng classification, nagva-validate kami ulit bago mag-commit ng mga pagbabago.

Bakit Mahalaga Ito

Sinolusyunan ng feedback loop na ginawa namin ang ilang problema:

Para sa mga bagong miyembro ng team: Sa halip na magtanong ng “bakit namin ginawa ang X?”, puwede nilang i-search ang decisions registry. Napapanatili ang context.

Para sa mga AI agent: Hindi sila nagtatrabaho sa isang vacuum. Puwede nilang i-query ang institutional knowledge bago gumawa ng mga rekomendasyon. Kapag hiniling na magdagdag ng bagong pipeline stage, puwede nilang matuklasan ang DuckDB pattern at sundan ito.

Para sa architectural consistency: Explicit at searchable ang mga desisyon. Kapag may nagmumungkahi ng approach na sumasalungat sa umiiral nang desisyon, puwedeng ilabas ng system ang conflict.

Para sa changelog generation: Hindi last-minute na pagmamadali ang release notes. Byproduct sila ng patuloy na classification habang nagde-develop.

Para sa onboarding: Namamana ng mga bagong agent ang buong context ng codebase. Hindi lang nila nakikita ang code—nakikita rin nila ang mga desisyon na humubog dito.

Kasalukuyang Estado

Sa ngayon:

• 15,637 commits ang naproseso sa pipeline
• 476 na architectural decision ang na-extract at na-dokumento
• 6,799 changelog entries ang naitala
• 100% coverage sa parehong domain

Nauri ang bawat commit mula nang magsimula kami. Kumpleto at queryable ang institutional memory.

Pagsisimula

Kung gusto mong mag-implement ng katulad nito:

1. Magsimula sa conventional commits. Pinakamahusay gumana ang mining pipeline kapag may structured prefix ang mga commit (feat:, fix:, chore:).

2. I-define ang mga domain mo. Gumagamit kami ng mga domain tulad ng pipeline, agent-design, observability, data-modeling. Ino-organisa nito ang mga desisyon ayon sa area.

3. Bumuo ng classification habit. Gumagana ang mining kapag regular na nagki-classify ng mga commit ang mga team. Nakakatulong sa pag-scale ang batch processing na may LLM assistance.

4. Gawing queryable ang mga desisyon. Tumataas ang value kapag puwedeng i-search ng mga agent ang mga desisyon sa pamamagitan ng CLI. I-structure ang output mo para sa machine consumption.

5. Isara ang loop. Dapat maimpluwensyahan ng mga desisyon ang hinaharap na trabaho. Isama ang mga decision reference sa agent instructions at code review checklists.

Hindi perpektong documentation ang layunin. Ang gawing accessible sa parehong tao at AI ang bakit sa likod ng mga pagbabago, ngayon at anim na buwan mula ngayon. Kapag naging institutional memory na ang mga pagbabago, bumubuo ang mga team sa itinatag nang mga pattern sa halip na ulitin ang mga ito.

---

Bahagi ng orchestration engine namin ang mining workflow, mismong ang context engine module sa orchestration package namin.