architecture-decision-quality

name	architecture-decision-quality
description	Turn a specification into a concrete architecture with stable contracts, file boundaries, ownership, and risk analysis. Use this when acting as the architecture writer for a task.
owner	architect
trigger	null
version	1

Architecture Decision Quality

Use this before finalizing an architecture deliverable.

Goal

Convert the spec into an architecture that execution agents can implement with minimal ambiguity and minimal cross-agent conflict.

Checklist

1. Start from the spec, then validate against the codebase. Reuse existing patterns when they already solve the problem. Do not design a new subsystem when the repo has an established one.
2. Make contracts binding. ## API Contracts and ## Shared Types must be concrete enough that execution agents can implement or consume them without inventing missing fields, names, or shapes.
3. Define file boundaries with ownership. ## File Boundaries should say which files change, whether they are created or modified, and which agent should own each slice. Avoid overlapping ownership unless coordination is unavoidable.
4. Refine data design only where needed. Confirm or correct the spec, but do not explode into unnecessary schema detail.
5. Fail closed on risks. Call out the real integration, migration, compatibility, and concurrency risks. High-severity risks need a mitigation, fallback, or explicit reason they are acceptable.
6. Keep the design implementable. Prefer additive changes, stable imports, single-source shared types, and compatibility shims over sweeping rewrites.

Guardrails

• Do not leave shared types implicit. If multiple agents need a type, name it and say exactly where it lives.
• Do not put vague entries like "frontend files" or "backend logic" in ## File Boundaries; name actual paths or path patterns.
• Do not turn architecture into a planner task list. Say what must exist and who owns it, not every coding step.
• If the design changes an external or internal interface, activate api-change-protocol.
• If the design changes shared behavior or compatibility boundaries, activate implementation-strategy.

Deliverable Standard

Before submitting, ask:

• Could two execution agents implement opposite sides of a contract and still match?
• Could the planner assign work without re-deciding ownership?
• Does each real risk have an actionable mitigation?

If not, tighten the architecture before calling submit_deliverable.