یہ کتاب کیسے بنائی گئی: تفصیل سے چلنے والی ترقی

🎯 چیلنج

ہیکاتھن کا مقصد: "Docusaurus کا استعمال کرتے ہوئے ایک کتاب لکھیں اور اسے GitHub Pages پر Spec-Kit Plus اور Claude Code کے ذریعے ڈیپلوئی کریں۔"

یہ درسی کتاب صرف روبوٹکس کے بارے میں نہیں ہے—یہ فزیکل اے آئی سے چلنے والی، تفصیل سے چلنے والی مواد کی تخلیق کا زندہ مظاہرہ ہے۔ آپ جو بھی باب پڑھتے ہیں وہ ایک ہی دہرائے جانے والے کام کے عمل کے مطابق منظم طور پر تیار کیا گیا تھا۔

---

🔄 کام کا عمل

graph LR
    A[/sp.specify] --> B[spec.md]
    B --> C[/sp.plan]
    C --> D[plan.md + ADRs]
    D --> E[/sp.tasks]
    E --> F[tasks.md]
    F --> G[/sp.implement]
    G --> H[Content + PHRs]
    H --> I{Quality Check}
    I -->|Pass| J[Deploy]
    I -->|Fail| A

    style A fill:#4CAF50
    style C fill:#2196F3
    style E fill:#FF9800
    style G fill:#9C27B0
    style J fill:#4CAF50

ہر باب اس چار مرحلہ عمل کی پیروی کرتا ہے:

1. تفصیل (/sp.specify)

ان پٹ: قدرتی زبان کی خصوصیت کی تفصیل آؤٹ پٹ: spec.md میں منظم ضروریات کے ساتھ

مثال:

/sp.specify "Create Chapter 2: ROS 2 Fundamentals covering pub/sub, services, actions, and transforms"

کیا ہوتا ہے:

• خصوصیت کی تفصیل کا تجزیہ کرتا ہے
• صارف کی کہانیاں تیار کرتا ہے (مثلاً، US-P1: Pub/Sub Lab, US-P2: Services & Actions)
• فعال ضروریات کی تعریف کرتا ہے (FR-001 سے FR-008 تک)
• ہر ضرورت کے لیے قبولیت کے معیار تیار کرتا ہے
• منظم specs/002-ros2-fundamentals/spec.md کا آؤٹ پٹ دیتا ہے

مثال آؤٹ پٹ (View Chapter 2 Spec):

## User Stories
- **US-P1**: As a student, I want hands-on pub/sub labs...
- **US-P2**: As a student, I want service/action examples...

## Functional Requirements
- **FR-001**: Provide learning objectives (5 measurable)
- **FR-002**: Explain ROS 2 graph architecture...

---

2. منصوبہ بندی (/sp.plan)

ان پٹ: spec.md آؤٹ پٹ: plan.md + Architecture Decision Records (ADRs)

مثال:

/sp.plan  # Runs in feature branch after spec is approved

کیا ہوتا ہے:

• تکنیکی ضروریات کا تجزیہ کرتا ہے
• معماری کے فیصلے کرتا ہے (مثلاً، "Python کے لیے Black formatter کا استعمال")
• ڈیزائن کے آرٹیفیکٹس (ڈایاگرامز، ڈیٹا ماڈلز) تیار کرتا ہے
• اہم فیصلوں کے لیے ADRs تیار کرتا ہے
• specs/002-ros2-fundamentals/plan.md کا آؤٹ پٹ دیتا ہے

ADR تجویز (منصوبہ بندی کے دوران ہوتا ہے):

📋 Architectural decision detected: ROS 2 Humble as primary distribution
   Document reasoning and tradeoffs? Run `/sp.adr ros2-humble-selection`

تیار کردہ مثال ADRs:

• ADR-001: Docusaurus for Textbook Delivery
• ADR-002: GitHub Pages Deployment Strategy

مثال آؤٹ پٹ (View Chapter 2 Plan):

## Architecture Decisions
1. Use Gazebo Classic 11+ for simulation (stability over features)
2. Black formatter with line length 100 (ROS 2 community standard)
3. Google-style docstrings (clarity for students)

---

3. ٹاسک جنریشن (/sp.tasks)

ان پٹ: spec.md + plan.md آؤٹ پٹ: tasks.md میں ترتیب سے ٹاسک کی تعمیل کے ساتھ

مثال:

/sp.tasks  # After plan is reviewed and approved

کیا ہوتا ہے:

• منصوبہ کو عملی ٹاسک میں توڑتا ہے
• ٹاسک کو انحصار کے لحاظ سے ترتیب دیتا ہے (مرحلہ 1: ترتیب → مرحلہ 2: بنیاد → ...)
• متوازی ٹاسک کو [P] کے ساتھ نشان زد کرتا ہے
• فائل پاتھ اور قبولیت کے معیار شامل کرتا ہے
• specs/002-ros2-fundamentals/tasks.md کا آؤٹ پٹ دیتا ہے (باب 2 کے لیے 65 ٹاسک!)

مثال آؤٹ پٹ (View Chapter 2 Tasks):

## Phase 1: Setup
- [ ] T001 Create directory: chapters/02-ros2-fundamentals/
- [ ] T002 Create subdirectories: assets/, assessments/, lab-01-pubsub/

## Phase 2: Foundation
- [ ] T005 Write learning objectives (5 from spec FR-001-008)
- [ ] T007 [P] Write conceptual overview: ROS 2 graph architecture

## Phase 3: Lab P1 - Pub/Sub
- [ ] T016 **publisher_node.py** (~50 lines, publishes IMU at 50Hz)
- [ ] T017 **subscriber_node.py** (~40 lines, logs messages)

---

4. عمل درآمد (/sp.implement)

ان پٹ: tasks.md آؤٹ پٹ: اصل مواد (markdown, کوڈ, ڈایاگرامز) + Prompt History Records (PHRs)

مثال:

/sp.implement  # Executes tasks systematically

کیا ہوتا ہے:

• ٹاسک کو انحصار کے ترتیب میں عمل کرتا ہے
• فائلیں تیار کرتا ہے (README.md, Python کوڈ, ڈایاگرامز)
• قبولیت کے معیار کے خلاف تصدیق کرتا ہے
• ہر قدم کی دستاویزی تاریخ PHRs میں تیار کرتا ہے
• حقیقی وقت میں ٹاسک کو مکمل کے طور پر نشان زد کرتا ہے

Prompt History Records (PHRs) خود بخود تیار کیے جاتے ہیں:

• مقام: history/prompts/<feature-name>/
• فارمیٹ: <ID>-<slug>.<stage>.prompt.md
• شامل ہے: صارف کی ان پٹ، اے آئی کا جواب، تبدیل شدہ فائلیں، نتیجہ

مثال PHRs (View All PHRs):

history/prompts/002-ros2-fundamentals/
├── 001-create-ros2-fundamentals-spec.spec.prompt.md
├── 002-create-ros2-fundamentals-plan.plan.prompt.md
├── 003-create-ros2-fundamentals-tasks.tasks.prompt.md
└── 004-implement-ros2-fundamentals-foundation.implement.prompt.md

مثال عمل درآمد آؤٹ پٹ:

• chapters/02-ros2-fundamentals/README.md
• chapters/02-ros2-fundamentals/assets/glossary.md
• ڈایاگرامز، کوئزز، ٹربل شوٹنگ گائیڈز

---

📋 کوالٹی کنٹرول: آئین

ہر مواد کی توثیق آئین (View Full Constitution) کے خلاف کی جاتی ہے۔

اہم اصول:

1. جسمانیت-پہلے: ہر تصور جسمانی حدود سے جڑا ہوتا ہے
2. سم-ٹو-ریل تسلسل: سمولیشن اور ڈیپلائمنٹ کو ایک پائپ لائن کے طور پر دیکھا جاتا ہے
3. سسٹمز انٹیگریشن: عبوری مسائل کو حل کیا جاتا ہے (ادراک → منصوبہ بندی → کنٹرول)
4. ٹولچین شفافیت: تمام ورژنز کو لاک اور دستاویزی کیا جاتا ہے
5. عمل کے ذریعے تشخیص: قبولیت ٹیسٹوں کے ساتھ ترسیلی آرٹیفیکٹس
6. اخلاقی غور و فکر: حفاظت، رازداری، تعصب جہاں موزوں ہو وہاں پر غور کیا جاتا ہے

پری-پبلیکیشن چیک لسٹ (سب کو پاس کرنا ضروری ہے):

• سیکھنے کے مقاصد پیمائش کے قابل ہیں
• کوڈ کی مثالیں Ubuntu 22.04 + ROS 2 Humble پر ٹیسٹ کی گئیں
• ٹربل شوٹنگ گائیڈ میں ≥5 عام غلطیاں ہیں
• بصری امداد موجود ہے (ڈایاگرامز، کوڈ بلاکس)
• پڑھنے کی سطح مناسب ہے (تکنیکی لیکن قابل رسائی)

---

🎯 اس کی اہمیت کیوں ہے

روایتی کتاب لکھنا

Idea → Draft → Edit → Review → Publish
   ↑_________________________________|
        (repeat until "good enough")

مسائل:

• ❌ کوئی آڈٹ ٹریل نہیں (فیصلہ X کیوں کیا گیا؟)
• ❌ تعاون کرنا مشکل (کس نے کیا کیا؟)
• ❌ معیار میں ناہمواری (مختلف ابواب، مختلف معیار)
• ❌ دہرائے جانے کے قابل نہیں (عمل کو دوبارہ تخلیق نہیں کر سکتے)

تفصیل سے چلنے والی کتاب کی تخلیق

Specify → Plan → Tasks → Implement → Validate
   │        │       │         │          │
   ↓        ↓       ↓         ↓          ↓
spec.md   plan.md  tasks.md  content    PHRs
   │        │                   │
   └────────┴──→ ADRs ←─────────┘

فوائد:

• ✅ دہرائے جانے کے قابل: نئے ابواب کے لیے ایک ہی /sp.* کمانڈز کی پیروی کریں
• ✅ آڈٹ کے قابل: PHRs ہر فیصلہ اور تبدیلی کو قید کرتے ہیں
• ✅ تعاونی: شراکت دار ایک ہی منظم کام کے عمل کی پیروی کرتے ہیں
• ✅ کوالٹی-کنٹرولڈ: آئین معیار کو یقینی بناتا ہے
• ✅ شفاف: ADRs معماری کے انتخابات کی وضاحت کرتے ہیں
• ✅ موثر: اے آئی گرنٹ کام کو سنبھالتا ہے، انسان حکمت عملی فراہم کرتے ہیں

یہ صرف ایک درسی کتاب نہیں ہے—یہ فزیکل اے آئی سے چلنے والی مواد کی تخلیق کا نقشہ ہے۔

---

🚀 اگلے مراحل

• مزید جانیں: View PHR Gallery مکمل تاریخ دیکھنے کے لیے
• فیصلے سمجھیں: Browse ADRs معماری کے انتخابات کے لیے
• کوالٹی معیار دیکھیں: Read Constitution مواد کے قوانین کے لیے
• سیکھنا شروع کریں: Begin Chapter 1 →

---

بنایا گیا استعمال کرتے ہوئے Spec-Kit Plus + Claude Code + Docusaurus