---
name: discovery-requirements
description: Lifecycle'ın "A"sı — INVEST user story, acceptance criteria (Gherkin Given/When/Then), assumption tracking, NFR (latency/availability/scale), non-goal tanımı, risk + open question. Kod öncesi disipline.
---

# Discovery & Requirements

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

- **Kod yazmadan netleş.** "Ben halletmeyi düşünüyorum" yerine **yazılı**
  user story + acceptance criteria.
- **Assumption explicit**. "Tahmin ettiğimiz" şey listelenir; doğrulama planı.
- **Non-goal eşit önemde**. Neyi yapmıyoruz? Scope creep'i baştan kapat.
- **NFR (non-functional requirement) ayrı**. Latency/availability/scale/security
  fonksiyonel olmayan ama **kritik**.
- **Iteratif > big design upfront**. INVEST: Independent / Negotiable /
  Valuable / Estimable / Small / Testable.

## Ne Zaman Kullanılır
- Yeni feature başlangıç (kod yazılmadan)
- Customer / stakeholder isteği belirsiz
- "Refactor" istediği gerçekte feature olduğunda (scope tartışma)
- Sprint planning öncesi (estimable hâle getir)
- Teknik borç → epic dönüştürme
- Migration / rewrite (legacy → new) scope
- Compliance feature (GDPR DSR, audit log, vs.)

## Workflow

### 1) Stakeholder + persona
- **Asıl talep eden** kim? Product / customer / engineering / compliance?
- **Persona** (kullanıcı tipi): admin, end-user, integrator, support agent, ...
- **Sahiplik**: hangi ekip? cross-team mi?

### 2) Problem statement
**1 paragraf, kullanıcı dilinde**:
```text
[Persona] [bağlam'da] [problemini yaşıyor]; mevcut çözüm [eksik/yavaş/yok].
Etkisi: [iş etkisi — sayı + birim].
Çözünce kazanç: [metric'e dökülmüş ROI].
```

Örnek:
> Admin kullanıcı, müşteri itirazını çözerken son 90 günlük order history'i
> görmek istiyor; mevcut tool 7 gün gösteriyor (legacy DB cap). Etkisi:
> Support ticket'i %12 oranında "veri eksik" sebebiyle tier-2'ye yükseliyor.
> 90 gün ile bu yükseltmenin %80'i tier-1'de kapanacak (T-2/ay 240 ticket
> azalır → ~$4800/ay support cost düşüş).

### 3) User stories (INVEST)

```text
As [persona], I want [capability] so that [benefit].
```

INVEST kriterleri:
- **Independent**: diğer story'den bağımsız teslim edilebilir.
- **Negotiable**: implementation detayı esnek.
- **Valuable**: kullanıcıya / işe değer.
- **Estimable**: ekibin tahmin edebileceği boyut.
- **Small**: 1 sprint'ten kısa.
- **Testable**: acceptance criteria yazılabilir.

Slice'lar:
- **Vertical slice** (DB → backend → frontend) tek story; full feature değil.
- **Tracer bullet**: ilk slice end-to-end "happy path" (gerçek dummy data).
- **Sequence**: Plugin `vertical-slice-planner` agent'ı bu kararı verir.

### 4) Acceptance criteria (Gherkin)

```gherkin
Feature: Admin order history (90-day)
  As admin
  I want 90-day order history
  So that I resolve customer disputes faster

  Scenario: Admin opens customer order history
    Given admin authenticated with `read:orders` scope
    And customer "C-12345" has 47 orders in last 90 days
    When admin requests `GET /admin/customers/C-12345/orders?days=90`
    Then response status 200
    And response includes 47 orders
    And each order has fields: id, created_at, total, status
    And response time p99 < 500ms

  Scenario: Customer with no orders in 90 days
    Given customer "C-99999" has no orders in last 90 days
    When admin requests `GET /admin/customers/C-99999/orders?days=90`
    Then response status 200
    And response.orders == []

  Scenario: Beyond 90 days requested
    Given admin authenticated
    When admin requests `?days=120`
    Then response status 400
    And response.error == "max 90 days"

  Scenario: Insufficient permission
    Given user authenticated with `read:profile` scope only
    When user requests `GET /admin/customers/C-12345/orders`
    Then response status 403
```

**Kurallar:**
- Her scenario **bir davranış**.
- Given = precondition; When = aksiyon; Then = beklenen.
- **Ölçülebilir** (status code, count, time).
- Edge case'ler ayrı scenario.

### 5) NFR (non-functional)

| Kategori | Hedef | Kanıt |
|---|---|---|
| **Latency** | p99 < 500ms | `/observe-bootstrap` SLO ile uyumlu |
| **Availability** | 99.9% / 30d rolling | error budget 43m 12s |
| **Throughput** | 100 RPS sustained, 500 RPS peak | `/capacity-plan` doğrulaması |
| **Scalability** | 10x kullanıcı 6 ayda | architecture review |
| **Security** | OAuth2 scope, audit log, PII redact | `/threat-model` + `/security-audit` |
| **Compliance** | GDPR Art. 32, SOC 2 CC6.1 | audit map |
| **Cost** | < $50/ay yeni infra | `/iac-review` cost diff |
| **Browser** | last 2 versions Chrome/Safari/Firefox | frontend bağı |
| **Accessibility** | WCAG 2.1 AA | a11y review |
| **i18n** | EN + TR (P0), DE (P2) | locale plan |

NFR **ölçülebilir**. "Hızlı" değil "p99 < 500ms".

### 6) Assumption + risk + open question

**Assumption** = "doğru sayıyoruz ama doğrulanmamış":
```markdown
- A1: Order history 90 gün için yeterli (legal 6 ay tutuyor; UI ihtiyacı 90 ile sınırlı varsayıldı).
  - Doğrulama: data team query 6 ay vs 90 gün support ticket overlap.
- A2: Admin bu endpoint'i support tool dışından kullanmıyor.
  - Doğrulama: API gateway log, son 30 gün caller.
```

**Risk** = "kötü gidebilir":
```markdown
- R1: 90-gün scan slow query — index zorunlu (`idx_orders_customer_created`).
- R2: PII expose risk — admin scope yeterli mi? `/threat-model` delege.
```

**Open question** = "henüz cevabı yok":
```markdown
- Q1: Pagination cursor mu offset mi? → @api-team karar (örnek 14 cursor önerir)
- Q2: 90 gün overlap ile partial export var mı? → @data-team (UI vs CSV export ayrı story)
```

### 7) Non-goals

```markdown
- **Order detail view**: bu story sadece liste; detay ayrı endpoint zaten var.
- **CSV export**: ayrı story (S-4567).
- **Real-time push**: bu story polling; WS ayrı.
- **Multi-currency**: sadece TRY ilk sürüm.
- **Customer-facing endpoint**: admin-only; customer self-service ayrı epic.
```

Non-goal **scope creep'i kapatır**. Stakeholder "bunu da ekleyelim" derse → ayrı story.

### 8) Definition of Done (DoD)

```markdown
- [ ] Tüm acceptance criteria pass
- [ ] Unit + integration test (coverage staged > 70%)
- [ ] Contract test (OpenAPI schema validated)
- [ ] NFR doğrulandı (latency, availability — `/capacity-plan`)
- [ ] Security review (`/threat-model` veya `/security-audit`)
- [ ] Observability: SLO metric + alert + runbook
- [ ] Documentation: API doc + changelog
- [ ] Feature flag default off
- [ ] Rollback test edildi (drill)
- [ ] PR review APPROVE (kanıt — `agents/shared/severity-rubric.md`)
```

### 9) Dependency + sequencing

```text
Story 1: DB migration (idx_orders_customer_created)
   ↓ (merge önce)
Story 2: Backend endpoint `GET /admin/customers/:id/orders`
   ↓
Story 3: Frontend admin tool integration
   ↓ (parallel)
Story 4: Audit log + PII redact (security)
```

Plugin `vertical-slice-planner` agent'ı dependency graph'ı çıkarır;
`coordination.md` §2 paralel implementer kuralı uygular.

### 10) Estimation

- **Story points** (Fibonacci 1/2/3/5/8/13) — relative.
- **8+ → split**. Tek sprint'i geçemez.
- **13 = epic** — alt story'lere bölünmesi şart.
- **0 = no work** (sadece spec / discovery).
- T-shirt size (S/M/L/XL) takım tercihiyse OK.

## Checklist
- [ ] Stakeholder + persona belirgin
- [ ] Problem statement ROI dahil
- [ ] User story INVEST geçer
- [ ] Acceptance criteria Gherkin (≥ 3 scenario, edge dahil)
- [ ] NFR ölçülebilir (latency, availability, security, cost)
- [ ] Assumption listesi + doğrulama planı
- [ ] Risk listesi + mitigation
- [ ] Open question + sahip
- [ ] Non-goal listesi (scope creep önle)
- [ ] DoD checkbox listesi
- [ ] Dependency graph + slice sıralama
- [ ] Estimation (≤ 8 points; aksi halde split)
- [ ] Yayın: discovery doc + linked PR/issue

## Antipattern
- **"Sonra düşünürüz"** — kod yazılırken çıkan sorular discovery yetersizliği işareti.
- **NFR yok** — "hızlı, güvenilir, scale" olmalı; ölçü yok = test edilemez.
- **Acceptance criteria belirsiz** — "kullanıcı dostu" testable değil.
- **Non-goal yok** — scope creep garanti.
- **Assumption yazılı değil** — yanlış varsayım sessizce ilerler.
- **Tek scenario happy path** — edge + error path eksik.
- **Estimation yok** — sprint planning'de tahmin yapılır → yanlış.
- **13+ point story** — split etme şart.
- **Customer + internal birlikte** tek story — ayrı persona ayrı release.
- **"Sadece UI değişikliği"** — backend API impact, security, NFR ihmal.
- **Migration story = "legacy'i new'e geçir"** — slice'lara böl, big bang yasak.
- **Compliance feature ad-hoc** — explicit control map (SOC 2 / GDPR).

## Örnek Agent Davranışı
```
User: /discovery admin order history 90 days
Agent (product-domain-analyst):
1. Stakeholder: support ekibi → product → engineering.
2. Persona: support agent (admin role).
3. Problem statement: tier-2 escalation %12; 90 gün ile tier-1 close %80 → support cost düşüş.
4. User story: "As admin, I want 90-day order history so that I resolve disputes faster".
5. Acceptance criteria: 5 Gherkin scenario (happy + empty + max + insufficient perm + slow query timeout).
6. NFR:
   - p99 < 500ms (SLO ile uyumlu)
   - PII redact admin log
   - GDPR Art. 32
7. Assumption:
   - A1: 90 gün UI ihtiyacı yeterli (data team doğrula).
   - A2: admin scope yeterli (security-reviewer doğrula).
8. Risk: R1 slow query → DB index. R2 PII expose → audit log.
9. Open question: Q1 cursor pagination, Q2 CSV export ayrı story.
10. Non-goal: detail view, CSV export, real-time, multi-currency, customer-facing.
11. DoD: 10 madde checklist.
12. Estimation: 5 story (DB index 1 + backend 3 + frontend 5 + security 2 + observability 2).
13. Output: `docs/discovery/admin-90day-order-history.md` + 5 GitHub issue.
```

## Çıktı Formatı
```markdown
# Discovery: <feature>

## Stakeholder + Persona
## Problem Statement (ROI dahil)
## User Stories (INVEST)
## Acceptance Criteria (Gherkin)
## NFR
| Kategori | Hedef | Kanıt |

## Assumption
## Risk + Mitigation
## Open Question + Sahip
## Non-Goals
## Definition of Done
## Dependency + Sequencing
## Estimation
| Story | Points | Sahip |

## Linked Issues
- #N — story 1
- ...
```