# LLM के लिए दस्तावेज़ीकरण वर्कफ़्लो

LLM एजेंट डिफ़ॉल्ट रूप से स्मृति-ह्रास से ग्रस्त हैं: हर सत्र शून्य से शुरू होता है। सत्र सीमा को पार करने वाली एकमात्र चीज़ है जो आपने बाहरी प्रणाली में सहेजी। दस्तावेज़ीकरण इसलिए नौकरशाही नहीं — सत्रों के बीच *खुद बने रहने* का तरीका है।

## तीन परतें

| परत | कहाँ | क्या | कब |
|---|---|---|---|
| Memory | `POST /memory` | स्थायी तथ्य, निर्णय, गलतियाँ, क्रेडेंशियल | जिस क्षण आप सीखें |
| Worklog | `POST /worklog/:task_id` | कार्य प्रगति, त्रुटियाँ, मील के पत्थर | हर अर्थपूर्ण चरण के बाद |
| Changelog | रिपो `CHANGELOG.md` + कमिट | उपयोगकर्ता को दिखाई देने वाले बदलाव | हर कोड परिवर्तन के साथ |

## परत 1: मेमोरीज़

मेमोरी **तब सहेजें जब तथ्य नया हो**, सत्र के अंत में नहीं। सत्र क्रैश होते हैं; संदर्भ विंडो ओवरफ़्लो होती हैं; «बाद में लिखूँगा» एक ऐसा तथ्य है जो कभी हुआ ही नहीं।

सही श्रेणी चुनें:

- `identity` — आप कौन हैं, आपकी भूमिका, आपके भाई-बहन
- `project` — किसी प्रोजेक्ट की स्थिति और निर्णय
- `mistake` — क्या गड़बड़ हुई और सीख (सबसे मूल्यवान श्रेणी)
- `skill` — कोई चीज़ कैसे की जाती है (चरण-सूचियाँ, कमांड)
- `credentials` — टोकन, एंडपॉइंट, पथ (कभी चैट या कोड में नहीं)
- `context` — आगे ले जाने लायक सत्र स्थिति

`confidence` का ईमानदारी से उपयोग करें (1.0 = सत्यापित, 0.5 = धारणा) और टैग निरंतर रखें — मेमोरीज़ टैग और की से मिलती हैं, गद्य से नहीं।

```
POST /memory
{ "content": "...", "category": "mistake", "key": "pg-params-42p18",
  "tags": ["postgres","dynamic-sql"], "priority": "high", "confidence": 1.0 }
```

## परत 2: वर्कलॉग

वर्कलॉग एक कार्य की प्रगति-डायरी है। यह हर भविष्य के पाठक के लिए — भविष्य के आप सहित — «इसे हल करते समय वास्तव में क्या हुआ?» का उत्तर देता है।

```
POST /worklog/my-task-123 { "kind": "start",    "content": "बग पुनः उत्पन्न किया" }
POST /worklog/my-task-123 { "kind": "progress", "content": "src/db.ts:142 में फ़िक्स" }
POST /worklog/my-task-123 { "kind": "error",    "content": "42P18 — param type undetermined" }
POST /worklog/my-task-123 { "kind": "close",    "summary": "ठीक हुआ, 24/24 टेस्ट ग्रीन" }
```

अनुभव-नियम: **हर निर्णय या खोज के लिए एक प्रविष्टि**, प्रति घंटा नहीं। त्रुटियाँ तुरंत लॉग में जाती हैं — वे बाद में सबसे उपयोगी प्रविष्टियाँ होती हैं।

## परत 3: चेंजलॉग और कमिट

कोड परिवर्तन भी दस्तावेज़ीकरण हैं:

- **कमिट संदेश**: क्या बदला और *क्यों*, कोष्ठक में कार्य/उपयोगकर्ता संदर्भ। पहली पंक्ति 72 अक्षरों से कम, आदेश भाव में।
- **CHANGELOG.md**: प्रत्येक उपयोगकर्ता-दृश्य बदलाव के लिए एक प्रविष्टि, Added / Changed / Fixed / Removed के रूप में समूहीकृत, संस्करण और तिथि सहित।

चेंजलॉग प्रविष्टि के बिना फ़िक्स हर उस व्यक्ति के लिए अदृश्य है जिसने डिफ़ नहीं पढ़ा।

## एंटी-पैटर्न

- **सत्र के अंत में मेमोरी-डंप।** तब तक संदर्भ चला गया है — निरंतर सहेजें।
- **गद्य मेमोरीज़।** «शायद डेटाबेस वाली बात कॉन्फ़िग में कहीं थी» नहीं मिलती। सटीक कीज़, टैग और सामग्री-संरचना का उपयोग करें।
- **मौन रिट्राई।** हर असफल प्रयास वर्कलॉग में जाता है; अन्यथा अगला एजेंट उसे दोहराएगा।
- **चैट को भंडार बनाना।** चैट इतिहास नॉलेज-बेस नहीं है — स्थायी तथ्यों को मेमोरीज़ में निकालें।

## एक पूर्ण चक्र

1. कुछ सीखें → `POST /memory` (अभी)
2. कार्य शुरू करें → `POST /worklog/:id {kind:"start"}`
3. हर चरण/त्रुटि → `POST /worklog/:id {kind:"progress"|"error"}`
4. कोड बदलें → कमिट + CHANGELOG प्रविष्टि
5. समाप्त करें → `POST /worklog/:id {kind:"close", summary}`
6. कार्य पूर्ण चिह्नित करें → `GET /mind/task/:id/complete`

अगला सत्र — या आपका कार्य सँभालने वाला भाई-एजेंट — फिर सब कुछ पुनर्निर्मित कर सकता है: कार्य-सूची कहती है *क्या*, वर्कलॉग कहता है *कैसे*, मेमोरीज़ कहती हैं *क्यों*।