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.
1---2name: pre-build-architect3description: 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.4---56# Pre-Build Architect Skill78## Purpose910Before implementation, map the 6 architectural layers the change touches.11This prevents mid-build discovery of integration conflicts, missing abstractions,12and design decisions that should have been made before any code existed.1314"An hour of architecture saves a day of refactoring."1516## The 6 Layers1718### Layer 1 — Data Layer19- What entities are involved? (tables, collections, models)20- What columns / fields change? (add, modify, remove)21- What indexes are needed? (new queries = new indexes)22- What constraints apply? (nullable, unique, foreign key, check)23- Migration: is this forward-compatible? Can it be rolled back?2425### Layer 2 — Repository / Data Access Layer26- What queries does this feature require?27- Are they covered by existing repository methods or do new ones need creating?28- Any N+1 risks in how data will be fetched?29- Transaction boundaries: what must succeed or fail atomically?3031### Layer 3 — Business Logic / Service Layer32- What business rules govern this feature?33- Which service owns this logic? (one owner, not split across services)34- What are the invariants? (conditions that must always be true after this runs)35- What domain events does this trigger?36- For payroll: where do accumulators, thresholds, and compliance checks live?3738### Layer 4 — API / Interface Layer39- What endpoints are needed? (method, path, auth level)40- What is the request contract? (typed schema)41- What is the response contract? (typed schema, including all error responses)42- What validation happens at this layer vs the business layer?43- Versioning: does this break existing consumers?4445### Layer 5 — Integration Layer46- What external systems are called? (APIs, queues, file systems, webhooks)47- What are the failure modes? (timeout, rate limit, partial response)48- Are calls idempotent? (what happens on retry?)49- What data crosses trust boundaries? (PII, financial, secrets)5051### Layer 6 — Observability Layer52- What logs are needed to debug a production failure of this feature?53- What metrics track its health? (success rate, latency, error rate)54- What audit events are required? (compliance, who/when/what on every write)55- What alerts should fire? (payroll: amounts outside expected range, run failures)5657## Output Format5859```60## Architecture Map — [Feature Name]6162Layer 1 (Data):63 Entities affected: [list]64 Schema changes: [column, type, nullable, index]65 Migration reversible: yes / no6667Layer 2 (Repository):68 New methods needed: [list]69 Existing methods reused: [list]70 Transaction boundary: [description]7172Layer 3 (Service):73 Owner service: [name]74 Business rules: [list]75 Invariants guaranteed: [list]7677Layer 4 (API):78 Endpoints: [METHOD /path — auth level]79 Request type: [reference]80 Response type: [reference]8182Layer 5 (Integration):83 External calls: [list / none]84 Failure strategy: [retry / fail-fast / fallback]8586Layer 6 (Observability):87 Logs: [what, what level]88 Audit events: [list / none]89 Alerts: [trigger conditions]9091Architecture risks: [top 1-2]92Decision required: [any conflict needing human input]93```9495Log this map to DECISIONS.md before implementation begins.
arogyareddy