Architecture

Architecture

Purpose

Make software architecture decisions traceable, proportionate to the problem, and grounded in evidence. Treat architecture as the system's boundaries, responsibilities, dependencies, data flows, runtime behavior, deployment topology, and quality attributes—not as a list of fashionable patterns.

Use this skill to create or review an architecture brief, a decision record, a target-state design, an architecture review, or an incremental migration plan. Prefer the simplest design that satisfies the stated constraints and quality targets. Do not default to microservices, event-driven integration, or a new framework without a concrete reason.

Routing

Use ultra-grill-me when the user explicitly wants adversarial questioning before deciding. Use feature-dev, bugfix, or refactoring when the main request is implementation, repair, or behavior-preserving cleanup. Keep this skill active when the task is to make or record an architecture decision, even if implementation work may follow.

Operating rules

• Inspect before prescribing. For an existing codebase, examine project instructions, entry points, module/package layout, dependency manifests, persistence, integration clients, tests, build and deployment configuration, observability, and recent relevant history.
• Label every important statement as a fact, an assumption, an inference, or an unresolved question. Cite repository paths and line numbers for material findings when available.
• Make quality attributes testable. Turn vague goals such as “scalable” or “highly available” into scenarios with a stimulus, environment, response, and measurable target.
• Compare alternatives against the same criteria. Include the current state or simplest viable baseline; do not present a single preferred pattern as if it were an analysis.
• Make ownership and failure behavior explicit: component responsibility, data ownership, transaction boundary, communication mode, retry/idempotency, timeout, backpressure, consistency, recovery, and observability.
• Separate target architecture from migration architecture. Explain how the system can move safely in increments, including compatibility, rollback, and data migration concerns.
• Record what would change the decision: assumptions, decision triggers, guardrails, and review date or horizon.
• Avoid invented throughput numbers, team structures, costs, compliance requirements, or infrastructure capabilities. Mark missing evidence and recommend how to measure it.

Workflow

1. Frame the decision

State the decision in one sentence. Capture the system boundary, users or actors, business capability, desired outcome, scope, constraints, non-goals, compatibility requirements, risk horizon, and who owns the decision. Define what “good” means before comparing designs.

If the request is underspecified, make low-risk assumptions and list them. Ask for clarification only when the missing choice materially affects security, privacy, data loss, regulatory exposure, public contracts, cost, or irreversible design direction.

2. Build the evidence base

For a repository task, inspect the smallest useful set of artifacts first:

• project instructions and architecture documentation
• package or dependency manifests, entry points, configuration, and build scripts
• top-level module or service directories and their public interfaces
• data models, migrations, queues, caches, external integrations, and authentication boundaries
• tests, CI/CD, deployment manifests, runtime configuration, logs, metrics, and tracing setup