<!--
TÜRKÇE AÇIKLAMA
───────────────
Bu skill, bir implementasyon planı kod yazılmadan önce "ikinci göz" olarak
stres testine tabi tutar. Aşırı mühendislik, döngüsel bağımlılıklar, eksik
hata senaryoları, güvenlik açıkları ve ölçeklenebilirlik sorunlarını erken tespit eder.
Yanlış temele inşa etmenin maliyeti çok yüksektir — bu skill o maliyeti sıfıra indirir.
NE ZAMAN: Plan hazırlandıktan SONRA, kod yazmaya başlamadan ÖNCE. Zorunludur.
ÇIKTI: 🔴 Blocker / 🟡 Warning / 🔵 Note listesi + Approved/Revisions Required kararı.
-->
Architecture Review Skill
When to Trigger
- After
writing-plans produces an implementation plan, before executing-plans
- When a significant refactor is proposed
- When adding a new external service or integration
- When the team is debating between two approaches
- When something "feels off" about a design but you can't articulate why
Step-by-Step Process
1. Load the Plan
Read the implementation plan (typically implementation_plan.md or the artifact from writing-plans).
Extract:
- Components being built
- Data flow between components
- External dependencies
- Assumptions the plan makes
2. Run the Checklists
Work through each checklist section. For every "No" or "Unclear" answer, flag it as a finding.
A. Complexity Check
B. Coupling & Cohesion
C. Data & State
D. Failure Modes
E. Security
F. Scalability
G. Observability
H. Operability
3. Classify Findings
For each "No" or "Unclear" found above, classify it:
| Class | Meaning | Action |
|---|
| 🔴 Blocker | Must fix before implementation | Revise plan |
| 🟡 Warning | Should address, can proceed carefully | Add a task to backlog |
| 🔵 Note | Nice to have, low risk | Document and move on |
4. Produce the Review Report
Her zaman ayrı bir dosyaya yaz — plan dosyasını kirletme:
.agent/reviews/architecture-review-<plan-slug>.md
Eğer bu review'dan önemli bir mimari karar çıktıysa, ek olarak knowledge-base-update skill'ini kullanarak decision tipiyle knowledge base'e de ekle — project-context-primer oradan okuyacak.
# Architecture Review — <plan name>
**Date:** <YYYY-MM-DD>
**Reviewer:** Agent
## Verdict
<Approved | Approved with conditions | Revisions required>
## 🔴 Blockers
### 1. <Finding title>
**Checklist item:** Failure Modes — timeout on I/O
**Issue:** The email service call has no timeout. If SendGrid hangs, the entire request thread blocks.
**Recommendation:** Wrap in a 5-second timeout; use a background job queue for non-critical emails.
## 🟡 Warnings
### 1. <Finding title>
...
## 🔵 Notes
### 1. <Finding title>
...
## Summary
<Overall health of the architecture in 2-3 sentences.>
5. Gate: Proceed or Revise?
- If there are any 🔴 Blockers: stop. Share the report with the user and revise the plan before any code is written.
- If there are only 🟡/🔵: proceed, but ensure warnings are tracked as tasks.
Rules
- Be specific, not generic. "You should add error handling" is useless. "The
fetchUser() call on line 42 of the plan has no 404 handling" is a review.
- Don't block on stylistic preferences. Blockers are objective risks, not taste.
- Never approve a plan with an undefined failure mode for a critical path.
- If you can't understand part of the plan, that is itself a finding — clarity is a requirement.