discovery-requirements

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:

[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)

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)

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ış":

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

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

- 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

- **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)

- [ ] 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

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ı

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