epic-orchestration

Epic Orchestration

Ortak Doktrin

agents/shared/severity-rubric.md ve agents/shared/escalation-matrix.md default-load sayılır (agents/coordination.md §11). Bu skill'in çıktısı Critical / High / Medium / Low + kanıt formatında olmak zorunda — spekülatif Critical yasak. Sahiplik dışı bulgu ilgili agent'a delege; karar yetkisi eşiği aşılırsa kullanıcı onayı zorunlu.

Felsefe

• Epic ≠ büyük story. Multi-team + multi-sprint + dependency.
• Vertical slice mandatory. Backend bitti, frontend bekler yasak.
• Critical path görünür. DB → Backend → Frontend zinciri açık + parallel fırsatları işaretli.
• Multi-agent assignment her slice'a explicit lider + destek + review.
• Cross-team blocker mediator epic-orchestrator (passive değil proaktif).
• Weekly burndown + ETA refresh stakeholder'a transparency.
• Epic close kriteri yazılı; "Done" tanımı belirsizliği yok.

Ne Zaman Kullanılır

• Discovery sonrası epic ≥ 13 point.
• ≥ 2 sprint süresi.
• ≥ 3 ekip dahil (DB + Backend + Frontend + Infra + Security minimum).
• Migration / refactor large-scale.
• Compliance-driven (SOC 2 gap closure).
• Major feature launch + observability + GTM.
• Cross-quarter initiative.

Workflow

1) Discovery + scope alıntı

• docs/discovery/<feature>.md zaten yazılı (önce /discovery koştu).
• Toplam point + user story sayısı + acceptance criteria + NFR.
• Stakeholder map: sponsor + PM + eng lead + cross-team.
• Hedef tarih: campaign / release / compliance deadline.

Eşik:

• Point ≥ 13 → epic.
• Sprint ≥ 2 → epic.
• Ekip ≥ 3 → epic.

2) Slice decomposition (vertical-slice-planner delege)

Slice kuralları:

• INVEST geçer.
• 1-5 point (8+ → split).
• Vertical (DB → Backend → Frontend → Infra hepsi içinde).
• Tek başına ship'lenebilir.
• Test'lenebilir.

Çıktı:

| Slice | Konu | Point | Vertical katmanlar |
| S1 | DB migration | 3 | DB |
| S2 | Backend endpoint | 5 | Backend + DB read |
| S3 | Email notification | 3 | Backend + 3rd party |
| S4 | Frontend form | 5 | Frontend + Backend integration |
| S5 | Security hardening | 3 | Backend + audit log |
| S6 | Observability | 2 | Infra + monitoring |
| S7 | UAT + release | 2 | Cross-cutting |

3) Dependency graph

ASCII veya Mermaid:

graph TD
  S1[S1: DB migration] --> S2[S2: Backend]
  S1 --> S5[S5: Security]
  S2 --> S3[S3: Email]
  S2 --> S4[S4: Frontend]
  S2 --> S6[S6: Observability]
  S3 --> S7[S7: UAT]
  S4 --> S7
  S5 --> S7
  S6 --> S7

Critical path: en uzun zincir. Bu örnek: S1 → S2 → S4 → S7. Parallel fırsat: S5, S6 critical path dışı.

4) Multi-agent assignment

Her slice için:

• Lider (1): kararı alan + sahip.
• Destek (0-3): kanıt + impl katkı.
• Review (1-2): bağımsız ses, APPROVE.

Plugin agent'ları (mevcut 46) — agents/CAPABILITY_MATRIX.md referans (madde 11 ile gelecek).

Tipik dağılım:

Slice tipi	Lider	Destek	Review
DB	database-implementer	database-optimizer, migration-planner	infrastructure-reviewer, security-reviewer
Backend (REST)	backend-implementer	api-contract-guardian, test-engineer	code-reviewer, security-reviewer
Backend (gRPC/WS)	backend-implementer + realtime-implementer	api-contract-guardian	realtime-systems-reviewer
Frontend	frontend-implementer	frontend-performance-auditor, test-engineer	frontend-reviewer, code-reviewer
Mobile (gelecek M18)	mobile-engineer (yeni)	—	frontend-reviewer
Infra (K8s/Helm)	infrastructure-implementer	iac-engineer, platform-engineer	infrastructure-reviewer
IaC (Terraform)	iac-engineer	infrastructure-implementer	infrastructure-reviewer, security-reviewer
Security	security-reviewer	api-contract-guardian, dependency-risk-auditor	architecture-reviewer
Observability	observability-engineer	runbook-author	production-readiness-reviewer
Release	release-manager	deployment-strategist, migration-planner	—
Migration	migration-planner	database-implementer, release-manager	architecture-reviewer
UAT	test-engineer	unit/integration/e2e-test-writer	—

5) Milestone + ETA

Sprint 1 (2026-05-12 → 05-23) — 8 pts kapasite
   S1 (3) + S2 başla (5) + S5 paralel (3 partial)
   Critical path progress: %33

Sprint 2 (2026-05-26 → 06-06) — 8 pts
   S2 finalize, S3 (3) + S4 başla (5 partial), S6 paralel (2)
   Critical path progress: %66

Sprint 3 (2026-06-09 → 06-20) — 7 pts
   S4 finalize, S7 (UAT + release)
   Critical path progress: %100
   Epic close: 2026-06-20

ETA range:

• Best case: tüm slice tahmin altında, no blocker → 2026-06-15.
• Likely: 2026-06-20 (planlı).
• Worst case: cross-team review delay + 1 risk materialize → 2026-07-01.

6) Cross-team blocker mediation

Tipik blocker pattern + mitigation:

Blocker	Sebep	Mitigation
DB schema bekletme	Backend S1'i bekliyor	S1 önce merge; backend backward compat layer
API contract bekletme	Frontend backend'i bekliyor	Mock server (Postman/Prism); api-contract-guardian onaylı schema
Infra latency	Helm chart yeni servis	Infra slice 1 ile paralel başlasın
Review SLA	24-72 saat APPROVE/block kuralı	Slack ping + escalation architecture-reviewer
Resource conflict	İki ekip aynı code path	Lider epic-orchestrator mediator; merge sırası kararı
Cross-region/account	IaC çoklu environment	iac-engineer ayrı slice; sequential apply

Eskalasyon (agents/shared/escalation-matrix.md):

• Lider blocker → epic-orchestrator mediation.
• Mediator çözmediyse → architecture-reviewer.
• Mimari değil operational → incident-commander style.
• Hâlâ çözülmemiş → kullanıcı onayı.

7) Weekly burndown + reporting

Her hafta:

• Velocity: actual vs planned point.
• Burndown chart: sprint kalan / epic kalan.
• Blocker: count + age + sahip.
• Risk: discovery'deki risk'ler hâlâ geçerli mi?
• Open question: yeni soru çıkarsa eskalasyon.
• ETA refresh: critical path slip > %15 ise stakeholder notify.

Format: docs/epics/<epic>/status-YYYY-MM-DD.md + Slack özet.

8) Epic close

Checklist:

• Tüm slice ship (production).
• Acceptance criteria pass (Gherkin → automated test).
• NFR doğrulandı (latency p99 / availability SLO / security threat model / cost projection).
• Observability live (SLO + multi-window alert + runbook).
• Release notes (/release-plan çağrılmış) + CHANGELOG entry.
• Bug bash + UAT sign-off.
• Customer / stakeholder communication (status page / email).
• Postmortem mini (T+30 gün retro: ne iyi gitti, ne iyileştirilebilir).
• Tribal knowledge handover (/onboard doc update + ADR ekle).
• Epic doc archive (docs/epics/<epic>/closed.md + retro link).

Checklist

• Discovery doc oku, point ≥ 13 doğrulandı
• Slice decomposition (vertical-slice-planner)
• Dependency graph + critical path
• Multi-agent assignment tablosu (lider+destek+review)
• Milestone + ETA range (best/likely/worst)
• Cross-team blocker mediator plan
• Weekly burndown + stakeholder report cadence
• Epic close kriteri (DoD)
• Risk register + mitigation
• GitHub project board + issue link

Antipattern

• Epic = sprint backlog tamamı — ayrı disiplin gerekli.
• Tek agent epic'i koşar — multi-team paralel orkestrasyonu.
• Slice 8+ point — split şart.
• Critical path görmezden — DB migration paralele alma.
• Blocker passive — mediator proaktif çöz.
• ETA tek nokta — range zorunlu.
• Epic close kriteri yok — DoD belirsiz scope creep.
• Postmortem yok (epic ≠ incident ama retro şart).
• Cross-team review SLA yok — 24-72h hedef.
• Stakeholder reporting yok — haftalık burndown + Slack.
• Discovery atla — epic önce /discovery zorunlu.
• /release-plan atla — major epic = release entry.

Örnek Agent Davranışı

User: /epic-plan customer-password-reset
Agent (epic-orchestrator):
1. /discovery çıktısı oku: 23 points, 4 story, 6 Gherkin scenario.
2. Eşik geç: 23 ≥ 13 → epic.
3. vertical-slice-planner delege → 7 slice listesi.
4. Dependency graph (Mermaid).
5. Critical path: S1→S2→S4→S7 = 3 sprint.
6. Multi-agent: 7 lider + 14 destek/review (12 agent unique).
7. Milestone: Sprint 1-3 (2026-05-12 → 06-20).
8. ETA range: 06-15 / 06-20 / 07-01.
9. Risk: SendGrid rate limit, auth scope expansion, frontend SDK upgrade.
10. Output: docs/epics/customer-password-reset/plan.md + Mermaid graph +
    GitHub project board (12 issue + cross-team label).
11. Weekly burndown: docs/epics/customer-password-reset/status-YYYY-MM-DD.md
12. Cross-team review SLA: 24h APPROVE/block; Slack #epic-passwordreset.

Çıktı Formatı

# Epic: <epic-name>

## Discovery Summary
- Points + Stories + Stakeholders + Deadline

## Slice Decomposition
| Slice | Konu | Point | Vertical |

## Dependency Graph (Mermaid)

## Critical Path + ETA Range

## Multi-Agent Assignment
| Slice | Lider | Destek | Review |

## Milestone Plan
| Sprint | Slices | Capacity |

## Risk + Mitigation

## Blocker Mediation Plan

## Weekly Burndown Cadence

## Epic Close Criteria (DoD)

## Linked Issues + Project Board