pre-build-architect

name	pre-build-architect
description	6-layer pre-code architecture mapping skill. Use before writing any non-trivial implementation to map the full architectural surface before the first line of code. Triggers on "architect this", "map the architecture", "design before build", or automatically when spec-architect Phase 2 involves cross-system impact. Outputs a layered architecture map that feeds into DECISIONS.md.

Pre-Build Architect Skill

Purpose

Before implementation, map the 6 architectural layers the change touches. This prevents mid-build discovery of integration conflicts, missing abstractions, and design decisions that should have been made before any code existed.

"An hour of architecture saves a day of refactoring."

The 6 Layers

Layer 1 — Data Layer

• What entities are involved? (tables, collections, models)
• What columns / fields change? (add, modify, remove)
• What indexes are needed? (new queries = new indexes)
• What constraints apply? (nullable, unique, foreign key, check)
• Migration: is this forward-compatible? Can it be rolled back?

Layer 2 — Repository / Data Access Layer

• What queries does this feature require?
• Are they covered by existing repository methods or do new ones need creating?
• Any N+1 risks in how data will be fetched?
• Transaction boundaries: what must succeed or fail atomically?

Layer 3 — Business Logic / Service Layer

• What business rules govern this feature?
• Which service owns this logic? (one owner, not split across services)
• What are the invariants? (conditions that must always be true after this runs)
• What domain events does this trigger?
• For payroll: where do accumulators, thresholds, and compliance checks live?

Layer 4 — API / Interface Layer

• What endpoints are needed? (method, path, auth level)
• What is the request contract? (typed schema)
• What is the response contract? (typed schema, including all error responses)
• What validation happens at this layer vs the business layer?
• Versioning: does this break existing consumers?

Layer 5 — Integration Layer

• What external systems are called? (APIs, queues, file systems, webhooks)
• What are the failure modes? (timeout, rate limit, partial response)
• Are calls idempotent? (what happens on retry?)
• What data crosses trust boundaries? (PII, financial, secrets)

Layer 6 — Observability Layer

• What logs are needed to debug a production failure of this feature?
• What metrics track its health? (success rate, latency, error rate)
• What audit events are required? (compliance, who/when/what on every write)
• What alerts should fire? (payroll: amounts outside expected range, run failures)

Output Format

## Architecture Map — [Feature Name]

Layer 1 (Data):
  Entities affected: [list]
  Schema changes: [column, type, nullable, index]
  Migration reversible: yes / no

Layer 2 (Repository):
  New methods needed: [list]
  Existing methods reused: [list]
  Transaction boundary: [description]

Layer 3 (Service):
  Owner service: [name]
  Business rules: [list]
  Invariants guaranteed: [list]

Layer 4 (API):
  Endpoints: [METHOD /path — auth level]
  Request type: [reference]
  Response type: [reference]

Layer 5 (Integration):
  External calls: [list / none]
  Failure strategy: [retry / fail-fast / fallback]

Layer 6 (Observability):
  Logs: [what, what level]
  Audit events: [list / none]
  Alerts: [trigger conditions]

Architecture risks: [top 1-2]
Decision required: [any conflict needing human input]

Log this map to DECISIONS.md before implementation begins.