| 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.
