detections/.cursor/skills/plan/steps/02_solution-analysis.md

## Step 2: Solution Analysis

**Role**: Professional software architect
**Goal**: Produce `architecture.md`, `system-flows.md`, `data_model.md`, and `deployment/` from the solution draft
**Constraints**: No code, no component-level detail yet; focus on system-level view

### Phase 2a.0: Glossary & Architecture Vision (BLOCKING)

**Role**: Software architect + business analyst
**Goal**: Align the AI's mental model of the project with the user's intent BEFORE drafting `architecture.md`. Capture domain terminology and the user's high-level architecture vision so every downstream artifact (architecture, components, flows, tests, epics) is grounded in confirmed user intent — not in AI inference.

**Inputs**:
- `_docs/00_problem/problem.md`, `acceptance_criteria.md`, `restrictions.md`
- `_docs/00_problem/input_data/*`
- `_docs/01_solution/solution.md` (and any earlier `solution_draft*.md` siblings)
- Any blackbox-test findings produced in Step 1

**Outputs**:
- `_docs/02_document/glossary.md` (NEW)
- A confirmed "Architecture Vision" paragraph + bullet list held in working memory and used as the spine of Phase 2a's `architecture.md`

**Procedure**:

1. **Draft glossary** — extract project-specific terminology from inputs (NOT generic software terms). Include:
   - Domain entities, processes, and roles
   - Acronyms / abbreviations
   - Internal codenames or product names
   - Synonym pairs in active use (e.g., "flight" vs. "mission")
   - Stakeholder personas referenced in problem.md
   Each entry: one-line definition, plus a parenthetical source (`source: problem.md`, `source: solution.md §3`).
   Skip terms that have a single well-known industry meaning (REST, JSON, etc.).

2. **Draft architecture vision** — synthesize from inputs:
   - **One paragraph**: what the system is, who uses it, the shape of the runtime topology (monolith / services / pipeline / library / hybrid).
   - **Components & responsibilities** (one-line each). At this stage these are *intent-level*, not the formal decomposition that Step 3 produces.
   - **Major data flows** (one or two sentences each).
   - **Architectural principles / non-negotiables** the user has implied (e.g., "DB-driven config", "no per-component state outside Redis", "all UI traffic via REST + SSE only").
   - **Open architectural questions** the AI cannot resolve from inputs alone.

3. **Present condensed view** to the user (NOT the full draft files — a synopsis only):

   ```
   ══════════════════════════════════════
    REVIEW: Glossary + Architecture Vision
   ══════════════════════════════════════
    Glossary (N terms drafted):
      - <Term>: <one-line definition>
      - ...
    Architecture Vision:
      <one-paragraph synopsis>

      Components / responsibilities:
        - <component>: <one-line>
        - ...

      Principles / non-negotiables:
        - <principle>
        - ...

      Open questions (AI could not resolve):
        - <q1>
        - <q2>
   ══════════════════════════════════════
    A) Looks correct — write glossary.md, use vision for Phase 2a
    B) I want to add / correct entries (provide diffs)
    C) Answer the open questions first, then re-present
   ══════════════════════════════════════
    Recommendation: pick C if open questions exist, otherwise A
   ══════════════════════════════════════
   ```

4. **Iterate**:
   - On B → integrate the user's diffs/additions, re-present the condensed view, loop until A.
   - On C → ask the listed open questions one round (M4-style batch), integrate answers, re-present.
   - **Do NOT proceed to step 5 until the user picks A.**

5. **Save**:
   - Write `_docs/02_document/glossary.md` with terms in alphabetical order. Include a top-line `**Status**: confirmed-by-user` and the date.
   - Hold the confirmed vision (paragraph + components + principles) in working memory; Phase 2a will materialize it into `architecture.md` and **must** preserve every confirmed principle and component intent verbatim.

**Self-verification**:
- [ ] Every glossary entry traces to at least one input file (no invented terms)
- [ ] Every component listed in the vision is one the inputs reference
- [ ] All open questions are either answered or explicitly deferred (with the user's acknowledgement)
- [ ] User picked option A on the latest condensed view

**BLOCKING**: Do NOT proceed to Phase 2a until `glossary.md` is saved and the user has confirmed the architecture vision.

### Phase 2a: Architecture & Flows

1. Read all input files thoroughly
2. Incorporate findings, questions, and insights discovered during Step 1 (blackbox tests)
3. **Apply confirmed vision from Phase 2a.0**: the architecture document must include a top-level `## Architecture Vision` section that contains the user-confirmed paragraph, components, and principles verbatim. The rest of `architecture.md` (tech stack, deployment model, NFRs, ADRs) builds on top of that section, never contradicts it
4. Research unknown or questionable topics via internet; ask user about ambiguities
5. Document architecture using `templates/architecture.md` as structure
6. Document system flows using `templates/system-flows.md` as structure

**Self-verification**:
- [ ] `architecture.md` opens with a `## Architecture Vision` section matching Phase 2a.0
- [ ] Architecture covers all capabilities mentioned in solution.md
- [ ] System flows cover all main user/system interactions
- [ ] No contradictions with problem.md, restrictions.md, or the confirmed vision
- [ ] Technology choices are justified
- [ ] Blackbox test findings are reflected in architecture decisions
- [ ] Every term used in `architecture.md` that is project-specific appears in `glossary.md`

**Save action**: Write `architecture.md` and `system-flows.md`

**BLOCKING**: Present architecture summary to user. Do NOT proceed until user confirms.

### Phase 2b: Data Model

**Role**: Professional software architect
**Goal**: Produce a detailed data model document covering entities, relationships, and migration strategy

1. Extract core entities from architecture.md and solution.md
2. Define entity attributes, types, and constraints
3. Define relationships between entities (Mermaid ERD)
4. Define migration strategy: versioning tool (EF Core migrations / Alembic / sql-migrate), reversibility requirement, naming convention
5. Define seed data requirements per environment (dev, staging)
6. Define backward compatibility approach for schema changes (additive-only by default)

**Self-verification**:
- [ ] Every entity mentioned in architecture.md is defined
- [ ] Relationships are explicit with cardinality
- [ ] Migration strategy specifies reversibility requirement
- [ ] Seed data requirements defined
- [ ] Backward compatibility approach documented

**Save action**: Write `data_model.md`

### Phase 2c: Deployment Planning

**Role**: DevOps / Platform engineer
**Goal**: Produce deployment plan covering containerization, CI/CD, environment strategy, observability, and deployment procedures

Use the `/deploy` skill's templates as structure for each artifact:

1. Read architecture.md and restrictions.md for infrastructure constraints
2. Research Docker best practices for the project's tech stack
3. Define containerization plan: Dockerfile per component, docker-compose for dev and tests
4. Define CI/CD pipeline: stages, quality gates, caching, parallelization
5. Define environment strategy: dev, staging, production with secrets management
6. Define observability: structured logging, metrics, tracing, alerting
7. Define deployment procedures: strategy, health checks, rollback, checklist

**Self-verification**:
- [ ] Every component has a Docker specification
- [ ] CI/CD pipeline covers lint, test, security, build, deploy
- [ ] Environment strategy covers dev, staging, production
- [ ] Observability covers logging, metrics, tracing, alerting
- [ ] Deployment procedures include rollback and health checks

**Save action**: Write all 5 files under `deployment/`:
- `containerization.md`
- `ci_cd_pipeline.md`
- `environment_strategy.md`
- `observability.md`
- `deployment_procedures.md`