Pragmatic arch spec create

pragmatic-arch-spec-create

Create a software architecture technical specification document for a system, module, layer, or integration.

Purpose

Produce a thorough architecture tech spec that captures design decisions (ADRs), component boundaries, architecture patterns, data flows, and non-functional requirements. Specs live in docs/arch/.

Scope Types

• system — full application or bounded context
• module — a single feature module or domain
• layer — a horizontal layer (e.g., data access, presentation)
• integration — an external integration or adapter

Default scope when not specified: module.

When This Skill Applies

Use this skill when no arch spec exists yet for the system, module, or integration being documented.

Do not use when:

• An arch spec already exists and the user wants to modify it → use pragmatic-arch-spec-update
• An arch spec already exists and the user wants a quality review → use pragmatic-arch-spec-validate

Edge case: if the user asks to "document the actual architecture" of an existing codebase (reverse-engineering decisions from code), scan the codebase thoroughly in Step 1 before the discovery interview — the code is the source of truth for what was actually built.

How to Create an Architecture Spec

Pre-condition — Check for Existing Arch Spec

Before anything else, determine the <name> from the user's message and check whether docs/arch/<name>.arch.md already exists.

If the file exists:

"An architecture spec already exists at docs/arch/<name>.arch.md. This skill will replace it. Did you mean to:

• Update decisions or component boundaries → use pragmatic-arch-spec-update
• Review its quality → use pragmatic-arch-spec-validate

I will only continue if you explicitly confirm you want to replace the existing architecture spec."

STOP. Do not proceed until the user explicitly confirms they want to replace the existing spec. If the user wants to update or validate instead, end this skill now.

---

Step 0 — Language Selection

Infer the document language before asking:

1. Detect user message language — if ≥80% of prose words in the user's message are in pt-BR, es-ES, or en-US, use that language without asking
2. Check existing arch specs — if step 1 is ambiguous (e.g., mostly technical terms or code snippets), scan docs/arch/ for existing arch spec files and use their language if uniform
3. Ask only if inconclusive — if both steps above are ambiguous, use AskUserQuestion:

In which language would you like the architecture spec to be generated?

1. pt-BR — Portuguese (Brazil)
2. es-ES — Spanish (Spain)
3. en-US — English (United States)
4. Other — specify which language

Record the chosen language and use it consistently for all content in the generated document — section headings, component descriptions, ADR rationale, data flow descriptions, and TODO comments.

Step 1 — Understand the Context

Determine from the user's input:

• Name — the system, module, or layer being documented
• Scope — how broad the document should be (system / module / layer / integration)

Before writing, scan the codebase for:

• Existing code, README files, or prior specs that reveal current decisions and constraints
• Related architecture specs in docs/arch/

Step 1.5 — Architecture Discovery Interview

This is a mandatory step. Do not generate the architecture document until you have a complete picture of the system's context, constraints, quality requirements, and open decisions.

After identifying the name/scope and scanning the codebase, use AskUserQuestion to conduct a focused architecture discovery. The goal is to understand the "why" behind the architecture — decisions only make sense in context.

Adapt the questions to the scope and what is not already evident from the codebase.

multiSelect rules for this step — always follow these:

• Quality Attributes: multiSelect: true — multiple NFRs apply simultaneously
• Constraints: multiSelect: true — technology, integration, and organizational constraints can coexist
• Pain Points / Risks: multiSelect: true — there are usually several concerns at once
• Architectural Goals: multiSelect: true — multiple goals drive the same architecture

Every question with a concrete option list must carry a recommended answer (➡️). Derive it in this priority order:

1. Related architecture specs already in docs/arch/ — reuse established quality targets or constraints
2. Patterns evident in the codebase scan (Step 1) — e.g. current infra, current uptime posture
3. A pragmatic default for the scope type, stated as such (e.g. "no strong signal — defaulting to X because Y")

Never present a bare menu with no recommendation — the user should be able to just confirm the ➡️ line.

Example format:

Before I write the architecture spec, I need to understand the broader context:

**Purpose & Drivers**
- What problem does this [system/module/layer/integration] solve, and for whom?
- What are the main business or product drivers behind this architecture?

**Quality Attributes (Non-Functional Requirements)** → multiSelect: true
Which of these matter most? (select all that apply — provide targets where known)
- Performance: expected throughput, latency targets
  ➡️ No strong signal in the codebase — recommend stating a target explicitly rather than leaving it implicit
- Scalability: peak load, growth projections
- Availability: uptime requirements, acceptable downtime
  ➡️ Match the uptime posture of related specs in docs/arch/, if any exist
- Security: data sensitivity, compliance requirements (LGPD, SOC2, PCI-DSS, etc.)
- Maintainability: how often will this change, and by what size team?
- Cost: any budget constraints on infrastructure?

**Constraints** → multiSelect: true
Which of these apply? (select all that apply)
- Technology constraints (existing platform, team skills, vendor agreements)
  ➡️ Existing platform — codebase already runs on [platform found in Step 1]
- Integration constraints (systems that cannot change)
- Organizational constraints (team structure, deployment pipeline, environment restrictions)

**Current Pain Points / Risks** → multiSelect: true
What is not working well today? (select all that apply)
- Performance / scalability problems
- Reliability / availability issues
- Security gaps or compliance risk
- High operational cost
- Developer experience / maintainability concerns

**Expected Evolution**
- How is this expected to evolve over the next 6–12 months?
- Are there known future requirements that should influence today's design?

**Open Decisions**
- Are there architectural decisions still being debated? Which options are on the table?

Answer what you know, or just confirm the ➡️ recommendation — for anything undecided, I'll capture it as an open ADR item in the spec.

STOP. Do not generate the architecture document until all three conditions below are met. Architecture specs written without this foundation will have FAIL findings in pragmatic-arch-spec-validate:

• The purpose and main quality attributes are understood
• Key constraints are captured
• Major open decisions are identified

Step 1.6 — Follow-up Round for Dependent Decisions

After the user answers Step 1.5, check whether any selected Quality Attribute or Constraint unlocks a dependent decision that could not have been asked before it (its options only make sense given the parent answer). Common triggers:

Parent answer	Dependent question to ask now
Security: LGPD/SOC2/PCI-DSS compliance	Data residency requirements? Encryption at rest/in transit? Audit logging required?
Availability: high uptime target	Multi-region or multi-AZ failover? Acceptable RTO/RPO?
Technology constraint: existing platform	Which specific platform/version? Any deprecation timeline to design around?
Integration constraint: systems that cannot change	Which protocol/contract must be preserved exactly?

If any dependent question applies, ask it now via AskUserQuestion — with a recommended answer, following the same rule as Step 1.5 — instead of leaving it as a vague open ADR item. Only questions whose parent decision itself remained undecided should still become [TODO: ...].

Run this check once. A second round should not itself spawn a third round unless the scope is unusually broad (e.g. system-level) — if it does, proceed to Step 2 anyway and leave the remainder as open ADR items rather than turning the interview into an unbounded loop.

Step 1.7 — Final Consistency Check

Before generating the document, assemble every decision confirmed across Steps 1.5 and 1.6 into one list, grouped by area. Scan pairwise for contradiction — not completeness (that is pragmatic-arch-spec-validate's job) — only cases where one confirmed decision makes another incoherent or impossible.

Known contradiction shapes to check for:

Area A	Area B	Contradiction pattern
Quality Attributes (Cost)	Constraints / dependent decisions	A strict budget constraint alongside a recommendation that implies significant spend (e.g. multi-region failover)
Current Pain Points (high operational cost)	Expected Evolution (major growth)	Growth answer worsens an already-flagged cost pain point — worth noting as a risk, not necessarily blocking
Constraints (existing platform)	Technology-implying Quality Attributes	A stated platform constraint conflicts with what a chosen NFR target would require

If no contradiction is found, skip straight to the recap below.

If a contradiction is found, do not silently resolve it. Present it explicitly and wait:

⚠️ Possible contradiction: [Decision A] says "...", but [Decision B] says "...". These look inconsistent because [reason]. Which should hold — or is there context I'm missing?

Once no contradictions remain, present the full recap and require explicit confirmation:

Here's the complete picture before I write the architecture spec: Purpose & Drivers: ... Quality Attributes: ... Constraints: ... Open Decisions: ... Confirm this is complete, or tell me what's missing or wrong.

STOP. Do not proceed to Step 2 until the user explicitly confirms.

Step 2 — Generate the Architecture Tech Spec

Create the file at docs/arch/<name>.arch.md using the full template in references/template.md.

Fill every section with concrete content. Use [TODO: ...] only for information that genuinely cannot be inferred and requires a human decision.

Diagram Guide

Use Mermaid diagrams to make structure and behavior immediately visible. Apply the right diagram type for each context:

Situation	Diagram type	Section
Component structure and dependencies	graph TD or flowchart TD	4.1, 6.2
Request/response flow between components	sequenceDiagram	7
Async flow with queues, events, or branching	flowchart LR	7
State transitions (e.g., status machine)	stateDiagram-v2	7

Rules:

• Section 4.1 (Component Diagram): always use graph TD — show every component and their dependency direction
• Section 6.2 (Dependency Direction): use flowchart TD to show allowed vs. forbidden dependency arrows explicitly
• Section 7 (Data Flow): use sequenceDiagram for synchronous flows; use flowchart LR when the flow involves async steps, queues, or conditional branching. Replace ASCII art — do not use plain text arrows.
• Keep diagrams focused: one diagram per flow. Do not combine multiple flows into a single diagram.

Step 3 — Output Summary

After creating the file:

1. State the file path created
2. Summarize the key architectural decisions documented
3. List any [TODO: ...] items that remain open

---

Arch spec created — docs/arch/<name>.arch.md.

Next step: Run pragmatic-arch-spec-validate to verify the spec is complete and sound. Do not use this spec as reference for pragmatic-arch-spec-check until it passes validation. FAIL or WARN items → resolve with pragmatic-arch-spec-update → re-validate until PASS → then run pragmatic-arch-spec-check.

Output Location

docs/arch/<name>.arch.md

Additional Resources

Reference Files

• references/template.md — Full architecture tech spec template with all sections, ADR format, and component table structure

Example Files

Use these examples as calibration targets for output structure, ADR depth, component boundary detail, diagram usage, and writing style. Each example showcases a different architecture pattern:

• examples/example-payments-arch.md — Payments module with anti-corruption layer and transactional outbox. Showcases graph TD for component dependencies, flowchart TD for dependency direction, and sequenceDiagram for synchronous multi-step flows
• examples/example-notification-service-arch.md — Event-driven notification service with multiple channels (email + push). Showcases consumer/dispatcher pattern, sequenceDiagram for async flows, and flowchart LR for opt-out/skip branching logic