लूप की माइनिंग: बदलाव संस्थागत स्मृति कैसे बनते हैं

इस पोस्ट में दिए गए आंकड़े प्रकाशन के समय (फ़रवरी 2026) की सिस्टम स्थिति दर्शाते हैं। मौजूदा आंकड़ों के लिए हमारा टीम पेज देखें।

हर इंजीनियरिंग टीम एक ही चुनौती का सामना करती है: बदलाव लगातार होते रहते हैं, लेकिन उन बदलावों के पीछे का क्यों ग़ायब हो जाता है। छह महीने बाद, कोई पूछता है “हमने पाइपलाइन स्टेज के लिए DuckDB क्यों अपनाया था?” और जवाब सिर्फ़ उस इंसान के दिमाग़ में रहता है जिसने वह फ़ैसला लिया था — अगर वह अब भी मौजूद है तो।

हमने एक माइनिंग वर्कफ़्लो बनाया जो इस लूप को बंद करता है। बदलाव git कमिट के ज़रिए बहते हैं, हमारी माइनिंग पाइपलाइन से प्रोसेस होते हैं, संरचित चेंजलॉग एंट्री और आर्किटेक्चरल डिसीज़न रिकॉर्ड बन जाते हैं, और फिर CLI क्वेरी के ज़रिए वापस हमारे AI एजेंट में फ़ीड हो जाते हैं। नतीजा: संस्थागत स्मृति जिसे इंसान और AI, दोनों एक्सेस कर सकते हैं।

समस्या: फ़ैसले वाष्पित हो जाते हैं

एक सामान्य परिदृश्य पर विचार करें। एक डेवलपर कमिट करता है:

feat(canonical): add DuckDB runtime for pipeline stages

यह कमिट एक महत्वपूर्ण आर्किटेक्चरल चुनाव दर्शाता है। टीम ने विकल्पों का मूल्यांकन किया, ट्रेड-ऑफ़ पर विचार किया, और विशिष्ट कारणों से DuckDB पर पहुंची। लेकिन वह सारा कॉन्टेक्स्ट यहां रहता है:

• एक Slack थ्रेड (शायद डिलीट हो चुका)
• किसी की याददाश्त (निश्चित रूप से धुंधली पड़ रही)
• कोड में एक कमेंट (शायद, अगर आप ख़ुशक़िस्मत हैं)

तीन महीने बाद, एक नया टीम मेंबर पूछता है: “क्या मुझे इस नए स्टेज के लिए DuckDB या SQLite इस्तेमाल करना चाहिए?” संस्थागत स्मृति के बिना, वे या तो पहिया फिर से बना लेते हैं, या असंगत चुनाव कर बैठते हैं।

लूप: कमिट से कॉन्टेक्स्ट तक

हमारा माइनिंग वर्कफ़्लो git इतिहास को क्वेरी करने योग्य ज्ञान में बदल देता है:

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

मुख्य इनसाइट: चेंजलॉग और आर्किटेक्चरल डिसीज़न, दोनों उसी git इतिहास से बहते हैं, एक एकीकृत पाइपलाइन से प्रोसेस होकर। इससे यह सुनिश्चित होता है कि कुछ भी दरार से छूटे नहीं।

माइनिंग कैसे काम करती है

चरण 1: इंडेक्स सिंक करें

uv run orkestra mine sync

यह कमांड git इतिहास स्कैन करता है और सभी कमिट का एक इंडेक्स बनाता है। यह हर कमिट से संरचित सिग्नल एक्सट्रैक्ट करता है:

• कन्वेंशनल कमिट टाइप (feat, fix, chore, docs)
• स्कोप (कौन-सा पैकेज या क्षेत्र)
• ब्रेकिंग चेंज मार्कर
• छुई गई फ़ाइलें और जटिलता मेट्रिक्स

चरण 2: कवरेज स्टेटस जांचें

uv run orkestra mine status

हमारी मौजूदा स्थिति कुछ ऐसी दिखती है:

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 कमिट प्रोसेस किए गए। 476 आर्किटेक्चरल डिसीज़न बने। 6,799 चेंजलॉग एंट्री बनीं। हर कमिट वर्गीकृत।

चरण 3: समीक्षा के लिए उम्मीदवार पाएं

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

यह उन कमिट को सामने लाता है जो अब तक प्रोसेस नहीं हुए, वर्गीकरण के लिए पूरे कॉन्टेक्स्ट के साथ:

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

सिग्नल वर्गीकरण में मार्गदर्शन करते हैं: is_releasable_type: true बताता है कि इसे चेंजलॉग में दिखना चाहिए। बड़ी इंसर्शन काउंट और इन्फ़्रास्ट्रक्चर फ़ाइलें बताती हैं कि यह एक आर्किटेक्चरल डिसीज़न भी हो सकता है।

चरण 4: कमिट वर्गीकृत करें

यहां दो रास्ते अलग हो जाते हैं: चेंजलॉग एंट्री और आर्किटेक्चरल डिसीज़न।

चेंजलॉग एंट्री के लिए:

uv run orkestra mine classify abc123 --changelog added

यह दर्ज करता है कि कमिट abc123 को चेंजलॉग में “Added” श्रेणी के अंतर्गत दिखना चाहिए।

आर्किटेक्चरल डिसीज़न के लिए:

पहले, एक असली डिसीज़न ID पाएं:

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

फिर डिसीज़न ID के साथ वर्गीकृत करें:

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

यह कमिट को एक डिसीज़न रिकॉर्ड से जोड़ता है जो बनाया या अपडेट किया जाएगा।

बैच प्रोसेसिंग के लिए (जो हम वास्तव में करते हैं):

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

JSONL फ़ॉर्मैट एक ही पास में दोनों डोमेन को सपोर्ट करता है:

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

चरण 5: आउटपुट रेंडर करें

uv run orkestra changelog render --package <pkg>

यह लेजर से प्रति-पैकेज CHANGELOG.md फ़ाइलें जनरेट करता है। चेंजलॉग व्युत्पन्न आर्टिफ़ैक्ट हैं — उन्हें डिलीट करें और वे सोर्स लेजर से बिल्कुल सही ढंग से दोबारा बन जाते हैं।

डिसीज़न रिकॉर्ड की संरचना

एक्सट्रैक्ट किए गए डिसीज़न समृद्ध मेटाडेटा वाली YAML फ़ाइलें बन जाते हैं:

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

हर डिसीज़न वापस अपने सोर्स कमिट से जुड़ता है। हर डिसीज़न बताता है कि वह किन फ़ाइलों को प्रभावित करता है। डिसीज़न के बीच रिलेशनशिप स्पष्ट होती हैं।

CLI इंटीग्रेशन: संस्थागत स्मृति को क्वेरी करना

यहीं पर लूप बंद होता है। एजेंट CLI के ज़रिए डिसीज़न क्वेरी कर सकते हैं:

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

रीट्राई लॉजिक, एरर हैंडलिंग, रिकवरी पैटर्न के बारे में डिसीज़न लौटाता है।

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

कॉन्टेक्स्ट, तर्क, और प्रभाव के साथ पूरा डिसीज़न रिकॉर्ड लौटाता है।

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

दिखाता है कि हाल में कौन-से आर्किटेक्चरल चुनाव किए गए।

एजेंट इसका उपयोग कैसे करते हैं

हमारे ऑर्केस्ट्रेटर के बेसलाइन निर्देशों में शामिल है:

**Essential CLI commands:**

- `orkestra decisions search "X"` — Find architectural decisions

जब किसी एजेंट से DuckDB से जुड़ी कोई चीज़ इम्प्लीमेंट करने के लिए कहा जाता है, तो वह पहले यह जांच सकता है:

uv run orkestra decisions search --query "DuckDB"

और DEC-PL-142 खोज सकता है, यह सीखते हुए:

• हमने DuckDB क्यों चुना (context)
• इसका सही उपयोग कैसे करें (agent_guidance)
• किन फ़ाइलों को देखना है (files)
• कौन-से संबंधित डिसीज़न मौजूद हैं (related)

एजेंट पहिया फिर से नहीं बनाता। यह स्थापित पैटर्न पर आगे बढ़ता है।

तीन सवालों का टेस्ट

हर कमिट को डिसीज़न रिकॉर्ड की ज़रूरत नहीं होती। हम फ़िल्टर करने के लिए तीन सवालों के टेस्ट का उपयोग करते हैं:

1. क्या यह बनाना मुश्किल था? क्या इसके लिए महत्वपूर्ण विश्लेषण, ट्रेड-ऑफ़ मूल्यांकन, या बहस ज़रूरी थी?
2. क्या इसे बदलना महंगा है? क्या इस फ़ैसले को पलटने के लिए बड़े पैमाने पर दोबारा काम करना पड़ेगा?
3. क्या इसका सिस्टम-व्यापी प्रभाव है? क्या यह कई पैकेज को प्रभावित करता है या ऐसे पैटर्न स्थापित करता है जिनका दूसरे अनुसरण करेंगे?

अगर कोई कमिट इनमें से कम-से-कम एक सवाल का जवाब “हां” में देता है, तो यह डिसीज़न एक्सट्रैक्शन का उम्मीदवार है। हमारी सामान्य दर: प्रति 100 कमिट पर 1-4 डिसीज़न (लगभग 1-4%)।

चेंजलॉग एंट्री के लिए, मानदंड कम है: कोई भी उपयोगकर्ता-सामने वाला बदलाव (फ़ीचर, फ़िक्स, सुधार) दर्ज किया जाता है। आंतरिक रखरखाव कार्य, डॉक्यूमेंटेशन अपडेट, और रीफ़ैक्टर आमतौर पर छोड़ दिए जाते हैं। हमारी सामान्य दर: प्रति 100 कमिट पर 30-50 चेंजलॉग एंट्री।

डेटा स्टोरेज: एपेंड-ओनली लेजर

माइनिंग सिस्टम टकराव-मुक्त मल्टी-एजेंट ऑपरेशन के लिए एपेंड-ओनली JSONL लेजर का उपयोग करता है:

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

merge=union वाले .gitattributes के साथ JSONL फ़ॉर्मैट का मतलब है कि कई एजेंट मर्ज कॉन्फ़्लिक्ट के बिना एक साथ कमिट वर्गीकृत कर सकते हैं। हर लाइन स्वतंत्र है।

वैलिडेशन गेट

किसी भी माइनिंग सेशन से पहले, हम वैलिडेशन चलाते हैं:

uv run orkestra mine validate --quick

यह जांचता है:

• SHA फ़ॉर्मैट की वैधता
• डिसीज़न ID फ़ॉर्मैट अनुपालन
• एक ही SHA के लिए कोई डुप्लिकेट एंट्री नहीं
• रेफ़रेंस किए गए डिसीज़न वास्तव में मौजूद हैं

वर्गीकरण के बाद, हम बदलाव कमिट करने से पहले दोबारा वैलिडेट करते हैं।

यह क्यों मायने रखता है

हमने जो फ़ीडबैक लूप बनाया है, वह कई समस्याएं सुलझाता है:

नए टीम मेंबर के लिए: “हमने X क्यों किया?” पूछने के बजाय, वे डिसीज़न रजिस्ट्री सर्च कर सकते हैं। कॉन्टेक्स्ट सुरक्षित रहता है।

AI एजेंट के लिए: वे किसी शून्य में काम नहीं करते। वे सिफ़ारिशें करने से पहले संस्थागत ज्ञान क्वेरी कर सकते हैं। जब उनसे कोई नया पाइपलाइन स्टेज जोड़ने के लिए कहा जाता है, तो वे DuckDB पैटर्न खोज सकते हैं और उसका पालन कर सकते हैं।

आर्किटेक्चरल संगति के लिए: डिसीज़न स्पष्ट और सर्च करने योग्य हैं। जब कोई ऐसा अप्रोच प्रस्तावित करता है जो किसी मौजूदा डिसीज़न के विरुद्ध जाता है, तो सिस्टम उस टकराव को सामने ला सकता है।

चेंजलॉग जनरेशन के लिए: रिलीज़ नोट्स आख़िरी पल की भागदौड़ नहीं हैं। वे डेवलपमेंट के दौरान लगातार वर्गीकरण का एक उपोत्पाद हैं।

ऑनबोर्डिंग के लिए: नए एजेंट कोडबेस का पूरा कॉन्टेक्स्ट विरासत में पाते हैं। वे सिर्फ़ कोड नहीं देखते — वे उन डिसीज़न को देखते हैं जिन्होंने उसे आकार दिया।

मौजूदा स्थिति

आज तक:

• पाइपलाइन के ज़रिए 15,637 कमिट प्रोसेस किए गए
• 476 आर्किटेक्चरल डिसीज़न एक्सट्रैक्ट और दस्तावेज़ीकृत किए गए
• 6,799 चेंजलॉग एंट्री दर्ज की गईं
• दोनों डोमेन में 100% कवरेज

हमारे शुरू करने के बाद से हर कमिट वर्गीकृत किया जा चुका है। संस्थागत स्मृति पूर्ण और क्वेरी करने योग्य है।

शुरुआत कैसे करें

अगर आप कुछ ऐसा ही इम्प्लीमेंट करना चाहते हैं:

1. कन्वेंशनल कमिट से शुरू करें। माइनिंग पाइपलाइन तब सबसे अच्छा काम करती है जब कमिट में संरचित प्रीफ़िक्स हों (feat:, fix:, chore:)।

2. अपने डोमेन परिभाषित करें। हम pipeline, agent-design, observability, data-modeling जैसे डोमेन का उपयोग करते हैं। ये डिसीज़न को क्षेत्र के हिसाब से व्यवस्थित करते हैं।

3. वर्गीकरण की आदत बनाएं। माइनिंग तब काम करती है जब टीमें नियमित रूप से कमिट वर्गीकृत करती हैं। LLM सहायता के साथ बैच प्रोसेसिंग स्केल करने में मदद करती है।

4. डिसीज़न को क्वेरी करने योग्य बनाएं। जब एजेंट CLI के ज़रिए डिसीज़न सर्च कर सकते हैं, तो मूल्य कई गुना बढ़ जाता है। अपने आउटपुट को मशीन-उपभोग के लिए संरचित करें।

5. लूप बंद करें। डिसीज़न को भविष्य के काम को प्रभावित करना चाहिए। एजेंट निर्देशों और कोड समीक्षा चेकलिस्ट में डिसीज़न रेफ़रेंस शामिल करें।

लक्ष्य मुकम्मल डॉक्यूमेंटेशन नहीं है। यह बदलावों के पीछे के क्यों को इंसानों और AI, दोनों के लिए सुलभ बनाना है, आज भी और आज से छह महीने बाद भी। जब बदलाव संस्थागत स्मृति बन जाते हैं, तो टीमें उन्हें दोबारा गढ़ने के बजाय स्थापित पैटर्न पर आगे बढ़ती हैं।

---

माइनिंग वर्कफ़्लो हमारे ऑर्केस्ट्रेशन इंजन का हिस्सा है, ख़ासतौर पर हमारे ऑर्केस्ट्रेशन पैकेज में मौजूद कॉन्टेक्स्ट इंजन मॉड्यूल का।