solution-design

name	solution-design
description	Design a production-ready solution from repository evidence and accepted requirements. Use for architecture, interfaces, data contracts, compatibility, migrations, rollback, observability, security, testability, release effects, or ADR decisions.
license	MIT

Solution Design and Architecture

Read ../.shared/operating-model.md; use the design/ADR template in ../.shared/artifact-templates.md.

When to invoke

Use for new systems, cross-module changes, public contracts, data/schema/infrastructure changes, high-risk fixes, refactors, or any material decision with multiple viable approaches. A small familiar change may need only a design delta.

Inputs and evidence

Expect accepted requirements or clearly stated design-only scope. Inspect current architecture, dependency direction, entry points, data flow, interfaces/schemas, tests, deploy topology, observability, security guidance, historical decisions and Git history, and current authoritative docs for external APIs/frameworks.

Workflow

1. Describe current state, constraints, pain points, and invariants with exact repository evidence.
2. Propose responsibilities, component boundaries, flows, interfaces, data/failure contracts, configuration, and lifecycle behavior.
3. Analyze alternatives—including no change when meaningful—by correctness, complexity, compatibility, operability, cost, delivery risk, and reversibility.
4. Address backward/forward compatibility, version negotiation, deprecation, data/config migration, coexistence windows, rollback, and failure recovery.
5. Design observability: user-visible errors, logs without secrets, metrics/traces, health, alerts, dashboards, ownership, and diagnostic paths.
6. Address authentication/authorization, trust boundaries, sensitive data, privacy/retention, dependency/supply-chain risk, abuse/failure modes, least privilege, and secrets.
7. Map design to test levels, test seams/data/environments, CI implications, feature flags, deployment sequencing, and release evidence.
8. Create/update an ADR when the decision is durable, cross-cutting, costly to reverse, contested, or establishes a standard. Follow the repository’s ADR convention; do not impose a new path.
9. Recheck every REQ-*/AC-* for design coverage and list decisions/questions.

Outputs and handoff

Current/proposed design, alternatives/tradeoffs, contracts, compatibility/migration/rollback, observability/security/test/release implications, ADRs if warranted, and requirement coverage. Handoff to security-operations for high-risk design review and then delivery-planning.

Completion evidence

The design is feasible against the actual repository; interfaces and failure behavior are explicit; compatibility, rollback, security, operations, tests, and release are addressed; tradeoffs and open questions are honest.

Must not

• Implement, select technology from fashion, or force greenfield patterns onto an existing system.
• Invent external API behavior; retrieve current authoritative documentation.
• Create an ADR for routine reversible detail or omit consequences/alternatives for a material decision.