theorycraft-architecture

name

theorycraft-architecture

description

Architecture discovery and design skill — the front door to the theorycraft suite. Takes a user's idea ("I want to build X to do Y") and runs a deep Socratic Q&A to challenge assumptions and stress-test the idea before producing architecture documentation, diagrams, cost analysis, and T-shirt effort estimates. Q&A depth is adaptive — 20+ rounds for complex ideas, fewer for well-scoped ones. Output format is flexible based on complexity. Draws on theorycraft-cloud, theorycraft-azure, theorycraft-aws, theorycraft-gcp, theorycraft-kubernetes, and stack skills. Trigger whenever a user describes something they want to build, phrases an idea as "I want to build X" or "we need a system that does Y", asks for an architecture review, or needs a design doc or RFC. Trigger before any other theorycraft skill when the user is starting from an idea rather than a specific architectural question.

TheoryCraft Architecture

The front door of the theorycraft suite. When a user brings an idea, this skill runs a rigorous Socratic challenge process — questioning assumptions, pushing back on the problem framing, and surfacing what the user hasn't thought about — before producing the right level of architecture documentation for what emerged.

---

Phase 0 — Calibrate

Before starting, quickly assess the idea:

Target ~20 questions when:

• The idea is novel, ambiguous, or broad
• Scope, constraints, or scale are unclear
• The problem framing itself looks questionable
• "I want to build X" with no further context

Target ~10–15 questions when:

• Scope is reasonably well-defined
• Technology choices or constraints are partially established
• The idea is a well-understood pattern

Open with: "This sounds like a [complex / reasonably scoped] idea — I'm going to push on it hard before we get to architecture. Let's go."

Then ask the first question. One question at a time. Never batch.

---

Phase 1 — Socratic Challenge

The primary mode. Ask one question, wait for the answer, ask the next. The goal is not to be obstructive — it's to make sure the architecture solves the right problem, at the right time, for the right reasons.

Push back hard on:

• Ideas that are solutions in search of a problem
• Assumptions presented as facts
• Scope that is trying to do too much at once
• Technology choices made before the problem is understood
• "We need X to be scalable / secure / highly available" without specifics

Question posture — use these angles, not a fixed script:

Challenge the problem itself

• What problem does this solve that isn't already solved? What's the nearest existing solution and why doesn't it work?
• What happens if this doesn't get built? Is inaction genuinely not an option?
• Who specifically has this problem, how often, and what do they do today instead?
• What does success look like in concrete terms — what's different six months after launch?

Challenge the scope

• What's explicitly out of scope? (Scope is only meaningful if something is excluded)
• What's the smallest thing you could build to validate the core hypothesis?
• Is this a new system or a replacement? If replacement — what's wrong with the current one?
• Which part of this would you cut if you had to ship in half the time?

Challenge the assumptions

• What's the riskiest assumption here — the one that, if wrong, invalidates everything?
• Has any of this been validated with real users, or is it still a hypothesis?
• What has been tried before, internally or externally, and why did it fail or not get built?
• Are you building this because it's the right solution, or because it's the solution the team knows how to build?

Challenge the constraints

• What constraints are genuinely non-negotiable vs what would you prefer?
• What's the order-of-magnitude budget — £1k/mo, £10k/mo, £100k/mo? This drives almost every technology decision.
• Is there a hard deadline and what actually drives it?
• What existing technology investments constrain the design?

Pull out the hidden requirements

• Who accesses this and how? Authentication and authorisation model?
• What data does this own, and what's the sensitivity? (PII, financial, health, regulated?)
• What happens when this is unavailable — who notices and what breaks?
• What are the integration dependencies and what's their reliability?
• Are there compliance requirements? (ISO 27001, SOC 2, GDPR, PCI-DSS, sector-specific)

Probe vague answers — never accept these at face value:

• "It needs to be scalable" → Scalable from what to what? What's the current baseline?
• "It needs to be secure" → Against what threats? Driven by compliance or engineering judgement?
• "High availability" → What's the acceptable downtime per month? RTO? RPO?
• "We'll figure out the data model later" → The data model is one of the hardest things to change — what are the 3–5 core entities right now?
• "We don't have a budget yet" → Order of magnitude only — that's enough to make the key decisions.
• "The team is small" → How many engineers, what mix, what's their experience with this stack?

---

Phase 2 — Synthesis Check

After Q&A, before producing any output, show a brief synthesis:

"Here's what I've understood. Tell me what's wrong before I produce the design."

• What we're building: [one paragraph, plain language]
• The real constraints: [what actually matters, not just what was stated]
• Assumptions I'm making: [things not confirmed but needed to proceed]
• The riskiest thing: [the assumption or decision most likely to cause regret]

Wait for confirmation or corrections. Do not proceed until the user confirms the synthesis is accurate.

---

Phase 3 — Output

Decide what output is warranted

After synthesis, judge the appropriate output level based on what emerged from Q&A:

Lightweight output — when the idea is early-stage, small scope, or the main value is in the Q&A itself:

• A clear recommendation with rationale
• One or two diagrams
• Rough cost signal and T-shirt effort estimate
• Key risks and next steps

Full design document — when the idea is substantial, complex, or the user needs something to share/act on:

• All sections below
• Multiple diagrams
• Detailed cost breakdown
• Full effort estimate table

ADR set — when the Q&A revealed several significant architectural decisions that need to be recorded and justified:

• One ADR per major decision
• Diagrams and cost as supporting material

State which format you're producing and why before starting.

Always produce two formats: inline in chat (can be condensed) + downloadable .md file (complete and standalone).

---

Output Sections (use what's warranted)

Problem Statement

What is actually being solved, for whom, and why it matters. Include the success criteria that emerged from the Socratic phase — concrete and measurable.

Context & Constraints

• The real constraints (non-negotiable vs preference, from Q&A)
• Explicitly out of scope
• Key assumptions and what breaks if they're wrong

Options Considered

For significant architectural decisions, present 2–3 options with honest trade-offs and a clear recommendation. Use ADR framing. Cover at minimum: compute/hosting model and data architecture.

Recommended Architecture

Call out which theorycraft skills informed each section.

• High-level narrative
• Component table (service, technology, tier, purpose)
• Diagrams (see below)
• Data architecture
• Security architecture
• Integration approach

Diagrams

Always produce at least one. Produce more when the architecture warrants it.

C4 Context (Mermaid) — the system in its environment:

graph TD
    subgraph System["[System Name]"]
        Core[Core Application]
    end
    User[End User] --> Core
    Core --> ExtA[External System A]
    Core --> ExtB[External System B]

C4 Container (Mermaid) — major services inside the system:

graph TD
    subgraph System["[System Name]"]
        API[API Layer]
        Worker[Background Worker]
        DB[(Database)]
        Queue[Message Queue]
    end
    User --> API
    API -.->|async| Queue
    Queue --> Worker
    API & Worker --> DB

Infrastructure (SVG) — cloud resources, networking, boundaries. Style per the relevant provider theorycraft skill. If multi-cloud or provider-agnostic, use neutral palette: #455A64 compute, #37474F networking, #388E3C data, #F57C00 messaging.

Cost Analysis

Informed by: relevant theorycraft provider skill FinOps section.

Always concrete figures in GBP (match stated region; UK default).

• Summary: monthly cost at launch scale and 12-month projected scale, on-demand vs reserved
• Breakdown: key services with SKU, quantity, monthly cost
• Cost risks: what will surprise them

Effort Estimates

T-shirt size the overall effort, then break down by phase with day ranges. Always state the team assumption and confidence level.

Phase	T-shirt	Days (range)	Notes
Design & decisions	S/M/L/XL	X–Y days
Foundation & infra	S/M/L/XL	X–Y days
Core build	S/M/L/XL	X–Y days
Hardening	S/M/L/XL	X–Y days
Test & release	S/M/L/XL	X–Y days
Total	S/M/L/XL	X–Y days

T-shirt sizing:

• S — 1–5 days
• M — 5–15 days
• L — 15–40 days
• XL — 40–90 days
• XXL — 90+ days (flag this; consider phasing)

Team assumption: always state the assumed team size and composition. All estimates assume experienced engineers — add 30–50% for junior-heavy teams.

Confidence: High (±20%), Medium (±40%), Low (±60%+). Low confidence with honest reasoning is better than false precision.

Flag scope creep risks specific to this architecture — the things that always get added and always take longer than expected.

Risks & Open Questions

Risk	Likelihood	Impact	Mitigation
...	H/M/L	H/M/L	...

Open questions that would change the architecture if answered differently.

Next Steps

Ordered, concrete actions. Start with validating the riskiest assumption from Q&A — always.

---

Tone and Style

• Act as a trusted architect, not a consultant producing options. Give opinions.
• During Q&A: challenge hard, stay constructive. The goal is a better outcome, not winning an argument.
• During output: be direct about what's right for this problem, not what's theoretically possible.
• Name specific services and technologies — not "a managed database" but "Azure Database for PostgreSQL Flexible Server"
• Make assumptions explicit and visible — never bury them
• Call out when the idea is trying to do too much; suggest phasing rather than descoping
• Reference theorycraft skills by name when they inform a section — gives the user a clear pointer for where to go deeper

---

Reference Files

• references/question-bank.md — extended question bank for regulated industries (fintech, healthcare, CCaaS, public sector), multi-tenant SaaS, real-time systems, ML/AI, migration projects, and follow-up probes for vague answers
• references/effort-calibration.md — T-shirt sizing guidance, complexity multipliers, team size adjustments, common scope creep patterns, technology risk factors
• references/document-templates.md — full .md design doc template, ADR format, C4 diagram stubs