@miniidealab/openlogos 0.3.0 → 0.3.2

package/skills/product-designer/SKILL.en.md

@@ -0,0 +1,228 @@
+# Skill: Product Designer
+
+> Based on scenarios from the Phase 1 requirements document, refine interaction flows and feature specifications, and generate product prototypes. The prototype format automatically adapts to the product type (Web/CLI/Library, etc.). Scenario numbering stays consistent with Phase 1.
+
+## Trigger Conditions
+
+- User requests a product design document or feature specification
+- User requests prototypes or interaction design
+- User mentions "Phase 2", "product design layer", or "WHAT"
+- Requirements document exists (with scenario definitions) and solution design needs to begin
+
+## Core Capabilities
+
+1. **Identify the product type** and determine the corresponding prototype format (see Product Types and Prototype Strategy below)
+2. Design information architecture (page structure / command structure / API structure)
+3. Use Phase 1 scenarios as the backbone to refine interaction flows and feature specifications
+4. Supplement each scenario with interaction-level GIVEN/WHEN/THEN acceptance criteria
+5. Generate prototypes appropriate for the product type
+6. When a scenario is too coarse-grained, split it into sub-scenarios (`S01.1`, `S01.2`)
+
+## Product Types and Prototype Strategy
+
+Before executing this Skill, first determine the product type (inferred from the requirements document's constraints and boundaries, and the `tech_stack` in `logos-project.yaml`), then select the corresponding prototype format:
+
+| Product Type | Typical Features | Prototype Format | Interaction Spec Focus |
+|---------|---------|---------|-------------|
+| **Web Application** | Has UI pages, user login | Interactive HTML pages | Page navigation, form validation, state changes |
+| **CLI Tool** | Terminal commands, no GUI | Terminal interaction examples (command + output simulation) | Command format, parameter design, output format, error messages |
+| **AI Skills / Conversational Product** | User interacts with AI via natural language | Dialogue flowchart + sample dialogue scripts | Dialogue steps, AI questioning strategy, deliverable format |
+| **Library / SDK** | Called by other programs | API usage examples (code snippets) | Public interfaces, parameter design, return values, error codes |
+| **Mobile Application** | Mobile UI | HTML pages (mobile viewport) | Gesture interaction, navigation patterns, offline state |
+| **Hybrid** | Combination of multiple deliverables | Select the corresponding format for each deliverable | Interaction handoffs between deliverables |
+
+## Execution Steps
+
+### Step 1: Read the Requirements Document and Identify the Product Type
+
+Read the Phase 1 requirements document and extract:
+- Scenario list (`S01`, `S02`...) and priorities
+- Constraints and boundaries → determine product type
+- `tech_stack` in `logos-project.yaml` → confirm technical form
+
+Output the product type determination and rationale for the prototype strategy selection.
+
+### Step 2: Design Information Architecture
+
+Design architecture at different levels based on the product type:
+
+- **Web Application**: Page structure, navigation hierarchy, route design
+- **CLI Tool**: Command tree structure, subcommand hierarchy, global options
+- **AI Skills**: Skill trigger relationships, dialogue step orchestration, deliverable dependency chain
+- **Library / SDK**: Module structure, public API grouping
+
+### Step 3: Refine Interaction Specifications Per Scenario
+
+Define complete interaction details for each scenario (see format examples below). Different product types emphasize different interaction dimensions.
+
+### Step 4: Supplement Interaction-Level Acceptance Criteria
+
+Building on the Phase 1 GIVEN/WHEN/THEN, refine down to the interaction element level.
+
+### Step 5: Generate Prototypes
+
+Generate prototypes in the format corresponding to the product type (see examples).
+
+### Step 6: Output the Product Design Document
+
+Organize by scenario, with each scenario containing interaction specifications + corresponding prototype.
+
+## Scenario Elaboration Examples
+
+### Web Application Example
+
+```markdown
+### S01: Email Registration — Interaction Specification
+
+**Pages Involved**: Registration page, email verification waiting page, verification success page
+
+**Interaction Flow**:
+1. User clicks "Sign Up" on the homepage → redirected to the registration page
+2. Registration page contains: email input, password input, confirm password input, sign up button
+3. Real-time validation: email format, password length ≥ 8, both passwords match
+4. Successful submission → redirected to email verification waiting page
+
+#### Acceptance Criteria (Interaction Level)
+
+##### Normal: Successful Registration
+- **GIVEN** User is on the registration page, all fields are empty
+- **WHEN** User enters test@example.com, password "Pass1234", confirm password "Pass1234", clicks "Sign Up" button
+- **THEN** "Sign Up" button enters loading state, redirects to email verification waiting page after 1-3 seconds
+```
+
+**Prototype**: `01-register-prototype.html` (interactive HTML page)
+
+### CLI Tool Example
+
+````markdown
+### S01: CLI Project Initialization — Interaction Specification
+
+**Command Format**: `openlogos init [name]`
+
+**Parameter Design**:
+| Parameter | Type | Required | Default | Description |
+|------|------|------|--------|------|
+| name | string | No | Current directory name | Project name |
+
+**Interaction Flow**:
+1. User runs `openlogos init my-project` in the terminal
+2. CLI checks if `logos/logos.config.json` already exists
+3. Does not exist → creates directory structure, outputs created file list line by line
+4. Exists → outputs error message and exits
+
+**Terminal Output Simulation**:
+
+Normal path:
+```
+$ openlogos init my-project
+
+Creating OpenLogos project structure...
+
+  ✓ logos/resources/prd/1-product-requirements/
+  ✓ logos/resources/prd/2-product-design/
+  ✓ logos/resources/prd/3-technical-plan/1-architecture/
+  ✓ logos/resources/prd/3-technical-plan/2-scenario-implementation/
+  ✓ logos/resources/api/
+  ✓ logos/resources/database/
+  ✓ logos/resources/scenario/
+  ✓ logos/changes/
+  ✓ logos/logos.config.json
+  ✓ logos/logos-project.yaml
+  ✓ AGENTS.md
+  ✓ CLAUDE.md
+
+Project initialized. Next steps:
+  1. Edit logos/logos.config.json to configure your project
+  2. Start with Phase 1: tell AI "Help me write requirements"
+  3. Run `openlogos status` to check progress at any time
+```
+
+Error path:
+```
+$ openlogos init
+Error: logos/logos.config.json already exists in current directory.
+This directory has already been initialized as an OpenLogos project.
+```
+
+#### Acceptance Criteria (Interaction Level)
+
+##### Normal: Brand New Project
+- **GIVEN** Current directory has no `logos/logos.config.json`
+- **WHEN** User runs `openlogos init my-project`
+- **THEN** Terminal outputs the 12 created files/directories line by line, ends with "Next steps" guidance, exit code is 0
+
+##### Error: Already Initialized
+- **GIVEN** Current directory already contains `logos/logos.config.json`
+- **WHEN** User runs `openlogos init`
+- **THEN** Terminal outputs a red error message, no files are created, exit code is 1
+````
+
+**Prototype**: `01-init-terminal.md` (terminal interaction simulation document)
+
+### AI Skills / Conversational Product Example
+
+```markdown
+### S02: AI-Assisted Requirements Writing — Interaction Specification
+
+**Trigger Method**: User enters natural language in an AI coding tool
+
+**Dialogue Flow**:
+1. User says "Help me write requirements"
+2. AI reads the prd-writer Skill
+3. AI follows up: "Please first tell me your product positioning — what problem does this product solve, and for whom?"
+4. User describes the product idea
+5. AI follows up: "Who is the core user? Can you describe a specific person?"
+6. User describes the user persona
+7. AI consolidates the information and begins outputting a structured requirements document
+8. After output, AI asks: "The requirements draft has been generated. Please review it and let me know what needs to be changed."
+
+**AI Behavioral Guidelines**:
+- No more than 3 rounds of follow-up questions, each round focusing on 1 key piece of information
+- If the user provides sufficient information in the first message, skip follow-up questions and output directly
+- Output document format strictly follows the prd-writer specification
+
+#### Acceptance Criteria (Interaction Level)
+
+##### Normal: Sufficient Information
+- **GIVEN** User describes product positioning, target users, and core pain points in the first message
+- **WHEN** AI begins executing the prd-writer Skill
+- **THEN** AI directly outputs a structured requirements document without follow-up questions
+
+##### Normal: Insufficient Information
+- **GIVEN** User only says "Help me write requirements"
+- **WHEN** AI begins executing the prd-writer Skill
+- **THEN** AI asks about product positioning (round 1) → user responds → AI asks about target users (round 2) → user responds → AI outputs requirements document
+```
+
+**Prototype**: `02-prd-writer-dialogue.md` (dialogue flow script)
+
+## Output Specification
+
+- Feature specs: `logos/resources/prd/2-product-design/1-feature-specs/`
+- Prototypes: `logos/resources/prd/2-product-design/2-page-design/`
+- Design documents and prototypes appear in pairs: `{number}-{name}-design.md` + `{number}-{name}-prototype.{ext}`
+  - Web Application: `.html`
+  - CLI Tool: `-terminal.md` (terminal interaction simulation)
+  - AI Skills: `-dialogue.md` (dialogue flow script)
+  - Library / SDK: `-api-examples.md` (usage examples)
+- **Scenario numbering must be consistent with Phase 1**; use sub-numbers when splitting (`S01.1`)
+
+## Best Practices
+
+- **Scenarios are the backbone**: Don't organize documents by "pages" or "commands" — organize by "scenarios"
+- **Phase 1 acceptance criteria are the input**: Phase 2 does not rewrite acceptance criteria; it refines Phase 1 criteria down to the interaction element level
+- **Sub-scenario splits need justification**: Only split when a Phase 1 scenario truly contains two independent interaction paths
+- **CLI "prototypes" are terminal output simulations**: No HTML needed — use code blocks to simulate terminal input/output
+- **AI Skills "prototypes" are dialogue scripts**: Simulate multi-turn conversations between the user and AI, specifying AI behavior at each node
+- **Hybrid products are organized by scenario**: Within the same product, CLI scenarios use terminal simulations while Web scenarios use HTML — no need for a uniform format
+- **Nested Markdown code blocks**: When the document content itself contains ` ``` ` code fences (e.g., AI outputting code snippets in dialogue scripts, or nested command output in terminal simulations), **the outer fence must use 4 backticks** (` ```` `), keeping the inner fence at 3. This is standard Markdown syntax to prevent the parser from misjudging nesting levels and causing formatting issues. The CLI Tool example above demonstrates this rule.
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Create product design based on the requirements document`
+- `Help me design the interaction flow and prototype for S01`
+- `Help me create the product design for all scenarios`
+- `Help me design the CLI command interaction flow`
+- `Help me design the AI Skill dialogue flow`

package/skills/project-init/SKILL.en.md

@@ -0,0 +1,163 @@
+# Skill: Project Init
+
+> Initialize a project structure following the OpenLogos methodology, generating configuration files, AI instruction files, and standard directories.
+
+## Trigger Conditions
+
+- User requests creating a new project or initializing a project structure
+- User mentions "openlogos init" or "initialize project"
+- No `logos/logos.config.json` exists in the current directory
+
+## Core Capabilities
+
+1. Create the `logos/` directory and its standard substructure
+2. Generate the `logos/logos.config.json` configuration file
+3. Generate the `logos/logos-project.yaml` AI collaboration index
+4. Generate `AGENTS.md` / `CLAUDE.md` AI instruction files (in the root directory)
+5. Create the `logos/changes/` change management directory
+
+## Execution Steps
+
+### Step 1: Gather Project Information
+
+Confirm the following information with the user:
+
+- **Project name**: Used for the `name` field in `logos/logos.config.json`
+- **Project description**: A one-sentence description
+- **Tech stack**: Main framework, language, database, deployment platform
+- **Document modules**: Whether additional modules are needed beyond the default prd/api/scenario/database
+
+If the user does not provide these, use reasonable defaults.
+
+### Step 2: Create Directory Structure
+
+```
+project-root/
+└── logos/
+    ├── resources/
+    │   ├── prd/
+    │   │   ├── 1-product-requirements/
+    │   │   ├── 2-product-design/
+    │   │   │   ├── 1-feature-specs/
+    │   │   │   └── 2-page-design/
+    │   │   └── 3-technical-plan/
+    │   │       ├── 1-architecture/
+    │   │       └── 2-scenario-implementation/
+    │   ├── api/
+    │   ├── database/
+    │   └── scenario/
+    └── changes/
+```
+
+### Step 3: Generate logos/logos.config.json
+
+```json
+{
+  "name": "{project name}",
+  "description": "{project description}",
+  "documents": {
+    "prd": {
+      "label": { "en": "Product Docs", "zh": "产品文档" },
+      "path": "./resources/prd",
+      "pattern": "**/*.{md,html,htm,pdf}"
+    },
+    "api": {
+      "label": { "en": "API Docs", "zh": "API 文档" },
+      "path": "./resources/api",
+      "pattern": "**/*.{yaml,yml,json}"
+    },
+    "scenario": {
+      "label": { "en": "Scenarios", "zh": "业务场景" },
+      "path": "./resources/scenario",
+      "pattern": "**/*.json"
+    },
+    "database": {
+      "label": { "en": "Database", "zh": "数据库" },
+      "path": "./resources/database",
+      "pattern": "**/*.sql"
+    }
+  }
+}
+```
+
+> The `path` field is relative to the directory where `logos.config.json` itself resides (i.e., `logos/`), so `./resources/prd` points to `logos/resources/prd`.
+
+### Step 4: Generate logos/logos-project.yaml
+
+```yaml
+project:
+  name: "{project name}"
+  description: "{project description}"
+  methodology: "OpenLogos"
+
+tech_stack:
+  framework: "{framework provided by user}"
+  language: "{language provided by user}"
+  # ... populate based on user-provided information
+
+resource_index: []
+  # Initially empty; entries are added incrementally as documents are produced
+
+conventions:
+  - "Follow the OpenLogos three-layer progression model (Why → What → How)"
+  - "Every change must first create a change proposal in logos/changes/"
+```
+
+### Step 5: Generate AGENTS.md (Root Directory)
+
+Generate AGENTS.md based on the content from Step 3 and Step 4, placed in the **project root directory**:
+
+```markdown
+# AI Assistant Instructions
+
+This project follows the **OpenLogos** methodology.
+Read `logos/logos-project.yaml` first to understand the project resource index.
+
+## Project Context
+- Config: `logos/logos.config.json`
+- Resource Index: `logos/logos-project.yaml`
+- Tech Stack: {extracted from logos-project.yaml}
+
+## Methodology Rules
+1. Never write code without first completing the design documents
+2. Follow the Why → What → How progression
+3. All API designs must originate from scenario sequence diagrams
+4. All code changes must have corresponding API orchestration tests
+5. Use the Delta change workflow for iterations (see logos/changes/ directory)
+
+## Conventions
+{extracted from conventions in logos-project.yaml}
+```
+
+Also generate `CLAUDE.md` with identical content to AGENTS.md.
+
+### Step 6: Output Initialization Report
+
+Report to the user which files and directories were created, and provide next-step suggestions:
+
+1. Edit `logos/logos.config.json` to refine the project configuration
+2. Start with Phase 1: Write the requirements document
+3. Use the `prd-writer` Skill to assist with writing
+
+## Output Specification
+
+- `logos/logos.config.json`: Valid JSON, conforming to `spec/logos.config.schema.json`
+- `logos/logos-project.yaml`: Valid YAML
+- `AGENTS.md` / `CLAUDE.md`: Markdown format, located in the project root directory
+- All directories under `logos/` are created; empty directories contain `.gitkeep`
+
+## Best Practices
+
+- **Don't over-configure**: Keep configuration minimal during initialization; let users refine it gradually during use
+- **resource_index starts empty**: Add entries as documents are produced, avoiding meaningless placeholder content
+- **Keep AGENTS.md concise**: Only include project-specific information; use fixed templates for universal methodology rules
+- **Prioritize creating the directory structure**: The `logos/` directory structure is the first step in adopting the methodology — more important than any document
+- **Low intrusiveness**: All methodology assets are contained within `logos/`, keeping the project's own structure clean
+
+## Recommended Prompts
+
+The following prompts can be copied directly for use with AI:
+
+- `Help me initialize an OpenLogos project`
+- `Initialize this project with OpenLogos, the project name is xxx`
+- `Help me integrate OpenLogos into an existing project`

package/skills/scenario-architect/SKILL.en.md

@@ -0,0 +1,214 @@
+# Skill: Scenario Architect
+
+> Expand business scenarios defined in Phase 1/2 into technical sequence diagrams, letting API design emerge naturally, and design comprehensive exception cases. Scenario numbering follows Phase 1 definitions.
+
+## Trigger Conditions
+
+- User requests drawing sequence diagrams, designing business scenarios, or performing scenario modeling
+- User mentions "Phase 3 Step 1", "scenario-driven", "technical plan design"
+- Requirements documents and product design documents (with scenario definitions) already exist, ready to begin technical implementation
+- User specifies a particular scenario number (e.g., S01) to be expanded into a sequence diagram
+
+## Core Capabilities
+
+1. Read scenario definitions and acceptance criteria from Phase 1/2 as input for sequence diagrams
+2. Draw Mermaid sequence diagrams for each scenario (strictly following numbering conventions)
+3. Write explanatory notes for key steps (explaining "why" rather than "what")
+4. Identify exception conditions for each step and design structured exception cases
+5. Generate scenario overview documents (scenario map + scenario index)
+
+## Linking with Phase 1/2
+
+**Phase 3 does not identify scenarios from scratch.** Scenarios are defined in Phase 1 (`S01`, `S02`...), interaction flows are refined in Phase 2, and technical architecture and technology choices are established in Step 0. The job of Phase 3 Step 1 is to expand the same scenario from an "interaction perspective" into a "technical perspective". The participants in the sequence diagram should align with the system components in the architecture diagram:
+
+| Input (from Phase 1/2) | Output (Phase 3) |
+|------------------------|----------------|
+| Scenario number and name | Sequence diagram title retains the number |
+| Trigger conditions | Starting arrow of the sequence diagram |
+| Main path description | Step sequence in the sequence diagram |
+| GIVEN/WHEN/THEN (business level) | Behavior description of sequence diagram steps |
+| Exception acceptance criteria | EX exception cases (technical level) |
+| Pages and interactions involved (Phase 2) | Participant identification |
+
+## Execution Steps
+
+### Step 1: Load Scenario Context
+
+Read scenario definitions from the Phase 1 requirements document, Phase 2 product design document, and Phase 3 Step 0 technical architecture summary. **Do not reinvent scenarios**—directly reuse existing numbers and descriptions. Participant naming should be consistent with the system components in the architecture diagram.
+
+Confirm the following for each scenario:
+- **Scenario number**: Reuse Phase 1's `S01`, `S02`... (or Phase 2 sub-scenarios `S01.1`)
+- **Participants**: Identify which system components are involved from Phase 2's interaction flows
+- **Main path**: Extract the normal flow from Phase 1/2 acceptance criteria
+- **Known exceptions**: Extract from Phase 1/2 exception acceptance criteria
+
+### Step 2: Draw Sequence Diagrams
+
+Draw Mermaid sequence diagrams for each scenario, **strictly following these conventions**:
+
+**Numbering conventions**:
+- Every arrow must have a `Step N:` number prefix
+- Numbering starts at 1 and increments consecutively
+- Each arrow includes a one-line behavior description: `HTTP_METHOD /api/path — brief explanation`
+
+**Participant conventions**:
+- Use short aliases: `U` (User/Browser), `W` (Web/Frontend), `SB` (Supabase), `DB` (Database)
+- Full name for each participant is noted in the `participant` declaration
+
+**Scenario numbering conventions**:
+- Document title format: `S01: Email Registration — Sequence Diagram`
+- One scenario per file, numbered to correspond with Phase 1
+
+**Format example**:
+
+```mermaid
+sequenceDiagram
+    participant U as User/Browser
+    participant W as Web (Astro)
+    participant SB as Supabase Auth
+    participant DB as Supabase DB
+
+    U->>W: Step 1: POST /api/auth/register — Submit {email, password, referral_code?}
+    W->>SB: Step 2: supabase.auth.signUp(email, password, metadata) — Initiate user creation
+    SB-->>W: Step 3: Return {user, session} or error
+    W->>DB: Step 4: INSERT INTO profiles — Write user extended info
+    DB-->>W: Step 5: Return write result
+    W-->>U: Step 6: Return registration result + prompt to verify email
+```
+
+### Step 3: Write Step Narratives
+
+After the sequence diagram, use a **consecutively numbered list** to write out all steps one by one, forming a linear narrative that humans can read fluently from start to finish.
+
+**Format conventions**:
+
+1. **Every step must be written out**—no skipping, no omitting. Simple steps can be covered in one line; complex steps are elaborated below using `>` blockquote
+2. **Every step must have a clear subject**—the reader should never have to guess "who is doing this". Use the alias or full name from the participant table as the subject
+3. **Numbering strictly corresponds to the Step N in the sequence diagram**
+4. **Normal flow and exception cases are written separately**—normal flow comes first, exception cases follow. In the normal flow, only add `→ see EX-N.M` references after steps that trigger exceptions; do not expand exception content inline
+
+**Normal flow format example**:
+
+````markdown
+## Step Descriptions
+
+1. **Developer** enters `openlogos init my-project` in the terminal.
+2. **CLI** checks whether `logos/logos.config.json` already exists. If it exists → see EX-2.1.
+3. **CLI** displays a language selection menu in the terminal (1. English / 2. 中文). If the terminal is non-TTY → see EX-3.1.
+
+> Language selection is placed in the `init` phase (rather than global configuration) because this is the user's first interaction with OpenLogos, making it the most natural moment to confirm language preference.
+
+4. **Developer** selects a language (enters 1 or 2).
+5. **CLI** detects the project name from `package.json` / `Cargo.toml` / `pyproject.toml` / directory name. If the user-provided name conflicts with the config file name → see EX-5.1.
+
+> Priority chain: CLI argument > package.json > Cargo.toml > pyproject.toml > directory name. Scoped names automatically strip the `@org/` prefix.
+
+6. **CLI** creates 11 directories in sequence (`logos/resources/prd/...` etc.), writing `.gitkeep` to each.
+7. **CLI** writes `logos/logos.config.json` (containing locale + 5 document module definitions).
+8. **CLI** writes `logos/logos-project.yaml` (containing empty tech_stack + conventions).
+9. **CLI** writes `AGENTS.md` and `CLAUDE.md` (containing Phase detection logic).
+10. **CLI** outputs the list of created files and next-step suggestions in the terminal.
+````
+
+**Exception case format example**:
+
+````markdown
+## Exception Cases
+
+### EX-2.1: Project Already Initialized
+
+- **Trigger condition**: Step 2 detects that `logos/logos.config.json` already exists
+- **Expected response**: stderr outputs `Error: logos/logos.config.json already exists in current directory.`, exit(1)
+- **Side effects**: No files created, existing configuration not overwritten
+
+### EX-3.1: Non-TTY Environment
+
+- **Trigger condition**: Step 3 detects that `process.stdin.isTTY` is false (CI pipeline / piped input)
+- **Expected response**: Skip language selection interaction, default to `locale = 'en'`
+- **Side effects**: None, flow proceeds directly to Step 5
+
+### EX-5.1: Project Name Conflict
+
+- **Trigger condition**: In Step 5, the user-provided `name` differs from the name in `package.json` (or other config files)
+- **Expected response**: Display two options for the user to choose from; in non-TTY environments, automatically use the user-provided name
+- **Side effects**: None, flow continues to Step 6 after selection
+````
+
+**Narrative principles**:
+- **No skipping steps**: Even if a step is worth only one line (e.g., "CLI writes file"), it must still be written out to maintain consecutive numbering
+- **Subject first**: Each step begins with a bold subject, so the reader can immediately see "who is acting"
+- **Use blockquotes for supplementary notes**: When you need to explain "why" or document a design decision, expand below the step using `>` blockquote without disrupting reading flow
+- **Exception cases as separate sections**: Normal flow only contains `→ see EX-N.M` references; the trigger conditions, expected responses, and side effects of exceptions are expanded in the "Exception Cases" section at the bottom of the document
+
+### Step 4: Design Exception Cases
+
+Expand exception acceptance criteria identified in Phase 1/2 into technical-level exception cases, and supplement with technical exceptions not covered in Phase 1/2 (e.g., service unavailable, database write failure):
+
+```markdown
+#### Exception Cases
+
+##### EX-2.1: Email Already Registered (← Phase 1 S01 exception acceptance criteria)
+- **Trigger condition**: Submitted email already exists in the auth.users table
+- **Expected response**: HTTP 409 `{ code: "EMAIL_EXISTS", message: "Email already registered" }`
+- **Side effects**: No records created, no emails sent
+
+##### EX-2.2: Supabase Auth Service Unavailable (technical exception, not covered in Phase 1)
+- **Trigger condition**: Supabase Auth service times out or returns 5xx
+- **Expected response**: HTTP 503 `{ code: "AUTH_SERVICE_UNAVAILABLE", message: "Authentication service temporarily unavailable" }`
+- **Side effects**: Error logged, alert triggered
+
+##### EX-4.1: Profile Write Failure (technical exception, not covered in Phase 1)
+- **Trigger condition**: INSERT INTO profiles violates unique constraint or RLS denies access
+- **Expected response**: HTTP 500 `{ code: "PROFILE_CREATE_FAILED", message: "User profile creation failed" }`
+- **Side effects**: Record in auth.users already created but profiles not created (compensation mechanism needed)
+```
+
+**Exception case numbering rule**: `EX-{step number}.{sequence number}`
+
+### Step 5: Generate Scenario Overview Document
+
+Summarize the technical implementation status of all scenarios:
+
+```markdown
+# Business Scenario Overview (Technical Implementation)
+
+## Scenario Map
+| Number | Scenario Name | Phase 1 | Phase 2 | Phase 3 Sequence Diagram | API | Orchestration | Status |
+|--------|--------------|---------|---------|--------------------------|-----|---------------|--------|
+| S01    | Email Registration | ✅ | ✅ | ✅ | ✅ | 🔲 | In Progress |
+| S02    | Password Login | ✅ | ✅ | 🔲 | 🔲 | 🔲 | Not Started |
+
+## Scenario Dependencies
+[Describe prerequisite/follow-up relationships between scenarios]
+
+## Scenario Index
+[File links for each scenario, spanning all three Phases]
+```
+
+## Output Specification
+
+- **Scenario overview**: `logos/resources/prd/3-technical-plan/2-scenario-implementation/00-scenario-overview.md`
+- **Scenario documents**: `logos/resources/prd/3-technical-plan/2-scenario-implementation/{scenario-number}-{scenario-name}.md`
+- Sequence diagrams use Mermaid format (renderable directly in Markdown)
+- Exception cases use `EX-N.M` numbering, globally unique
+- Each scenario document contains: sequence diagram + step descriptions + exception cases
+- **Scenario numbers must be consistent with Phase 1/2**
+
+## Best Practices
+
+- **Do not identify scenarios from scratch**: Phase 3 scenarios come from Phase 1 requirements documents. If a scenario not present in Phase 1 is discovered, go back to Phase 1 to add it
+- **Phase 1/2 exceptions are inputs**: Phase 1's "exception: email already registered" should be expanded in Phase 3 into a technical specification with HTTP status codes and response bodies
+- **Draw the main path first, then add exceptions**: Do not try to draw all branches in the first pass; get the main path clear first
+- **Exception case coverage strategy**: Every step involving an external call (database, third-party service) should have at least 1 exception case
+- **Step numbering maintenance**: When inserting a step in the middle, renumber all subsequent steps and update all EX references accordingly
+- **Participant granularity**: In microservice architectures, each service is a participant; in monolithic applications, divide by logical layers (Web, Auth, DB)
+- **Sequence diagrams are the source of APIs**: Cross-system-boundary arrows in sequence diagrams are the APIs that need to be designed—if an API cannot be traced back to a sequence diagram, it probably should not exist
+
+## Recommended Prompts
+
+The following prompts can be copied directly for AI use:
+
+- `Help me draw the sequence diagram for S01`
+- `Help me do scenario modeling for all P0 scenarios`
+- `Help me add exception case sequence diagrams for S03`
+- `Based on the product design, help me do technical scenario modeling`