architecture-reasoning

Architecture Reasoning Protocol

EXTREMELY_IMPORTANT: This is a MANDATORY protocol, not a suggestion. Follow every step. Do not skip steps. Do not combine steps. Do not summarize. Work through each gate in order.

You're making a structural decision. These are expensive to reverse. Reason carefully.

STEP 1 — Classify the decision's reversibility

Type 1 (one-way door): Database schema, public API contract, core data model, infrastructure provider, primary language/framework choice. → Requires full protocol below. Do not rush.

Type 2 (two-way door): Internal module boundaries, library choices, config format, naming conventions, internal API between your own services. → Run abbreviated protocol (Steps 2 and 5 only). Decide fast, iterate.

STEP 2 — Map what exists

Before designing anything new, understand what's already there.

• What components exist today?
• What are the current boundaries? (services, modules, packages)
• Where are the current pain points? (coupling, bottlenecks, tech debt)
• What constraints does the existing system impose on new design?

If this is greenfield (nothing exists), state that and skip to Step 3.

STEP 3 — Evaluate build vs buy vs adopt

For each major component in the design, ask:

Question	If YES →
Does a well-maintained OSS/SaaS solution exist?	Evaluate adopting it
Is this a commodity capability (auth, email, storage, logging)?	Buy/adopt, don't build
Is this your core differentiator?	Build it — this is where your value lives
Will you need to customize it beyond what exists?	Build if you'd be modifying its core rather than configuring its edges — a deep fork costs more than owning the code

State each component's classification: BUILD / BUY / ADOPT.

STEP 4 — Boundary analysis

For every proposed module or service boundary, verify:

Cohesion test: "Can I describe this module's purpose in one sentence without 'and'?"

• YES → Boundary is well-placed.
• NO → Module does too many things. Split it.

Coupling test: "If I change module A's internals, does module B need to change?"

• NO → Good separation.
• YES → Missing abstraction at the boundary. Add an interface.

Data ownership test: "Does exactly one module own each piece of data?"

• YES → Clean ownership.
• NO → Shared mutable state. This is where bugs breed. Assign a single owner.

Communication test: "How do these modules talk?"

• Direct function calls → Fine for monolith. Tight coupling for services.
• Events/messages → Loose coupling. Good for independent deployment.
• Shared database → Almost always wrong. Each module owns its data.

STEP 5 — Spot the bottleneck

Apply Theory of Constraints: which single component limits the system's overall capacity? Everything else is irrelevant until that bottleneck is addressed.

• Where does data queue up?
• Which step is slowest?
• Which component fails first under load?

Name the bottleneck explicitly. Your architecture must address it.

Output format

ARCHITECTURE ANALYSIS
├── Decision type: [Type 1 / Type 2]
├── Components: [BUILD: x, y | BUY: z | ADOPT: w]
├── Boundaries: [cohesion ✓/✗ | coupling ✓/✗ | data ownership ✓/✗]
├── Bottleneck: [identified component and why]
├── Key risk: [the one thing most likely to require rework]
└── Confidence: [HIGH / MEDIUM / LOW]

For Type 1 decisions: do NOT proceed to implementation planning until all 5 steps are complete and the user has confirmed the architecture.

Type 1 decisions with MEDIUM or LOW confidence require explicit human sign-off with the risks stated clearly. Do not bury risks in optimistic framing.

Superpowers handoff

After architecture analysis is complete and user confirms:

If Superpowers is installed → invoke Skill(superpowers:brainstorming) if design exploration is needed, or Skill(superpowers:writing-plans) if the architecture is confirmed. Pass your build/buy/adopt classifications, boundary analysis, and bottleneck identification as context. Do NOT write the implementation plan inside this skill. PRAXIS architected. Superpowers plans and builds.

If Superpowers is NOT installed → proceed to implementation planning yourself using the architecture analysis as the foundation.