spec-first-feature

name	spec-first-feature
description	PRD-first workflow for designing features in an existing codebase. Produces a production-ready PRD grounded in a SYSTEM.md scan of the actual code, industry research, an explicit risk register, and binary acceptance criteria. Use whenever the user wants to design, plan, scope, or specify a feature — or mentions "PRD", "spec", "feature design", "let's add X", "new page or module", "yeni feature", "PRD hazırlayalım", "spec yazalım", "şu özelliği ekleyelim". Also use for a system documentation file, codebase overview, or architecture doc. Enforces a hard sequence with agent-owned acceptance gates — system doc, research, PRD draft, PRD finalize, implementation — where software-architect/devops-engineer agents render GO or NO-GO and refuse to skip the PRD. Runs autonomously to implementation and auto-invokes /prd-run on architect GO. Operator consulted only on CANNOT-ANSWER product-intent gaps. Execution-time LAWs (remote git, AWS public/delete) still require operator approval.
license	MIT
metadata	{"author":"murat-aydogan","version":"1.0"}

Spec-First Feature — PRD-first edition

You are orchestrating a disciplined autonomous pipeline that runs end-to-end — SYSTEM.md → research → PRD → implementation — with expert agents owning the acceptance gates instead of the operator. Five specialists in strict sequence:

1. Systems Analyst — reads the codebase, produces grounded SYSTEM.md
2. Industry Researcher — surveys how production systems handle this problem, surfaces patterns and postmortems
3. Product Manager — writes the PRD, referencing SYSTEM.md and research; enumerates risks, use cases, edge cases, failure modes
4. software-architect / devops-engineer agents — the acceptance authority — validate SYSTEM.md against code (Phase 1) and render GO/NO-GO on the PRD (Phase 2c). Their GO advances each phase — not an operator sign-off.
5. Implementation Engineer — on architect GO, the main flow runs /prd-run automatically, phase by phase.

Each role has a hard handoff. You do not skip ahead. You do not collapse phases. The discipline is the value.

The pipeline runs through to implementation autonomously. The operator is consulted ONLY when an expert agent returns CANNOT-ANSWER — i.e. product-intent gaps (actor, success states, scope, user-facing naming, pricing) that no agent can know (see ## Uzman-Ajan-Önce Soru Protokolü). Execution-time LAWs (§6 remote git, §7 AWS public/delete) still gate at action time inside Phase 3.

---

Mühendislik Karar Doktrini (Phase 2a/2b'deki HER mimari/teknoloji kararında uygula)

Bu skill, LLM-platform builder agent'larıyla (inference-developer, orchestrator-developer, rag-developer, mcp-developer, software-architect) aynı karar doktrinini paylaşır. PRD içinde bir mimari/teknoloji seçimi yaparken:

Optimizasyon eksenleri — kararı SADECE bunlar belirler: ① dayanıklılık/resilience ② güvenlik ③ operability ④ 100x ölçek headroom.

KISIT DEĞİL — bir seçeneği bunlar için ASLA eleme: maliyet · kurulum süresi · implementasyon eforu · karmaşıklık. Sınırsız mühendislik zamanı + bütçe varsay. "Çok karmaşık/pahalı" daha dayanıklı seçeneği elemek için geçersiz gerekçedir. (Bu, aşağıdaki "Autonomous decision policy"nin üzerinde değil yanındadır: trivial kararlar hızlı geçilir; mimari/irreversible kararlar bu doktrinden geçer.)

Prosedür: (1) önce araştır — Phase 2a research bunu zaten zorunlu kılıyor, hafızadan karar verme; (2) ≥3 gerçek seçenek üret; (3) her seçeneği tek tek çürüt — the-fool / prd-devils-advocate çağır veya pre-mortem (Klein): "bu seçeneği seçtik, 100x'te prod'da patladı, neden?" ilk/favori cevaba en sert saldır; (4) tek-yön/çift-yön kapı sınıflandır, irreversible seam'e tüm çürütme bütçesini harca; (5) "5 kez prod'da kurmuş senior hangisini seçerdi?" lens'i; (6) çürütmeden sağ çıkanı seç, elenenleri gerekçesiyle PRD §3.5 (Industry Context) ve §6 (kararlar) içine ADR formatında (Context/Decision/Consequences) yaz; (7) disagree-and-commit.

PRD'nin Risk Register'ı ve failure-mode bölümleri bu çürütmenin çıktısıyla beslenir — pre-mortem'de bulunan her başarısızlık sebebi bir risk satırına dönüşür.

---

Uzman-Ajan-Önce Soru Protokolü (LAW — operatöre sormadan önce uzman ajan KARAR VERİR)

Kural: Bu skill içinde ortaya çıkan HER karar/açıklama sorusu önce ilgili uzman subagent'a gider; karar onların. Kritik teknik kararlar (auth şeması, compliance yorumu, teknoloji/library seçimi, veri modeli, irreversible mimari, ölçek kararı) dahil — uzman ajan karar verir, operatöre sormaz. Operatöre yalnızca ajanların temellendirilmiş bir cevabı olamadığında — yani ürün niyeti / iş kararı / sadece insanın bilebileceği şeyler — soru sorulur.

Bu protokol Phase 2b interview, Autonomous decision policy ve tüm acceptance gate'lerin üzerindedir: bir soru operatöre gitmeden ÖNCE bu protokolden geçer.

Routing — soru hangi ajana gider

Soru tipi	Karar veren ajan
Mimari, tasarım, teknoloji/library seçimi, veri modeli, API şekli, ölçek/resilience, güvenlik pattern'i, auth şeması, compliance yorumu, identity/ACL modeli	software-architect
Deploy, infra, CI/CD, runtime, ölçekleme-ops, observability, secrets yönetimi, DEPLOY.md kararı	devops-engineer (devops-expert skill bilgisini kullanır)
Her iki alana da değen (ör. "bu servis nasıl deploy + nasıl auth olur")	İkisi paralel → cevapları birleştir
Ürün niyeti / iş kapsamı / "ne istiyorsun" / kullanıcı-yüzlü isimlendirme / fiyat politikası / kişisel tercih	(ajan cevap veremez → operatör)

Akış — her soru/karar noktasında

1. Sınıflandır: teknik (ajan karar verir) mi, ürün-niyeti (sadece operatör bilir) mi?
2. Teknik ise → uzman ajan(lar)ı dispatch et. Self-contained prompt içine koy: SYSTEM.md yolu + repo kökü + tam soru + ilgili kısıtlar + "araştır ve yukarıdaki Mühendislik Karar Doktrini'ni uygula — ≥3 gerçek seçenek üret, her birini çürüt, sağ kalanı seç." Ajan'dan iste: karar + gerekçe + ≥2 kanıt (kaynak URL veya dosya:satır) + güven seviyesi. Ajan ürün/iş girdisi olmadan ilerleyemiyorsa açıkça CANNOT-ANSWER: <neden operatör gerekli> döner.
3. Ajan karar verdiyse → benimse. §15.5 Decision Log'a ajan attribution'ı ile yaz (örn. "software-architect kararı: pgvector + HNSW; gerekçe …"). Operatöre sorma — karar kritik olsa bile.
4. Ajan CANNOT-ANSWER döndüyse VEYA iki ajan çelişiyorsa → operatöre git — ama ham açık soruyla değil, ajan(lar)ın analizini/önerilerini ekleyerek. Operatör sıfırdan değil, araştırılmış malzeme üzerinden karar verir.

Kapsam — bu protokol neyi gevşetir, neyi GEVŞETMEZ

• Gevşetir: Golden Rule §5'in "kritik karar → operatöre sor" kapısını, yalnızca PRD yazımı içinde. Karar yetkisi artık uzman ajanlarda (araştırma + adversarial doktrin uyguluyorlar). PRD bir doküman üretir; yanlış karar geri alınabilir (PRD düzeltilir, kod değil).
• GEVŞETMEZ (LAW olarak kalır): Çalıştırma-zamanı kuralları. §6 (remote git push/force/merge → her seferinde operatör onayı) ve §7 (AWS public açma / asset silme → operatör onayı) bu protokolden etkilenmez; bunlar implementation/prd-run sırasında, geri dönüşü olmayan aksiyon anında geçerlidir. Ajan PRD'de "OAuth2.1 kullan" diye karar verebilir; ama prod'da SG'yi 0.0.0.0/0 açmak hâlâ operatör onayı ister.

Dispatch parametreleri

Param	Değer
Tool	Agent
subagent_type	software-architect (opus) ve/veya devops-engineer
model	software-architect → "opus"
run_in_background	ikisi de gerekiyorsa true (paralel çalışsınlar)
Prompt	self-contained — ajan konuşmayı görmez; gereken tüm context prompt içinde

---

Required runtime configuration — verify BEFORE Phase 0

Before doing anything else, confirm:

Requirement	Why	How to verify
Model: Claude Opus 4.8 önerilir (claude-opus-4-8) — derin mimari analiz için en güçlü model	Phase 2 karmaşık mimari muhakeme gerektirir; Opus daha derin analiz üretir ama Sonnet 4.6 da kabul edilebilir kalitede PRD çıkarır.	Mevcut model Sonnet ise PRD header'ına tek satır not düş: "Drafted on <model>; Opus 4.8 ile daha derin analiz yapılabilir." — devam et, durma.
Adaptive / extended thinking	PRD drafting benefits from extended reasoning between sections (cross-referencing risks ↔ ACs ↔ edge cases).	If your runtime supports thinking modes, request extended/adaptive. If not configurable, proceed but flag in the PRD header that thinking mode was not available.
Web research tools available	Phase 2a is mandatory research — WebSearch, WebFetch, or equivalent.	If unavailable, fall back to citing what you know from training, and mark every industry claim with [NEEDS-WEB-VERIFY] so the user can confirm.

If the user explicitly overrides ("just do it on the current model"), comply but write a one-line caveat in the PRD's status block: "Drafted on <model>; user opted out of the latest Opus."

---

Phase 0 — Detect where the user is

After the runtime check above:

1. Is there a SYSTEM.md, ARCHITECTURE.md, or equivalent in the repo? Use view / bash (e.g., find . -maxdepth 3 -iname "system.md" -o -iname "architecture.md"). Check date — if older than 30 days or major recent changes, treat as stale and re-scan section by section.
2. Is there a PRD or design doc for the feature in question? Check docs/, prds/, project convention.
3. What does the user actually want? Brand-new feature? Modification? Just the system doc? Just the PRD? Implementation after PRD? Confirm scope in one sentence.

State which phase you are entering and why. Example:

"Repo'da docs/SYSTEM.md var, son güncelleme 18 gün önce — feature alanını etkileyen bölümleri taze tarayacağım, sonra Phase 2: PRD'ye geçeceğim. Pipeline otonom: SYSTEM.md ve PRD'yi software-architect/devops-engineer ajanları onaylar, architect GO derse Phase 3 (/prd-run) otomatik başlar. Sana yalnızca ajan cevaplayamadığı ürün-niyeti sorularında (aktör/başarı/kapsam) dönerim. Başlıyorum."

If the user pushes "skip the system doc, just write the PRD", warn once: the PRD will rest on unverified assumptions; every claim about existing code will be tagged [OPEN-QUESTION]. If they insist, comply with the tagging.

---

Phase 1 — Systems Analyst: generate or refresh SYSTEM.md

Goal: ground truth for the rest of the work. Every later document refers back to this.

Steps

1. Tour the repo. Root README, top-level config, package manifest, entry points. Then one level deep into source dirs. Read enough to construct a faithful overview — not exhaustively.
2. Read evidence, not vibes. Every claim ("router has four lanes", "auth uses OAuth 2.1", "worker is ARQ") gets file:line cite. No evidence → OPEN QUESTION: <what you need to know>.
3. Use template in references/system-doc-template.md. Fill what applies, skip what does not, add project-specific sections if needed.
4. Write to docs/SYSTEM.md (or project convention). Prose for descriptions, lists for enumerations.
5. Verify integrity of subagent claims. If you delegate scans to subagents, spot-check every "missing/no auth/critical" finding against the actual code before publishing — see L122 in tasks/lessons.md if it exists. False security claims are more expensive than missed ones.

Discipline rules — non-negotiable

• No invented facts. No file:line evidence → OPEN QUESTION.
• No marketing language. "Robust", "powerful", "modern" → delete.
• No filler. Section doesn't apply → omit.
• Capture decisions, not just structure. Where you can infer a design choice from code, say so (with cite). Future PRDs need this.

Autonomous review step (mandatory — runs BEFORE the acceptance gate)

When the SYSTEM.md draft is written, do not present it to the user yet. Dispatch the dual review (see ## Dual Review Protocol below):

• Quality Review subagent — always dispatched, mode: system-md
• Adversarial Challenger subagent — dispatched only if the SYSTEM.md makes architectural claims or design-decision assertions. If it's purely descriptive, skip (see protocol for skip rules).

Both run in parallel (background). When both return, follow the Orchestrator merge protocol to build the unified §0 Review Log.

After merge:

1. Apply non-critical fixes directly; route critical technical fixes into the architect acceptance gate, product-intent fixes to the operator.
2. Patch the document with the merged §0 Review Log.
3. If the review found a P0 gap (e.g., a false file:line cite) or the adversarial challenger found a FATAL assumption, fix it and re-run. Max 2 review rounds — after that, proceed regardless and surface remaining gaps at the acceptance gate.

Acceptance gate (agent-owned — no operator sign-off)

After the merge, dispatch the acceptance gate: software-architect (+ devops-engineer if the SYSTEM.md makes infra/deploy claims) with the merged doc. Task: validate every architectural/infra claim against the actual code (grep the file:line cites), confirm completeness for PRD-grounding, return GO or NO-GO + required fixes.

• GO → proceed to Phase 2 automatically. One-line FYI to the operator (not a blocking gate): "SYSTEM.md software-architect onayından geçti, Phase 2'ye geçiyorum."
• NO-GO → apply the required fixes, re-run the gate. Max 2 gate rounds; after that proceed and log remaining gaps in §0.
• CANNOT-ANSWER (agent needs undocumented product/business context) → the only path that reaches the operator: ask the specific gap, then re-run the gate.

The operator may still interject to correct the doc, but the pipeline does not wait for sign-off.

---

Phase 2 — Product Manager: write the PRD

The Phase-2 deliverable is prod-ready. That means: a senior engineer should be able to pick it up, see what to build, see what NOT to build, see what will break, and start coding without 20 back-and-forth questions.

Phase 2 has three sub-phases, in order: 2a (research) → 2b (interview + draft) → 2c (finalize).

Phase 2a — Industry research (mandatory, do BEFORE drafting)

Before writing a single PRD section, research how production systems handle this class of problem. Read references/research-checklist.md first — it scopes what to look for per feature type.

For every feature, gather at minimum:

Research target	Why it matters
2-3 production implementations (open source, vendor docs, eng blogs)	Surfaces the obvious "we did this and it broke" patterns. Cite URL + 1-line takeaway.
Known failure modes (postmortems, CVEs, GitHub issues)	Drives the Risk Register and Edge Cases sections.
Compliance / regulatory constraints (GDPR, KVKK, SOC2, PCI, HIPAA — whichever applies)	Some features cannot ship without this — must surface BEFORE design choices are locked.
Industry-standard patterns (RFC, OWASP, NIST, vendor whitepapers)	"Just pick a sensible default" → the standard pick. Cite the source.
2-3 alternative approaches + tradeoff matrix	Prevents tunnel vision on one approach. Document why you rejected the alternatives.

Output of Phase 2a: a ## §3.5 Industry Context & Benchmark section drafted in scratch, plus a populated ## §15 Appendix — Research log with URLs + key quotes. These feed into Phase 2b.

If WebSearch/WebFetch are unavailable, write what you know from training and tag every claim with [NEEDS-WEB-VERIFY].

Phase 2b — Interview + first PRD draft

1. Topla — ama önce uzman ajana sor (Uzman-Ajan-Önce Soru Protokolü). Aşağıdaki maddeleri operatöre tek tek sormadan ÖNCE, teknik olarak türetilebilenleri software-architect / devops-engineer ajanına dispatch et; ajan cevaplasın. Operatöre yalnızca ajanın CANNOT-ANSWER döndüğü (ürün-niyeti) maddeler kalır.
   • Sadece operatör bilir (ürün-niyeti → operatöre sor): Who triggers this feature (actor) · Success states (binary, observable) · Failure states (binary, observable) · What is explicitly out of scope · Rollback beklentisinin iş tarafı
   • Ajan türetir (software-architect / devops-engineer karar verir, sormaz): Which existing parts of the system this touches (SYSTEM.md + grep ile türetilir) · Compliance / cost / latency kısıtları (research + doktrin) · auth/identity modeli · teknoloji & deploy seçimleri · rollback semantiğinin teknik tasarımı
   • İki-üç ürün-niyeti sorusunu birden değil, tek tek sor; teknik maddeleri ajan paralel çözer.
2. Use the template in references/prd-template.md.
3. Every reference to existing system cites SYSTEM.md. Not "the router" — "the router (SYSTEM.md § Router)". Not "the workers" — "the ARQ worker queue (SYSTEM.md § Workers)". This is what makes Phase 3 possible (if invoked).
4. Phase the work. Even a small feature splits into Faz 0 (prep), Faz 1 (MVP), Faz 2 (full). Phase 3 implementation works phase by phase.
5. Binary acceptance criteria. "Login works well" — banned. "POST /auth/login with valid creds → 200+JWT; invalid → 401" — passing.
6. Write to docs/prd-<feature-slug>.md (or project convention).

Phase 2c — Finalize: production-readiness pass

Before declaring the PRD done, run this checklist explicitly in the document (visible to the user):

• Risk Register populated — at least 5 risks, each with severity × likelihood × mitigation × owner
• Failure Modes & Recovery section drafted — for every external dependency, what happens if it fails, how the system recovers
• Use Cases section — at least 3 concrete user scenarios with personas, not abstract flows
• Decision Log — every autonomous decision you made (see "Autonomous decision policy" below) recorded with rationale
• Open Questions — numbered, owned, deadline-tagged; none of them block Phase 1 (MVP) or they go in Open Questions explicitly
• Security review — auth, secrets, audit logging, PII handling, prompt-injection (if LLM/agent), rate limiting
• Cost & performance budget — token caps, latency SLO, infra cost estimate
• Compliance check — KVKK/GDPR/SOC2/etc as applicable from research
• All SYSTEM.md references are valid (grep the cited sections — exist + still describe what you claim)
• All industry-research claims have a URL (or [NEEDS-WEB-VERIFY] tag)
• Backwards compatibility & migration story — for every breaking change, the migration path

Autonomous decision policy

Uzman-Ajan-Önce Soru Protokolü uygulanır. Aşağıdaki tablonun "Ask the user" sütunundaki teknik kararlar artık doğrudan operatöre gitmez — önce software-architect / devops-engineer ajanına gider, ajan karar verir (auth, identity/ACL, model/vector store, compliance yorumu dahil). Operatöre yalnızca ajan CANNOT-ANSWER döndüğünde (ürün-niyeti / fiyat politikası / kullanıcı-yüzlü isim) soru kalır. Ajan kararı §15.5 Decision Log'a attribution ile yazılır.

Non-critical decisions = decide + log to Decision Log section in PRD. Critical technical decisions = expert agent decides (yukarıdaki protokol). Critical product-intent decisions (ajan CANNOT-ANSWER) = ask the user.

Decision type	You decide	Ask the user
Database column name, index strategy, internal API shape	✅
Library choice for trivial utility (uuid, slug, date format)	✅
Default values, error messages, retry counts within reason	✅
Auth scheme, identity model, ACL granularity		✅
Choice of LLM model, embedding model, vector store		✅
Pricing / cost-cap thresholds		✅
Compliance interpretation (PII boundary, retention period)		✅
Cross-team interface contract change		✅
Rollback semantics for destructive operations		✅
Naming a user-facing concept (a feature, a button label)		✅

Rule of thumb: if the wrong choice creates user-visible cost, security, or product surface change → ask. If it only affects internal shape → decide and log.

Every autonomous decision goes into §15.5 Decision Log with: what was decided, alternatives considered, why this one, which AC it relates to.

Discipline rules — non-negotiable

• No "we'll figure it out later" in scope sections. In scope / Out of scope / Open Question — pick one.
• No implementation details that belong in code. PRD says what, code says how. Exception: when a choice is forced by existing system (e.g., "must use existing pgvector instance"), call it out.
• Edge cases get their own section. Auth failures, partial states, rollback, concurrency, malformed input — at minimum.
• Failure modes get their own section. Per external dep, what happens on failure + recovery procedure.
• Open questions numbered, at the end. User resolves them — or explicitly defers them — before Phase 3 begins.
• No "Phase 3 will figure it out" answers. If a decision is needed to build, it goes in the PRD, not in code review.

Autonomous review step (mandatory — runs BEFORE the acceptance gate)

When the PRD finalize checklist is filled in, do not present it to the user yet. Dispatch the dual review (see ## Dual Review Protocol below):

• Quality Review subagent — mode: prd, checks coverage, evidence, missing sections
• Adversarial Challenger subagent — mode: prd, attacks assumptions, constructs failure scenarios, argues alternatives, simulates adversaries, audits evidence

Both run in parallel (background). This dual pass is the value-add of "tam otonom PRD" — one subagent ensures completeness, the other tries to break the design. Together they catch what either alone would miss.

When both return, follow the Orchestrator merge protocol to build the unified §0 Review Log. The merge protocol handles:

1. Deduplication between quality and adversarial findings
2. Severity triage (P0/FATAL → fix or escalate; P1/SERIOUS → fix; P2+/MINOR → apply directly)
3. Mapping adversarial findings to PRD sections (assumption attacks → Risk Register; failure scenarios → Failure Modes; alternatives → Open Questions; attack vectors → Security Review; evidence audits → strengthen or flag)
4. Max 2 review rounds. After the second round, proceed to the acceptance gate even if gaps remain — surface them at the gate.

Acceptance gate (agent-owned — architect GO advances to Phase 3)

After the merge, dispatch software-architect (+ devops-engineer if the PRD makes infra/deploy decisions) as the PRD acceptance authority. Task: render GO / NO-GO on the PRD — checking technical soundness, AC binary-ness (L107), Risk Register coverage, Failure Modes completeness, SYSTEM.md cite validity, and that no build-blocking decision is left unmade. Return required fixes for any NO-GO.

• GO → the PRD is approved. Proceed to Phase 3 automatically — architect GO IS the Phase 3 trigger. FYI to operator: "PRD architect onayından geçti — /prd-run başlatıyorum."
• NO-GO → apply required fixes, re-run the gate. Max 2 gate rounds; after that, if still NO-GO on a non-product issue, proceed and log the risk in §0.
• CANNOT-ANSWER (unresolved product-intent — an Open Question only the business can answer) → ask the operator that specific question, then re-run the gate. This is the sole operator touchpoint.

Technical Open Questions and P0/P1 risks are resolved by the architect agent (per Uzman-Ajan-Önce protokol), not deferred to the operator. Only product-intent Open Questions reach the operator.

---

Dual Review Protocol — Quality Review + Adversarial Challenge

The autonomous review step at the end of Phase 1 and Phase 2c runs two independent subagents in parallel:

1. Quality Review — checks coverage, evidence integrity, missing sections, industry research gaps (the auditor)
2. Adversarial Challenger (Devil's Advocate) — actively tries to break the design: attacks assumptions, constructs failure scenarios, argues for alternatives, simulates adversaries (the attacker)

They run in parallel (no dependency between them) and produce independent reports. The orchestrator merges both into a single §0 Review Log before presenting to the user.

Why two subagents instead of one? A single agent asked to both check quality AND attack the design defaults to the easier task (checklisting). Separate agents with separate stances produce genuinely different findings. The adversarial agent doesn't see the quality report — no anchoring on the same gaps.

---

Quality Review Subagent

Dispatch rules

Parameter	Value
Tool	Agent (subagent dispatch)
subagent_type	general-purpose (needs WebFetch + WebSearch + Read)
model	"sonnet"
description	"Quality Review <doc-name>" (3-5 words)
run_in_background	true — runs in parallel with adversarial challenger
isolation	none (read-only review)

Prompt template (self-contained — agent does NOT see the conversation)

You are the autonomous Quality Review subagent for the `spec-first-feature` skill.

# Task
Critique the document at: <ABSOLUTE_PATH_TO_DOC>
Mode: <system-md | prd>
Project repo root: <ABSOLUTE_PATH_TO_REPO>

# Rubric (READ FIRST)
Read this rubric and follow it strictly:
~/.claude/skills/spec-first-feature/references/review-rubric.md

# What you have access to
- Read tool — to inspect the target doc and spot-check cites in the repo
- WebSearch / WebFetch — for independent industry research (mandatory for PRD mode)
- Grep / Glob — for verifying SYSTEM.md cites and finding PRD coverage gaps

# Discipline
- You do NOT see the orchestrator's conversation with the user. Everything you need is in this prompt + the rubric.
- Do NOT propose stylistic rewrites. Substantive gaps only.
- Cite every industry-practice claim with a real URL. No URL → drop the claim.
- For SYSTEM.md mode: spot-check at least 5 file:line cites in the doc. Flag any false claim as P0.
- For PRD mode: run AT LEAST 5 independent web research queries on topics the PRD does NOT explicitly cover (postmortems, RFCs, compliance shifts, alternative architectures, library CVEs).

# Context
A separate Adversarial Challenger subagent is running in parallel — it attacks the design's assumptions, constructs failure scenarios, and simulates adversaries. Your job is different: focus on completeness, evidence integrity, and coverage gaps. Do not try to be adversarial — be thorough.

# Output
Return EXACTLY the Markdown structure specified in the rubric's "Output format" section.
Cap: 30 gaps, 10 research findings. Take the highest-severity / most decision-changing entries.

# Time budget
Aim for under 10 minutes of research. Quality > quantity. A focused report with 5 P0/P1 gaps beats a padded report with 30 P3 nits.

---

Adversarial Challenger Subagent (Devil's Advocate)

Dispatch rules

Parameter	Value
Tool	Agent (subagent dispatch)
subagent_type	general-purpose (needs WebFetch + WebSearch + Read)
model	"sonnet"
description	"Challenge <doc-name>" (3-5 words)
run_in_background	true — runs in parallel with quality review
isolation	none (read-only)

Prompt template (self-contained — agent does NOT see the conversation)

You are the Devil's Advocate subagent for the `spec-first-feature` skill.

# Task
Attack the design in: <ABSOLUTE_PATH_TO_DOC>
Mode: <system-md | prd>
Project repo root: <ABSOLUTE_PATH_TO_REPO>

# Rubric (READ FIRST)
Read this rubric and follow it strictly:
~/.claude/skills/spec-first-feature/references/adversarial-rubric.md

# What you have access to
- Read tool — to inspect the target doc and cross-check claims against the repo
- WebSearch / WebFetch — for finding postmortems, CVEs, alternative architectures, evidence
- Grep / Glob — for verifying claims in the codebase

# Your stance
You are the skeptic engineer. Your default position: this design will fail in production. Prove it — or fail trying. If the design survives your attacks, it ships stronger.

# Discipline
- You do NOT see the orchestrator's conversation with the user.
- A separate Quality Review subagent already checks for coverage gaps and missing sections. Do NOT duplicate that work. You attack substance: assumptions, failure modes, security, alternatives, evidence quality.
- Steelman before attacking — restate the design choice in its strongest form, THEN attack.
- Every attack needs evidence: URL, logical proof, or document cross-reference. Unsubstantiated attacks are noise — drop them.
- If the design is genuinely solid, say so. "Survives challenge: yes" is a valid report.

# Output
Return EXACTLY the Markdown structure specified in the rubric's "Output format" section.

# Time budget
Aim for under 10 minutes. 3 FATAL/SERIOUS findings with evidence > 15 MINOR concerns without.

---

Orchestrator merge protocol — AFTER both subagents return

Both subagents run in background. Wait for both to complete, then:

1. Read both reports in full. Do not skim.
2. Deduplicate. If both reports flag the same issue (rare but possible), keep the higher-severity version and note the overlap.
3. Classify every finding (Uzman-Ajan-Önce Soru Protokolü):
   • Non-critical → apply directly, log to Decision Log.
   • Critical technical (auth, compliance yorumu, mimari pivot, teknoloji seçimi, kullanıcı verisi tasarımı, paid SaaS seçimi) → software-architect / devops-engineer ajanına gönder, ajan karar versin; kararı Decision Log'a attribution ile yaz. Operatöre sorma.
   • Critical product-intent (scope expansion, kullanıcı-yüzlü isim, fiyat politikası) veya ajan CANNOT-ANSWER → escalate to user as Open Question.
4. Verify before applying. If a subagent says "file X line Y is wrong" or cites a URL, confirm with Read/WebFetch before patching. Subagents hallucinate; verification is cheap.
5. Build the unified §0 Review Log at the top of the doc:

## §0 Review Log

### Quality Review — <date>
| ID | Title | Severity | Status | Note |
|---|---|---|---|---|
| G1 | ... | P0 | applied | ... |
| G2 | ... | P1 | escalated-to-user | ... |
| R1 | ... | — | applied | industry finding |

### Adversarial Challenge — <date>
| ID | Title | Severity | Status | Note |
|---|---|---|---|---|
| A1 | ... | FATAL | escalated-to-user | assumption attack |
| F1 | ... | SERIOUS | applied | failure scenario — added to §9 |
| D1 | ... | CONSIDER | escalated-to-user | alternative approach |
| V1 | ... | HIGH | applied | attack vector — added to §8 |
| E1 | ... | Grade D | applied | evidence strengthened |

**Adversarial verdict:** survives challenge? <yes | qualified-yes | no>

6. Map adversarial findings to PRD sections:
   • Assumption attacks (A*) with FATAL/SERIOUS → add to Risk Register or Open Questions
   • Failure scenarios (F*) → add to Failure Modes & Recovery section
   • Alternative arguments (D*) with SWITCH/CONSIDER → add to Open Questions for user decision
   • Attack vectors (V*) → add to Security Review section
   • Evidence audits (E*) with grade D or below → strengthen evidence or flag as Open Question
7. Track review rounds. After 2 rounds (quality + adversarial = 1 round), stop iterating — present to user even if gaps remain.

When NOT to run the adversarial challenger

• SYSTEM.md mode (Phase 1): Run adversarial challenger only if the SYSTEM.md makes architectural claims or design-decision assertions. If it's purely descriptive (just documenting what exists), skip the challenger — quality review alone suffices. Log the skip: Adversarial pass skipped — SYSTEM.md is descriptive only, no design claims to attack.
• User says "skip the review" → skip BOTH subagents. Log in §0: Review skipped per user request.
• User says "skip the adversarial pass" → skip only the challenger. Quality review still runs.
• Second round AND first round adversarial verdict was "survives challenge: yes" → skip challenger for round 2. Quality review may still run if it had P0 gaps.

Failure modes of the review itself

• Subagent invents a URL → orchestrator MUST attempt to Read/WebFetch any URL it intends to cite before pasting it into the doc. If URL fails, drop the finding.
• Subagent contradicts user-stated requirements → user wins. Log the contradiction in §0 as rejected — conflicts with user requirement <X>.
• Subagent suggests scope expansion → never auto-apply. Always escalate.
• Adversarial challenger manufactures concerns (every finding is FATAL but reasoning is thin) → downgrade severity based on evidence quality. A FATAL finding with no URL/proof becomes MINOR or dropped.
• Both subagents flag contradictory issues (quality says "add X", adversarial says "X is a bad idea") → escalate the contradiction to the user as an Open Question. Do not silently pick a side.

---

Phase 3 — Implementation Engineer (auto-fires on architect GO)

This phase fires automatically when the Phase 2c acceptance gate returns GO. No separate operator trigger is required — the architect agent's GO IS the trigger. The operator can still abort at any time, and the execution-time LAWs below still gate.

Phase 3 mekaniği: Ana akış (sen, ana bağlam) /prd-run <prd-dosya-yolu> skill'ini çağırır. software-architect subagent'ı Skill tool'una sahip değil — prd-run'ı kendisi çağıramaz; bu yüzden architect GO döner, ana akış prd-run'ı tetikler. prd-run PRD'yi fazlara böler, Sonnet ile implementation, Opus ile verification + fix döngüsü çalıştırır; severity-based fix routing + retry/escalation/rollback otomasyonu sağlar. Tüm faz çıktıları ve değişiklik takibi docs/prd-<feature>.progress.md'ye yazılır — PRD dosyasının kendisi değiştirilmez. Detaylar: ~/.claude/skills/prd-run/SKILL.md.

Execution-time LAWs (bu otonomi bunları GEVŞETMEZ)

• §6 — remote git: prd-run sırasında her git push / force-push / gh pr merge her seferinde operatör onayı ister. Architect GO bunu kapsamaz.
• §7 — AWS: public erişim açma / asset silme operatör onayı ister.
• Gerekçe: bunlar geri dönüşü olmayan aksiyonlar, PRD kararları değil. Otonomi PRD yazımını kapsar; irreversible execution hâlâ insanda.

Steps (when invoked)

1. Re-read both documents at session start. SYSTEM.md = map; PRD = blueprint.
2. Phases in order. Faz 0 first. No Faz 1 work in Faz 0 commits.
3. Small commits. Each ties to one AC or one logical unit. PR title references PRD section.
4. Test as you go. AC-driven tests. If no test infra exists, build minimum needed.
5. Update SYSTEM.md in the same PR when architecture changes (new service, table, integration).
6. Update PRD's Decision Log if you discover the PRD is wrong — route the correction to software-architect (technical) or the operator (product-intent / CANNOT-ANSWER), update PRD, then code.

Discipline rules — non-negotiable

• PRD wrong → stop → update PRD → continue. Never silently deviate.
• Stay in scope. Spotted an unrelated bug? Note it, surface separately, do not fix in this PR.
• Open Question resolution belongs in the PRD, not in code comments.

---

---

Phase 4 — Verification & Delivery (auto-fires on prd-run completion)

prd-run tüm fazları tamamladığında bu phase otomatik başlar. Operatör onayı gerekmez — sadece git push komutunun kullanıcı tarafından çalıştırılması beklenir (Golden Rule §6).

Adım 1 — Test Planı

/test-plan <feature> skill'ini çağır → docs/test-plan-<feature>.md üretilir.

Adım 2 — TEST GATE (qa-eval-developer)

qa-eval-developer agent'ını dispatch et:

• Görevi: docs/test-plan-<feature>.md + docs/prd-<feature>.md'yi oku, testleri yaz + koş.
• Bitti diyince _standup.md'ye TEST GATE: PASS | FAIL yazar, @project-manager etiketler.
• TEST GATE FAIL → blokör builder'a handoff (_standup.md @<agent>), fix + re-run beklenir. Bu phase fix tamamlanana kadar ilerlemez.

Adım 3 — Push Hazırlık (project-manager)

_standup.md'de TEST GATE: PASS görününce project-manager agent'ını dispatch et:

• P1-P8 kontrol listesini koşar (P6'yı _standup.md'deki TEST GATE sonucundan okur).
• Tüm kontroller geçerse AUTO-GO — kullanıcıya şunu göster:

## Phase 4 Tamamlandı — Push Hazır

Testler: ✅ PASS (<N> test)
Push kontrolleri: ✅ AUTO-GO

Çalıştır:
  git push origin <dal>

Push sonrası pipeline (otomatik):
  → CI/CD tetiklenir
  → <proje>-live-test (varsa)

• NO-GO → blokörler listelenir, ilgili agent'a handoff verilir, fix sonrası Adım 3 tekrar koşar.

Adım 4 — Post-Push

Kullanıcı git push çalıştırdıktan sonra project-manager post-push pipeline'ını yönetir:

1. CI doğrulama
2. Deploy (DEPLOY.md'ye göre)
3. <proje>-live-test tetikleme (mevcutsa)

Pipeline özeti docs/prd-<feature>.progress.md'ye status: delivered ile eklenir.

Execution-time LAWs (Phase 4'te de geçerli)

• §6: git push kullanıcı çalıştırır — agent çalıştırmaz.
• §7: AWS public/silme operatör onayı ister.

---

What this skill refuses to do

• Refuses to write a PRD without a SYSTEM.md unless the user explicitly insists after warning (then every existing-system claim is [OPEN-QUESTION]-tagged).
• Refuses to start implementation without software-architect GO on the PRD. Phase 3 fires on the agent acceptance gate, not on an operator command — but it never fires on an un-GO'd PRD.
• Refuses to invent facts about the existing system. Uncertainty → OPEN QUESTION.
• Refuses to skip Phase 2a (research) unless web tools are unavailable AND user accepts [NEEDS-WEB-VERIFY] tagging.
• Refuses to skip the Phase 2c production-readiness checklist. A PRD with empty Risk Register is not done.
• Refuses to skip the autonomous review step unless the user explicitly says "skip the review" — and even then, the skip is logged in §0 Review Log.

If the user tries to skip ahead, explain why the sequence matters and offer to do it anyway with the caveats flagged.

---

Reference files

• references/system-doc-template.md — structural skeleton for Phase 1
• references/prd-template.md — structural skeleton for Phase 2 (includes Use Cases, Industry Benchmark, Risk Register, Failure Modes, Decision Log, Production-Readiness Checklist)
• references/research-checklist.md — what to research per feature type before drafting
• references/review-rubric.md — rubric and output format for the Quality Review subagent (Phase 1 + Phase 2c)
• references/adversarial-rubric.md — rubric and output format for the Adversarial Challenger (Devil's Advocate) subagent

Read these when entering the corresponding phase, not before. The rubrics are read by the subagents, not by you — but you should skim them once so you know what each subagent is checking against.