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