architecture-analysis

core process

Phase 0 — Context Assessment

1. **Check existing decisions:** - SPEC.md exists? Read Architecture Decisions. - architecture/ARCHITECTURE.md exists? Don't contradict without approval.
2. **Assess complexity:** - Simple (single-page, no backend, no auth) → Lightweight rec. - Non-trivial (multi-page, data persistence, auth, API) → Full analysis. - Complex (multi-team, high scale, regulated, distributed) → Extended + trade-off matrix.
3. **Check health:** Existing codebase → Verify HEALTH-CHECK.md recent.
---

Phase 1 — Discovery

→ **See DISCOVERY-GUIDE.md for complete interview (6 questions + assumptions + complexity assessment).**
Summary:

• Surface 4+ technical assumptions. Confirm before proceeding.
• Ask: scale, team, ops, data, latency, constraints.
• Lock context with explicit user confirmation.

---


Phase 2 — Candidate Research


Research before proposing. Never invent from memory.
1. **Identify candidates:** - Search "best [type] framework [current year] [scale]" - Verify maintenance status (commits, issues, releases) - **Always use current year.**
2. **Find benchmarks:** - Performance under similar load - Migration stories from user's current stack - Known limitations for this use case
3. **Present findings concisely:** ` RESEARCH FINDINGS: - [Tech A]: Dominant in [domain], excellent for [strength]. Limitation: [weakness]. - [Tech B]: Rising adoption, great for [strength]. Limitation: [weakness]. → Any of this change your thinking? `
4. **Persist research artifact:** Save findings to architecture/research.md with evaluated technologies, benchmarks, links, and decision context. This artifact survives session boundaries and compaction.
` # Research: [Project Name] > Generated by architecture-analysis Phase 2
## Technologies Evaluated - [Tech A]: [version], [strength], [weakness], [source link] - [Tech B]: [version], [strength], [weakness], [source link]
## Benchmarks - [Metric]: [Tech A] = [value], [Tech B] = [value]
## Key Sources - [Title](URL) `
Research without documentation is lost context. Only skip if user explicitly says "do not persist."
---


Phase 3 — Generate Options


Exactly 2 or 3 options. Never one (false certainty). Never four+ (analysis paralysis).
Each option includes:
| Field | Description | |---|---| | **Name** | Short, memorable label | | **Stack** | Concrete tools with versions | | **Pattern** | MVC, MVVM, Clean, Hexagonal, Serverless, Modular Monolith | | **Pros** | 3 genuine advantages FOR THIS PROJECT | | **Contras** | 3 genuine disadvantages (honest, even if kills sale) | | **Ideal for** | Scenario where this is clear winner | | **Main risk** | Biggest thing that could go wrong |
---


Phase 4 — Critical Challenge


→ **See CHALLENGE-GUIDE.md for challenge patterns and presentation format.**
Senior engineering happens here. Don't blindly accept user preference.
Analyze user's preference against options. Challenge assumptions.
If user has no preference: Recommend based on context.
---


Phase 5 — Recommendation & Lock


Present ONE recommendation with honest confidence.
` RECOMMENDATION:
Based on [specific user answers], recommend: → Option [X]: [Name]
Justification:
• [Reason 1 tied to context]
• [Reason 2 tied to context]
• [Trade-off accepted: sacrifice X because Y matters more]

Confidence: HIGH / MEDIUM / LOW
• HIGH: Clear match
• MEDIUM: Good match, one significant risk
• LOW: All options have serious trade-offs

→ Accept? Reply "yes" or ask for changes. `
If rejected: Back to Phase 3. Max 2 cycles. If still undecided: "We need to lock a decision. Which option feels least wrong?"
---


Phase 6 — Document Decision


→ **See ARCHITECTURE-TEMPLATE-GUIDE.md for SPEC.md section + ARCHITECTURE.md template.**
Architecture without documentation is fiction.
1. Update SPEC.md Architecture Decisions section. 2. Create architecture/ARCHITECTURE.md with stack, pattern, structure, risks, migration path.
---


example


User: "I want microservices for my MVP."
Agent: 1. Phase 1: Team = 2 devs, scale = 0, timeline = 2 months. 2. Phase 2: Research microservices overhead vs monolith speed. 3. Phase 3: Options — A: Microservices (K8s), B: Modular Monolith (Next.js), C: Serverless. 4. Phase 4: "With 2 devs and 2 months, microservices = 40% time on infrastructure. Modular monolith separates concerns now, extract services later." 5. Phase 5: Recommend B. User accepts. 6. Phase 6: Document in SPEC.md + architecture/ARCHITECTURE.md.
---


common rationalizations


| Excuse | Response | |---|---| | "User already chose stack, go with it." | Senior engineers challenge bad decisions. | | "Microservices are modern, so better." | Modern != appropriate. Context determines correctness. | | "I know React best, recommend it." | Familiarity bias harms user. Recommend what fits. | | "Just an MVP, architecture doesn't matter." | MVPs become production. "Speed" decisions become permanent. | | "Kubernetes is industry standard." | Standard for Google ≠ standard for 3-person startup. | | "User asked for implementation, not options." | Rotten foundation = wasted implementation. |
---


red flags



• Recommends stack without asking scale, team, constraints.
• Presents only one option.
• Agrees with user without analyzing trade-offs.
• Uses "best practice" without qualifying context.
• Decisions not documented in SPEC.md.
• Skips discovery, jumps to "just use Next.js."
• Recommends technology heard of but not researched.

---


verification



• [ ] ≥2 options generated with honest pros AND cons.
• [ ] User context (scale, team, constraints) discovered.
• [ ] Critical challenge questioned ≥1 assumption.
• [ ] Single option recommended with justification tied to context.
• [ ] User explicitly accepted.
• [ ] SPEC.md has Architecture Decisions section.
• [ ] architecture/ARCHITECTURE.md exists with stack, pattern, structure, risks.
• [ ] architecture/research.md exists with evaluated technologies, benchmarks, and sources.