Update deployment skill documentation to reflect new 7-step workflow and directory structure. Enhance README with detailed usage instructions for the autopilot feature and clarify skill descriptions. Adjust paths for deployment templates to align with the updated documentation structure.

2026-04-22 07:16:38 +00:00 · 2026-03-19 17:05:59 +02:00
parent 05411d19b8
commit f70d701979
10 changed files with 921 additions and 50 deletions
@@ -1,42 +1,149 @@
+## How to Use
+
+Type `/autopilot` to start or continue the full workflow. The orchestrator detects where your project is and picks up from there.
+
+```
+/autopilot              — start a new project or continue where you left off
+```
+
+If you want to run a specific skill directly (without the orchestrator), use the individual commands:
+
+```
+/problem                — interactive problem gathering → _docs/00_problem/
+/research               — solution drafts → _docs/01_solution/
+/plan                   — architecture, components, tests → _docs/02_plans/
+/decompose              — atomic task specs → _docs/02_tasks/
+/implement              — batched parallel implementation → _docs/03_implementation/
+/deploy                 — containerization, CI/CD, observability → _docs/04_deploy/
+```
+
+## How It Works
+
+The autopilot is a state machine that persists its state to `_docs/_autopilot_state.md`. On every invocation it reads the state file, cross-checks against the `_docs/` folder structure, shows a status summary with context from prior sessions, and continues execution.
+
+```
+/autopilot invoked
+    │
+    ▼
+Read _docs/_autopilot_state.md → cross-check _docs/ folders
+    │
+    ▼
+Show status summary (progress, key decisions, last session context)
+    │
+    ▼
+Execute current skill (read its SKILL.md, follow its workflow)
+    │
+    ▼
+Update state file → auto-chain to next skill → loop
+```
+
+The state file tracks completed steps, key decisions, blockers, and session context. This makes re-entry across conversations seamless — the autopilot knows not just where you are, but what decisions were made and why.
+
+Skills auto-chain without pausing between them. The only pauses are:
+- **BLOCKING gates** inside each skill (user must confirm before proceeding)
+- **Session boundary** after decompose (suggests new conversation before implement)
+
+A typical project runs in 2-4 conversations:
+- Session 1: Problem → Research → Research decision
+- Session 2: Plan → Decompose
+- Session 3: Implement (may span multiple sessions)
+- Session 4: Deploy
+
+Re-entry is seamless: type `/autopilot` in a new conversation and the orchestrator reads the state file to pick up exactly where you left off.
+
+## Skill Descriptions
+
+### autopilot (meta-orchestrator)
+
+Auto-chaining engine that sequences the full BUILD → SHIP workflow. Persists state to `_docs/_autopilot_state.md`, tracks key decisions and session context, and flows through problem → research → plan → decompose → implement → deploy without manual skill invocation. Maximizes work per conversation with seamless cross-session re-entry.
+
+### problem
+
+Interactive interview that builds `_docs/00_problem/`. Asks probing questions across 8 dimensions (problem, scope, hardware, software, acceptance criteria, input data, security, operations) until all required files can be written with concrete, measurable content.
+
+### research
+
+8-step deep research methodology. Mode A produces initial solution drafts. Mode B assesses and revises existing drafts. Includes AC assessment, source tiering, fact extraction, comparison frameworks, and validation. Run multiple rounds until the solution is solid.
+
+### plan
+
+6-step planning workflow. Produces integration test specs, architecture, system flows, data model, deployment plan, component specs with interfaces, risk assessment, test specifications, and Jira epics. Heavy interaction at BLOCKING gates.
+
+### decompose
+
+4-step task decomposition. Produces a bootstrap structure plan, atomic task specs per component, integration test tasks, and a cross-task dependency table. Each task gets a Jira ticket and is capped at 5 complexity points.
+
+### implement
+
+Orchestrator that reads task specs, computes dependency-aware execution batches, launches up to 4 parallel implementer subagents, runs code review after each batch, and commits per batch. Does not write code itself.
+
+### deploy
+
+7-step deployment planning. Status check, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts. Produces documents for steps 1-6 and executable scripts in step 7.
+
+### code-review
+
+Multi-phase code review against task specs. Produces structured findings with verdict: PASS, FAIL, or PASS_WITH_WARNINGS.
+
+### refactor
+
+6-phase structured refactoring: baseline, discovery, analysis, safety net, execution, hardening.
+
+### security
+
+OWASP-based security testing and audit.
+
+### retrospective
+
+Collects metrics from implementation batch reports, analyzes trends, produces improvement reports.
+
+### rollback
+
+Reverts implementation to a specific batch checkpoint using git revert, verifies integrity.
+
 ## Developer TODO (Project Mode)

 ### BUILD

 ```
-1. Create _docs/00_problem/                      — describe what you're building
+0. /problem                                      — interactive interview → _docs/00_problem/
   - problem.md                                   (required)
   - restrictions.md                              (required)
   - acceptance_criteria.md                       (required)
   - input_data/                                  (required)
   - security_approach.md                         (optional)

-2. /research                                     — solution drafts → _docs/01_solution/
+1. /research                                     — solution drafts → _docs/01_solution/
   Run multiple times: Mode A → draft, Mode B → assess & revise

-3. /plan                                         — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_plans/
+2. /plan                                         — architecture, data model, deployment, components, risks, tests, Jira epics → _docs/02_plans/

-4. /decompose                                    — atomic task specs + dependency table → _docs/02_tasks/
+3. /decompose                                    — atomic task specs + dependency table → _docs/02_tasks/

-5. /implement                                    — batched parallel agents, code review, commit per batch → _docs/03_implementation/
+4. /implement                                    — batched parallel agents, code review, commit per batch → _docs/03_implementation/
 ```

 ### SHIP

 ```
-6. /deploy                                       — containerization, CI/CD, environments, observability, procedures → _docs/02_plans/deployment/
+5. /deploy                                       — containerization, CI/CD, environments, observability, procedures → _docs/04_deploy/
 ```

 ### EVOLVE

 ```
-7. /refactor                                     — structured refactoring → _docs/04_refactoring/
-8. /retrospective                                — metrics, trends, improvement actions → _docs/05_metrics/
+6. /refactor                                     — structured refactoring → _docs/04_refactoring/
+7. /retrospective                                — metrics, trends, improvement actions → _docs/05_metrics/
 ```

+Or just use `/autopilot` to run steps 0-5 automatically.
+
 ## Available Skills

 | Skill | Triggers | Output |
 |-------|----------|--------|
+| **autopilot** | "autopilot", "auto", "start", "continue", "what's next" | Orchestrates full workflow |
+| **problem** | "problem", "define problem", "new project" | `_docs/00_problem/` |
 | **research** | "research", "investigate" | `_docs/01_solution/` |
 | **plan** | "plan", "decompose solution" | `_docs/02_plans/` |
 | **decompose** | "decompose", "task decomposition" | `_docs/02_tasks/` |
@@ -44,7 +151,7 @@
 | **code-review** | "code review", "review code" | Verdict: PASS / FAIL / PASS_WITH_WARNINGS |
 | **refactor** | "refactor", "improve code" | `_docs/04_refactoring/` |
 | **security** | "security audit", "OWASP" | Security findings report |
-| **deploy** | "deploy", "CI/CD", "observability" | `_docs/02_plans/deployment/` |
+| **deploy** | "deploy", "CI/CD", "observability" | `_docs/04_deploy/` |
 | **retrospective** | "retrospective", "retro" | `_docs/05_metrics/` |
 | **rollback** | "rollback", "revert batch" | `_docs/03_implementation/rollback_report.md` |

@@ -58,6 +165,7 @@

 ```
 _docs/
+├── _autopilot_state.md                  — autopilot orchestrator state (progress, decisions, session context)
 ├── 00_problem/                          — problem definition, restrictions, AC, input data
 ├── 00_research/                         — intermediate research artifacts
 ├── 01_solution/                         — solution drafts, tech stack, security analysis
@@ -74,6 +182,7 @@ _docs/
 │   └── FINAL_report.md
 ├── 02_tasks/                            — [JIRA-ID]_[name].md + _dependencies_table.md
 ├── 03_implementation/                   — batch reports, rollback report, FINAL report
+├── 04_deploy/                           — containerization, CI/CD, environments, observability, procedures, scripts
 ├── 04_refactoring/                      — baseline, discovery, analysis, execution, hardening
 └── 05_metrics/                          — retro_[YYYY-MM-DD].md
 ```
@@ -0,0 +1,321 @@
+---
+name: autopilot
+description: |
+  Auto-chaining orchestrator that drives the full BUILD-SHIP workflow from problem gathering through deployment.
+  Detects current project state from _docs/ folder, resumes from where it left off, and flows through
+  problem → research → plan → decompose → implement → deploy without manual skill invocation.
+  Maximizes work per conversation by auto-transitioning between skills.
+  Trigger phrases:
+  - "autopilot", "auto", "start", "continue"
+  - "what's next", "where am I", "project status"
+category: meta
+tags: [orchestrator, workflow, auto-chain, state-machine, meta-skill]
+disable-model-invocation: true
+---
+
+# Autopilot Orchestrator
+
+Auto-chaining execution engine that drives the full BUILD → SHIP workflow. Detects project state from `_docs/`, resumes from where work stopped, and flows through skills automatically. The user invokes `/autopilot` once — the engine handles sequencing, transitions, and re-entry.
+
+## Core Principles
+
+- **Auto-chain**: when a skill completes, immediately start the next one — no pause between skills
+- **Only pause at decision points**: BLOCKING gates inside sub-skills are the natural pause points; do not add artificial stops between steps
+- **State from disk**: all progress is persisted to `_docs/_autopilot_state.md` and cross-checked against `_docs/` folder structure
+- **Rich re-entry**: on every invocation, read the state file for full context before continuing
+- **Delegate, don't duplicate**: read and execute each sub-skill's SKILL.md; never inline their logic here
+
+## State File: `_docs/_autopilot_state.md`
+
+The autopilot persists its state to `_docs/_autopilot_state.md`. This file is the primary source of truth for re-entry. Folder scanning is the fallback when the state file doesn't exist.
+
+### Format
+
+```markdown
+# Autopilot State
+
+## Current Step
+step: [0-5 or "done"]
+name: [Problem / Research / Plan / Decompose / Implement / Deploy / Done]
+status: [not_started / in_progress / completed]
+sub_step: [optional — sub-skill phase if interrupted mid-step, e.g. "Plan Step 3: Component Decomposition"]
+
+## Completed Steps
+
+| Step | Name | Completed | Key Outcome |
+|------|------|-----------|-------------|
+| 0 | Problem | [date] | [one-line summary] |
+| 1 | Research | [date] | [N drafts, final approach summary] |
+| 2 | Plan | [date] | [N components, architecture summary] |
+| 3 | Decompose | [date] | [N tasks, total complexity points] |
+| 4 | Implement | [date] | [N batches, pass/fail summary] |
+| 5 | Deploy | [date] | [artifacts produced] |
+
+## Key Decisions
+- [decision 1: e.g. "Tech stack: Python + Rust for perf-critical, Postgres DB"]
+- [decision 2: e.g. "6 research rounds, final draft: solution_draft06.md"]
+- [decision N]
+
+## Last Session
+date: [date]
+ended_at: [step name and phase]
+reason: [completed step / session boundary / user paused / context limit]
+notes: [any context for next session, e.g. "User asked to revisit risk assessment"]
+
+## Blockers
+- [blocker 1, if any]
+- [none]
+```
+
+### State File Rules
+
+1. **Create** the state file on the very first autopilot invocation (after state detection determines Step 0)
+2. **Update** the state file after every step completion, every session boundary, and every BLOCKING gate confirmation
+3. **Read** the state file as the first action on every invocation — before folder scanning
+4. **Cross-check**: after reading the state file, verify against actual `_docs/` folder contents. If they disagree (e.g., state file says Step 2 but `_docs/02_plans/architecture.md` already exists), trust the folder structure and update the state file to match
+5. **Never delete** the state file. It accumulates history across the entire project lifecycle
+
+## Execution Entry Point
+
+Every invocation of this skill follows the same sequence:
+
+```
+1. Read _docs/_autopilot_state.md (if exists)
+2. Cross-check state file against _docs/ folder structure
+3. Resolve current step (state file + folder scan)
+4. Present Status Summary (from state file context)
+5. Enter Execution Loop:
+   a. Read and execute the current skill's SKILL.md
+   b. When skill completes → update state file
+   c. Re-detect next step
+   d. If next skill is ready → auto-chain (go to 5a with next skill)
+   e. If session boundary reached → update state file with session notes → suggest new conversation
+   f. If all steps done → update state file → report completion
+```
+
+## State Detection
+
+Read `_docs/_autopilot_state.md` first. If it exists and is consistent with the folder structure, use the `Current Step` from the state file. If the state file doesn't exist or is inconsistent, fall back to folder scanning.
+
+### Folder Scan Rules (fallback)
+
+Scan `_docs/` to determine the current workflow position. Check rules in order — first match wins.
+
+### Detection Rules
+
+**Step 0 — Problem Gathering**
+Condition: `_docs/00_problem/` does not exist, OR any of these are missing/empty:
+- `problem.md`
+- `restrictions.md`
+- `acceptance_criteria.md`
+- `input_data/` (must contain at least one file)
+
+Action: Read and execute `.cursor/skills/problem/SKILL.md`
+
+---
+
+**Step 1 — Research (Initial)**
+Condition: `_docs/00_problem/` is complete AND `_docs/01_solution/` has no `solution_draft*.md` files
+
+Action: Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mode A)
+
+---
+
+**Step 1b — Research Decision**
+Condition: `_docs/01_solution/` contains `solution_draft*.md` files AND `_docs/01_solution/solution.md` does not exist AND `_docs/02_plans/architecture.md` does not exist
+
+Action: Present the current research state to the user:
+- How many solution drafts exist
+- Whether tech_stack.md and security_analysis.md exist
+- One-line summary from the latest draft
+
+Then ask: **"Run another research round (Mode B assessment), or proceed to planning?"**
+- If user wants another round → Read and execute `.cursor/skills/research/SKILL.md` (will auto-detect Mode B)
+- If user wants to proceed → auto-chain to Step 2 (Plan)
+
+---
+
+**Step 2 — Plan**
+Condition: `_docs/01_solution/` has `solution_draft*.md` files AND `_docs/02_plans/architecture.md` does not exist
+
+Action:
+1. The plan skill's Prereq 2 will rename the latest draft to `solution.md` — this is handled by the plan skill itself
+2. Read and execute `.cursor/skills/plan/SKILL.md`
+
+If `_docs/02_plans/` exists but is incomplete (has some artifacts but no `FINAL_report.md`), the plan skill's built-in resumability handles it.
+
+---
+
+**Step 3 — Decompose**
+Condition: `_docs/02_plans/` contains `architecture.md` AND `_docs/02_plans/components/` has at least one component AND `_docs/02_tasks/` does not exist or has no task files (excluding `_dependencies_table.md`)
+
+Action: Read and execute `.cursor/skills/decompose/SKILL.md`
+
+If `_docs/02_tasks/` has some task files already, the decompose skill's resumability handles it.
+
+---
+
+**Step 4 — Implement**
+Condition: `_docs/02_tasks/` contains task files AND `_dependencies_table.md` exists AND `_docs/03_implementation/FINAL_implementation_report.md` does not exist
+
+Action: Read and execute `.cursor/skills/implement/SKILL.md`
+
+If `_docs/03_implementation/` has batch reports, the implement skill detects completed tasks and continues.
+
+---
+
+**Step 5 — Deploy**
+Condition: `_docs/03_implementation/FINAL_implementation_report.md` exists AND `_docs/04_deploy/` does not exist or is incomplete
+
+Action: Read and execute `.cursor/skills/deploy/SKILL.md`
+
+---
+
+**Done**
+Condition: `_docs/04_deploy/` contains all expected artifacts (containerization.md, ci_cd_pipeline.md, environment_strategy.md, observability.md, deployment_procedures.md)
+
+Action: Report project completion with summary.
+
+## Status Summary
+
+On every invocation, before executing any skill, present a status summary built from the state file (with folder scan fallback).
+
+Format:
+
+```
+═══════════════════════════════════════════════════
+ AUTOPILOT STATUS
+═══════════════════════════════════════════════════
+ Step 0  Problem      [DONE / IN PROGRESS / NOT STARTED]
+ Step 1  Research     [DONE (N drafts) / IN PROGRESS / NOT STARTED]
+ Step 2  Plan         [DONE / IN PROGRESS / NOT STARTED]
+ Step 3  Decompose    [DONE (N tasks) / IN PROGRESS / NOT STARTED]
+ Step 4  Implement    [DONE / IN PROGRESS (batch M of ~N) / NOT STARTED]
+ Step 5  Deploy       [DONE / IN PROGRESS / NOT STARTED]
+═══════════════════════════════════════════════════
+ Current step: [Step N — Name]
+ Action: [what will happen next]
+═══════════════════════════════════════════════════
+```
+
+For re-entry (state file exists), also include:
+- Key decisions from the state file's `Key Decisions` section
+- Last session context from the `Last Session` section
+- Any blockers from the `Blockers` section
+
+## Auto-Chain Rules
+
+After a skill completes, apply these rules:
+
+| Completed Step | Next Action |
+|---------------|-------------|
+| Problem Gathering | Auto-chain → Research (Mode A) |
+| Research (any round) | Auto-chain → Research Decision (ask user: another round or proceed?) |
+| Research Decision → proceed | Auto-chain → Plan |
+| Plan | Auto-chain → Decompose |
+| Decompose | **Session boundary** — suggest new conversation before Implement |
+| Implement | Auto-chain → Deploy |
+| Deploy | Report completion |
+
+### Session Boundary: Decompose → Implement
+
+After decompose completes, **do not auto-chain to implement**. Instead:
+
+1. Update state file: mark Decompose as completed, set current step to 4 (Implement) with status `not_started`
+2. Write `Last Session` section: `reason: session boundary`, `notes: Decompose complete, implementation ready`
+3. Present a summary: number of tasks, estimated batches, total complexity points
+4. Suggest: "Implementation is the longest phase and benefits from a fresh conversation context. Start a new conversation and type `/autopilot` to begin implementation."
+5. If the user insists on continuing in the same conversation, proceed.
+
+This is the only hard session boundary. All other transitions auto-chain.
+
+## Skill Delegation
+
+For each step, the delegation pattern is:
+
+1. Update state file: set current step to `in_progress`, record `sub_step` if applicable
+2. Announce: "Starting [Skill Name]..."
+3. Read the skill file: `.cursor/skills/[name]/SKILL.md`
+4. Execute the skill's workflow exactly as written, including:
+   - All BLOCKING gates (present to user, wait for confirmation)
+   - All self-verification checklists
+   - All save actions
+   - All escalation rules
+5. When the skill's workflow is fully complete:
+   - Update state file: mark step as `completed`, record date, write one-line key outcome
+   - Add any key decisions made during this step to the `Key Decisions` section
+   - Return to the auto-chain rules
+
+Do NOT modify, skip, or abbreviate any part of the sub-skill's workflow. The autopilot is a sequencer, not an optimizer.
+
+## Re-Entry Protocol
+
+When the user invokes `/autopilot` and work already exists:
+
+1. Read `_docs/_autopilot_state.md`
+2. Cross-check against `_docs/` folder structure
+3. Present Status Summary with context from state file (key decisions, last session, blockers)
+4. If the detected step has a sub-skill with built-in resumability (plan, decompose, implement, deploy all do), the sub-skill handles mid-step recovery
+5. Continue execution from detected state
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| State detection is ambiguous (artifacts suggest two different steps) | Present findings to user, ask which step to execute |
+| Sub-skill fails or hits an unrecoverable blocker | Report the error, suggest the user fix it manually, then re-invoke `/autopilot` |
+| User wants to skip a step | Warn about downstream dependencies, proceed if user confirms |
+| User wants to go back to a previous step | Warn that re-running may overwrite artifacts, proceed if user confirms |
+| User asks "where am I?" without wanting to continue | Show Status Summary only, do not start execution |
+
+## Trigger Conditions
+
+This skill activates when the user wants to:
+- Start a new project from scratch
+- Continue an in-progress project
+- Check project status
+- Let the AI guide them through the full workflow
+
+**Keywords**: "autopilot", "auto", "start", "continue", "what's next", "where am I", "project status"
+
+**Differentiation**:
+- User wants only research → use `/research` directly
+- User wants only planning → use `/plan` directly
+- User wants the full guided workflow → use `/autopilot`
+
+## Methodology Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│              Autopilot (Auto-Chain Orchestrator)                │
+├────────────────────────────────────────────────────────────────┤
+│ EVERY INVOCATION:                                              │
+│   1. State Detection (scan _docs/)                             │
+│   2. Status Summary (show progress)                            │
+│   3. Execute current skill                                     │
+│   4. Auto-chain to next skill (loop)                           │
+│                                                                │
+│ WORKFLOW:                                                       │
+│   Step 0  Problem    → .cursor/skills/problem/SKILL.md         │
+│     ↓ auto-chain                                               │
+│   Step 1  Research   → .cursor/skills/research/SKILL.md        │
+│     ↓ auto-chain (ask: another round?)                         │
+│   Step 2  Plan       → .cursor/skills/plan/SKILL.md            │
+│     ↓ auto-chain                                               │
+│   Step 3  Decompose  → .cursor/skills/decompose/SKILL.md       │
+│     ↓ SESSION BOUNDARY (suggest new conversation)              │
+│   Step 4  Implement  → .cursor/skills/implement/SKILL.md       │
+│     ↓ auto-chain                                               │
+│   Step 5  Deploy     → .cursor/skills/deploy/SKILL.md          │
+│     ↓                                                          │
+│   DONE                                                         │
+│                                                                │
+│ STATE FILE: _docs/_autopilot_state.md                          │
+│ FALLBACK: _docs/ folder structure scan                         │
+│ PAUSE POINTS: sub-skill BLOCKING gates only                    │
+│ SESSION BREAK: after Decompose (before Implement)              │
+├────────────────────────────────────────────────────────────────┤
+│ Principles: Auto-chain · State to file · Rich re-entry         │
+│             Delegate don't duplicate · Pause at decisions only  │
+└────────────────────────────────────────────────────────────────┘
+```
@@ -1,22 +1,22 @@
 ---
 name: deploy
 description: |
-  Comprehensive deployment skill covering containerization, CI/CD pipeline, environment strategy, observability, and deployment procedures.
-  5-step workflow: Docker containerization, CI/CD pipeline definition, environment strategy, observability planning, deployment procedures.
-  Uses _docs/02_plans/deployment/ structure.
+  Comprehensive deployment skill covering status check, env setup, containerization, CI/CD pipeline, environment strategy, observability, deployment procedures, and deployment scripts.
+  7-step workflow: Status & env check, Docker containerization, CI/CD pipeline definition, environment strategy, observability planning, deployment procedures, deployment scripts.
+  Uses _docs/04_deploy/ structure.
  Trigger phrases:
  - "deploy", "deployment", "deployment strategy"
  - "CI/CD", "pipeline", "containerize"
  - "observability", "monitoring", "logging"
  - "dockerize", "docker compose"
 category: ship
-tags: [deployment, docker, ci-cd, observability, monitoring, containerization]
+tags: [deployment, docker, ci-cd, observability, monitoring, containerization, scripts]
 disable-model-invocation: true
 ---

 # Deployment Planning

-Plan and document the full deployment lifecycle: containerize the application, define CI/CD pipelines, configure environments, set up observability, and document deployment procedures.
+Plan and document the full deployment lifecycle: check deployment status and environment requirements, containerize the application, define CI/CD pipelines, configure environments, set up observability, document deployment procedures, and generate deployment scripts.

 ## Core Principles

@@ -26,14 +26,16 @@ Plan and document the full deployment lifecycle: containerize the application, d
 - **Environment parity**: dev, staging, and production environments mirror each other as closely as possible
 - **Save immediately**: write artifacts to disk after each step; never accumulate unsaved work
 - **Ask, don't assume**: when infrastructure constraints or preferences are unclear, ask the user
- **Plan, don't code**: this workflow produces deployment documents and specifications, not implementation code
+- **Plan, don't code**: this workflow produces deployment documents and specifications, not implementation code (except deployment scripts in Step 7)

 ## Context Resolution

 Fixed paths:

 - PLANS_DIR: `_docs/02_plans/`
- DEPLOY_DIR: `_docs/02_plans/deployment/`
+- DEPLOY_DIR: `_docs/04_deploy/`
+- REPORTS_DIR: `_docs/04_deploy/reports/`
+- SCRIPTS_DIR: `scripts/`
 - ARCHITECTURE: `_docs/02_plans/architecture.md`
 - COMPONENTS_DIR: `_docs/02_plans/components/`

@@ -55,7 +57,7 @@ Announce the resolved paths to the user before proceeding.

 1. `architecture.md` exists — **STOP if missing**, run `/plan` first
 2. At least one component spec exists in `PLANS_DIR/components/` — **STOP if missing**
-3. Create DEPLOY_DIR if it does not exist
+3. Create DEPLOY_DIR, REPORTS_DIR, and SCRIPTS_DIR if they do not exist
 4. If DEPLOY_DIR already contains artifacts, ask user: **resume from last checkpoint or start fresh?**

 ## Artifact Management
@@ -68,18 +70,33 @@ DEPLOY_DIR/
 ├── ci_cd_pipeline.md
 ├── environment_strategy.md
 ├── observability.md
-└── deployment_procedures.md
+├── deployment_procedures.md
+├── deploy_scripts.md
+└── reports/
+    └── deploy_status_report.md
+
+SCRIPTS_DIR/           (project root)
+├── deploy.sh
+├── pull-images.sh
+├── start-services.sh
+├── stop-services.sh
+└── health-check.sh
+
+.env                   (project root, git-ignored)
+.env.example           (project root, committed)
 ```

 ### Save Timing

 | Step | Save immediately after | Filename |
 |------|------------------------|----------|
-| Step 1 | Containerization plan complete | `containerization.md` |
-| Step 2 | CI/CD pipeline defined | `ci_cd_pipeline.md` |
-| Step 3 | Environment strategy documented | `environment_strategy.md` |
-| Step 4 | Observability plan complete | `observability.md` |
-| Step 5 | Deployment procedures documented | `deployment_procedures.md` |
+| Step 1 | Status check & env setup complete | `reports/deploy_status_report.md` + `.env` + `.env.example` |
+| Step 2 | Containerization plan complete | `containerization.md` |
+| Step 3 | CI/CD pipeline defined | `ci_cd_pipeline.md` |
+| Step 4 | Environment strategy documented | `environment_strategy.md` |
+| Step 5 | Observability plan complete | `observability.md` |
+| Step 6 | Deployment procedures documented | `deployment_procedures.md` |
+| Step 7 | Deployment scripts created | `deploy_scripts.md` + scripts in `SCRIPTS_DIR/` |

 ### Resumability

@@ -92,11 +109,52 @@ If DEPLOY_DIR already contains artifacts:

 ## Progress Tracking

-At the start of execution, create a TodoWrite with all steps (1 through 5). Update status as each step completes.
+At the start of execution, create a TodoWrite with all steps (1 through 7). Update status as each step completes.

 ## Workflow

-### Step 1: Containerization
+### Step 1: Deployment Status & Environment Setup
+
+**Role**: DevOps / Platform engineer
+**Goal**: Assess current deployment readiness, identify all required environment variables, and create `.env` files
+**Constraints**: Must complete before any other step
+
+1. Read architecture.md, all component specs, and restrictions.md
+2. Assess deployment readiness:
+   - List all components and their current state (planned / implemented / tested)
+   - Identify external dependencies (databases, APIs, message queues, cloud services)
+   - Identify infrastructure prerequisites (container registry, cloud accounts, DNS, SSL certificates)
+   - Check if any deployment blockers exist
+3. Identify all required environment variables by scanning:
+   - Component specs for configuration needs
+   - Database connection requirements
+   - External API endpoints and credentials
+   - Feature flags and runtime configuration
+   - Container registry credentials
+   - Cloud provider credentials
+   - Monitoring/logging service endpoints
+4. Generate `.env.example` in project root with all variables and placeholder values (committed to VCS)
+5. Generate `.env` in project root with development defaults filled in where safe (git-ignored)
+6. Ensure `.gitignore` includes `.env` (but NOT `.env.example`)
+7. Produce a deployment status report summarizing readiness, blockers, and required setup
+
+**Self-verification**:
+- [ ] All components assessed for deployment readiness
+- [ ] External dependencies catalogued
+- [ ] Infrastructure prerequisites identified
+- [ ] All required environment variables discovered
+- [ ] `.env.example` created with placeholder values
+- [ ] `.env` created with safe development defaults
+- [ ] `.gitignore` updated to exclude `.env`
+- [ ] Status report written to `reports/deploy_status_report.md`
+
+**Save action**: Write `reports/deploy_status_report.md` using `templates/deploy_status_report.md`, create `.env` and `.env.example` in project root
+
+**BLOCKING**: Present status report and environment variables to user. Do NOT proceed until confirmed.
+
+---
+
+### Step 2: Containerization

 **Role**: DevOps / Platform engineer
 **Goal**: Define Docker configuration for every component, local development, and integration test environments
@@ -117,7 +175,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
   - Database (Postgres) with named volume
   - Any message queues, caches, or external service mocks
   - Shared network
-   - Environment variable files (`.env.dev`)
+   - Environment variable files (`.env`)
 6. Define `docker-compose.test.yml` for integration tests:
   - Application components under test
   - Test runner container (black-box, no internal imports)
@@ -140,7 +198,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda

 ---

-### Step 2: CI/CD Pipeline
+### Step 3: CI/CD Pipeline

 **Role**: DevOps engineer
 **Goal**: Define the CI/CD pipeline with quality gates, security scanning, and multi-environment deployment
@@ -179,7 +237,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda

 ---

-### Step 3: Environment Strategy
+### Step 4: Environment Strategy

 **Role**: Platform engineer
 **Goal**: Define environment configuration, secrets management, and environment parity
@@ -194,7 +252,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
 | **Production** | Live system | Full infrastructure | Real data |

 2. Define environment variable management:
-   - `.env.example` with all required variables (no real values)
+   - Reference `.env.example` created in Step 1
   - Per-environment variable sources (`.env` for dev, secret manager for staging/prod)
   - Validation: fail fast on missing required variables at startup
 3. Define secrets management:
@@ -209,7 +267,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda

 **Self-verification**:
 - [ ] All three environments defined with clear purpose
- [ ] Environment variable documentation complete (`.env.example`)
+- [ ] Environment variable documentation complete (references `.env.example` from Step 1)
 - [ ] No secrets in any output document
 - [ ] Secret manager specified for staging/production
 - [ ] Database strategy per environment
@@ -218,7 +276,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda

 ---

-### Step 4: Observability
+### Step 5: Observability

 **Role**: Site Reliability Engineer (SRE)
 **Goal**: Define logging, metrics, tracing, and alerting strategy
@@ -272,7 +330,7 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda

 ---

-### Step 5: Deployment Procedures
+### Step 6: Deployment Procedures

 **Role**: DevOps / Platform engineer
 **Goal**: Define deployment strategy, rollback procedures, health checks, and deployment checklist
@@ -321,6 +379,69 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda

 ---

+### Step 7: Deployment Scripts
+
+**Role**: DevOps / Platform engineer
+**Goal**: Create executable deployment scripts for pulling Docker images and running services on the remote target machine
+**Constraints**: Produce real, executable shell scripts. This is the ONLY step that creates implementation artifacts.
+
+1. Read containerization.md and deployment_procedures.md from previous steps
+2. Read `.env.example` for required variables
+3. Create the following scripts in `SCRIPTS_DIR/`:
+
+**`deploy.sh`** — Main deployment orchestrator:
+   - Validates that required environment variables are set (sources `.env` if present)
+   - Calls `pull-images.sh`, then `stop-services.sh`, then `start-services.sh`, then `health-check.sh`
+   - Exits with non-zero code on any failure
+   - Supports `--rollback` flag to redeploy previous image tags
+
+**`pull-images.sh`** — Pull Docker images to target machine:
+   - Reads image list and tags from environment or config
+   - Authenticates with container registry
+   - Pulls all required images
+   - Verifies image integrity (digest check)
+
+**`start-services.sh`** — Start services on target machine:
+   - Runs `docker compose up -d` or individual `docker run` commands
+   - Applies environment variables from `.env`
+   - Configures networks and volumes
+   - Waits for containers to reach healthy state
+
+**`stop-services.sh`** — Graceful shutdown:
+   - Stops services with graceful shutdown period
+   - Saves current image tags for rollback reference
+   - Cleans up orphaned containers/networks
+
+**`health-check.sh`** — Verify deployment health:
+   - Checks all health endpoints
+   - Reports status per service
+   - Returns non-zero if any service is unhealthy
+
+4. All scripts must:
+   - Be POSIX-compatible (#!/bin/bash with set -euo pipefail)
+   - Source `.env` from project root or accept env vars from the environment
+   - Include usage/help output (`--help` flag)
+   - Be idempotent where possible
+   - Handle SSH connection to remote target (configurable via `DEPLOY_HOST` env var)
+
+5. Document all scripts in `deploy_scripts.md`
+
+**Self-verification**:
+- [ ] All five scripts created and executable
+- [ ] Scripts source environment variables correctly
+- [ ] `deploy.sh` orchestrates the full flow
+- [ ] `pull-images.sh` handles registry auth and image pull
+- [ ] `start-services.sh` starts containers with correct config
+- [ ] `stop-services.sh` handles graceful shutdown
+- [ ] `health-check.sh` validates all endpoints
+- [ ] Rollback supported via `deploy.sh --rollback`
+- [ ] Scripts work for remote deployment via SSH (DEPLOY_HOST)
+- [ ] `deploy_scripts.md` documents all scripts
+
+**Save action**: Write scripts to `SCRIPTS_DIR/`, write `deploy_scripts.md` using `templates/deploy_scripts.md`
+
+---
+
 ## Escalation Rules

 | Situation | Action |
@@ -331,31 +452,38 @@ At the start of execution, create a TodoWrite with all steps (1 through 5). Upda
 | Secret manager not chosen | **ASK user** |
 | Deployment pattern trade-offs | **ASK user** with recommendation |
 | Missing architecture.md | **STOP** — run `/plan` first |
+| Remote target machine details unknown | **ASK user** for SSH access, OS, and specs |

 ## Common Mistakes

- **Implementing during planning**: this workflow produces documents, not Dockerfiles or pipeline YAML
- **Hardcoding secrets**: never include real credentials in deployment documents
+- **Implementing during planning**: Steps 1–6 produce documents, not code (Step 7 is the exception — it creates scripts)
+- **Hardcoding secrets**: never include real credentials in deployment documents or scripts
 - **Ignoring integration test containerization**: the test environment must be containerized alongside the app
 - **Skipping BLOCKING gates**: never proceed past a BLOCKING marker without user confirmation
 - **Using `:latest` tags**: always pin base image versions
 - **Forgetting observability**: logging, metrics, and tracing are deployment concerns, not post-deployment additions
+- **Committing `.env`**: only `.env.example` goes to version control; `.env` must be in `.gitignore`
+- **Non-portable scripts**: deployment scripts must work across environments; avoid hardcoded paths

 ## Methodology Quick Reference

 ```
 ┌────────────────────────────────────────────────────────────────┐
-│            Deployment Planning (5-Step Method)                   │
+│            Deployment Planning (7-Step Method)                  │
 ├────────────────────────────────────────────────────────────────┤
 │ PREREQ: architecture.md + component specs exist                │
 │                                                                │
-│ 1. Containerization  → containerization.md                      │
+│ 1. Status & Env     → reports/deploy_status_report.md          │
+│                       + .env + .env.example                    │
+│    [BLOCKING: user confirms status & env vars]                 │
+│ 2. Containerization  → containerization.md                     │
 │    [BLOCKING: user confirms Docker plan]                       │
-│ 2. CI/CD Pipeline    → ci_cd_pipeline.md                        │
-│ 3. Environment       → environment_strategy.md                  │
-│ 4. Observability     → observability.md                         │
-│ 5. Procedures        → deployment_procedures.md                 │
+│ 3. CI/CD Pipeline    → ci_cd_pipeline.md                       │
+│ 4. Environment       → environment_strategy.md                 │
+│ 5. Observability     → observability.md                        │
+│ 6. Procedures        → deployment_procedures.md                │
 │    [BLOCKING: user confirms deployment plan]                   │
+│ 7. Scripts           → deploy_scripts.md + scripts/            │
 ├────────────────────────────────────────────────────────────────┤
 │ Principles: Docker-first · IaC · Observability built-in        │
 │             Environment parity · Save immediately              │
@@ -1,6 +1,6 @@
 # CI/CD Pipeline Template

-Save as `_docs/02_plans/deployment/ci_cd_pipeline.md`.
+Save as `_docs/04_deploy/ci_cd_pipeline.md`.

 ---

@@ -1,6 +1,6 @@
 # Containerization Plan Template

-Save as `_docs/02_plans/deployment/containerization.md`.
+Save as `_docs/04_deploy/containerization.md`.

 ---

@@ -0,0 +1,73 @@
+# Deployment Status Report Template
+
+Save as `_docs/04_deploy/reports/deploy_status_report.md`.
+
+---
+
+```markdown
+# [System Name] — Deployment Status Report
+
+## Deployment Readiness Summary
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| Architecture defined | ✅ / ❌ | |
+| Component specs complete | ✅ / ❌ | |
+| Infrastructure prerequisites met | ✅ / ❌ | |
+| External dependencies identified | ✅ / ❌ | |
+| Blockers | [count] | [summary] |
+
+## Component Status
+
+| Component | State | Docker-ready | Notes |
+|-----------|-------|-------------|-------|
+| [Component 1] | planned / implemented / tested | yes / no | |
+| [Component 2] | planned / implemented / tested | yes / no | |
+
+## External Dependencies
+
+| Dependency | Type | Required For | Status |
+|------------|------|-------------|--------|
+| [e.g., PostgreSQL] | Database | Data persistence | [available / needs setup] |
+| [e.g., Redis] | Cache | Session management | [available / needs setup] |
+| [e.g., External API] | API | [purpose] | [available / needs setup] |
+
+## Infrastructure Prerequisites
+
+| Prerequisite | Status | Action Needed |
+|-------------|--------|--------------|
+| Container registry | [ready / not set up] | [action] |
+| Cloud account | [ready / not set up] | [action] |
+| DNS configuration | [ready / not set up] | [action] |
+| SSL certificates | [ready / not set up] | [action] |
+| CI/CD platform | [ready / not set up] | [action] |
+| Secret manager | [ready / not set up] | [action] |
+
+## Deployment Blockers
+
+| Blocker | Severity | Resolution |
+|---------|----------|-----------|
+| [blocker description] | critical / high / medium | [resolution steps] |
+
+## Required Environment Variables
+
+| Variable | Purpose | Required In | Default (Dev) | Source (Staging/Prod) |
+|----------|---------|------------|---------------|----------------------|
+| `DATABASE_URL` | Postgres connection string | All components | `postgres://dev:dev@db:5432/app` | Secret manager |
+| `DEPLOY_HOST` | Remote target machine | Deployment scripts | `localhost` | Environment |
+| `REGISTRY_URL` | Container registry URL | CI/CD, deploy scripts | `localhost:5000` | Environment |
+| `REGISTRY_USER` | Registry username | CI/CD, deploy scripts | — | Secret manager |
+| `REGISTRY_PASS` | Registry password | CI/CD, deploy scripts | — | Secret manager |
+| [add all required variables] | | | | |
+
+## .env Files Created
+
+- `.env.example` — committed to VCS, contains all variable names with placeholder values
+- `.env` — git-ignored, contains development defaults
+
+## Next Steps
+
+1. [Resolve any blockers listed above]
+2. [Set up missing infrastructure prerequisites]
+3. [Proceed to containerization planning]
+```
@@ -1,6 +1,6 @@
 # Deployment Procedures Template

-Save as `_docs/02_plans/deployment/deployment_procedures.md`.
+Save as `_docs/04_deploy/deployment_procedures.md`.

 ---

@@ -1,6 +1,6 @@
 # Environment Strategy Template

-Save as `_docs/02_plans/deployment/environment_strategy.md`.
+Save as `_docs/04_deploy/environment_strategy.md`.

 ---

@@ -1,6 +1,6 @@
 # Observability Template

-Save as `_docs/02_plans/deployment/observability.md`.
+Save as `_docs/04_deploy/observability.md`.

 ---

@@ -0,0 +1,240 @@
+---
+name: problem
+description: |
+  Interactive problem gathering skill that builds _docs/00_problem/ through structured interview.
+  Iteratively asks probing questions until the problem, restrictions, acceptance criteria, and input data
+  are fully understood. Produces all required files for downstream skills (research, plan, etc.).
+  Trigger phrases:
+  - "problem", "define problem", "problem gathering"
+  - "what am I building", "describe problem"
+  - "start project", "new project"
+category: build
+tags: [problem, gathering, interview, requirements, acceptance-criteria]
+disable-model-invocation: true
+---
+
+# Problem Gathering
+
+Build a complete problem definition through structured, interactive interview with the user. Produces all required files in `_docs/00_problem/` that downstream skills (research, plan, decompose, implement, deploy) depend on.
+
+## Core Principles
+
+- **Ask, don't assume**: never infer requirements the user hasn't stated
+- **Exhaust before writing**: keep asking until all dimensions are covered; do not write files prematurely
+- **Concrete over vague**: push for measurable values, specific constraints, real numbers
+- **Save immediately**: once the user confirms, write all files at once
+- **User is the authority**: the AI suggests, the user decides
+
+## Context Resolution
+
+Fixed paths:
+
+- OUTPUT_DIR: `_docs/00_problem/`
+- INPUT_DATA_DIR: `_docs/00_problem/input_data/`
+
+## Prerequisite Checks
+
+1. If OUTPUT_DIR already exists and contains files, present what exists and ask user: **resume and fill gaps, overwrite, or skip?**
+2. If overwrite or fresh start, create OUTPUT_DIR and INPUT_DATA_DIR
+
+## Completeness Criteria
+
+The interview is complete when the AI can write ALL of these:
+
+| File | Complete when |
+|------|--------------|
+| `problem.md` | Clear problem statement: what is being built, why, for whom, what it does |
+| `restrictions.md` | All constraints identified: hardware, software, environment, operational, regulatory, budget, timeline |
+| `acceptance_criteria.md` | Measurable success criteria with specific numeric targets grouped by category |
+| `input_data/` | At least one reference data file or detailed data description document |
+| `security_approach.md` | (optional) Security requirements identified, or explicitly marked as not applicable |
+
+## Interview Protocol
+
+### Phase 1: Open Discovery
+
+Start with broad, open questions. Let the user describe the problem in their own words.
+
+**Opening**: Ask the user to describe what they are building and what problem it solves. Do not interrupt or narrow down yet.
+
+After the user responds, summarize what you understood and ask: "Did I get this right? What did I miss?"
+
+### Phase 2: Structured Probing
+
+Work through each dimension systematically. For each dimension, ask only what the user hasn't already covered. Skip dimensions that were fully answered in Phase 1.
+
+**Dimension checklist:**
+
+1. **Problem & Goals**
+   - What exactly does the system do?
+   - What problem does it solve? Why does it need to exist?
+   - Who are the users / operators / stakeholders?
+   - What is the expected usage pattern (frequency, load, environment)?
+
+2. **Scope & Boundaries**
+   - What is explicitly IN scope?
+   - What is explicitly OUT of scope?
+   - Are there related systems this integrates with?
+   - What does the system NOT do (common misconceptions)?
+
+3. **Hardware & Environment**
+   - What hardware does it run on? (CPU, GPU, memory, storage)
+   - What operating system / platform?
+   - What is the deployment environment? (cloud, edge, embedded, on-prem)
+   - Any physical constraints? (power, thermal, size, connectivity)
+
+4. **Software & Tech Constraints**
+   - Required programming languages or frameworks?
+   - Required protocols or interfaces?
+   - Existing systems it must integrate with?
+   - Libraries or tools that must or must not be used?
+
+5. **Acceptance Criteria**
+   - What does "done" look like?
+   - Performance targets: latency, throughput, accuracy, error rates?
+   - Quality bars: reliability, availability, recovery time?
+   - Push for specific numbers: "less than Xms", "above Y%", "within Z meters"
+   - Edge cases: what happens when things go wrong?
+   - Startup and shutdown behavior?
+
+6. **Input Data**
+   - What data does the system consume?
+   - Formats, schemas, volumes, update frequency?
+   - Does the user have sample/reference data to provide?
+   - If no data exists yet, what would representative data look like?
+
+7. **Security** (optional, probe gently)
+   - Authentication / authorization requirements?
+   - Data sensitivity (PII, classified, proprietary)?
+   - Communication security (encryption, TLS)?
+   - If the user says "not a concern", mark as N/A and move on
+
+8. **Operational Constraints**
+   - Budget constraints?
+   - Timeline constraints?
+   - Team size / expertise constraints?
+   - Regulatory or compliance requirements?
+   - Geographic restrictions?
+
+### Phase 3: Gap Analysis
+
+After all dimensions are covered:
+
+1. Internally assess completeness against the Completeness Criteria table
+2. Present a completeness summary to the user:
+
+```
+Completeness Check:
+- problem.md:             READY / GAPS: [list missing aspects]
+- restrictions.md:        READY / GAPS: [list missing aspects]
+- acceptance_criteria.md: READY / GAPS: [list missing aspects]
+- input_data/:            READY / GAPS: [list missing aspects]
+- security_approach.md:   READY / N/A / GAPS: [list missing aspects]
+```
+
+3. If gaps exist, ask targeted follow-up questions for each gap
+4. Repeat until all required files show READY
+
+### Phase 4: Draft & Confirm
+
+1. Draft all files in the conversation (show the user what will be written)
+2. Present each file's content for review
+3. Ask: "Should I save these files? Any changes needed?"
+4. Apply any requested changes
+5. Save all files to OUTPUT_DIR
+
+## Output File Formats
+
+### problem.md
+
+Free-form text. Clear, concise description of:
+- What is being built
+- What problem it solves
+- How it works at a high level
+- Key context the reader needs to understand the problem
+
+No headers required. Paragraph format. Should be readable by someone unfamiliar with the project.
+
+### restrictions.md
+
+Categorized constraints with markdown headers and bullet points:
+
+```markdown
+# [Category Name]
+
+- Constraint description with specific values where applicable
+- Another constraint
+```
+
+Categories are derived from the interview (hardware, software, environment, operational, etc.). Each restriction should be specific and testable.
+
+### acceptance_criteria.md
+
+Categorized measurable criteria with markdown headers and bullet points:
+
+```markdown
+# [Category Name]
+
+- Criterion with specific numeric target
+- Another criterion with measurable threshold
+```
+
+Every criterion must have a measurable value. Vague criteria like "should be fast" are not acceptable — push for "less than 400ms end-to-end".
+
+### input_data/
+
+At least one file. Options:
+- User provides actual data files (CSV, JSON, images, etc.) — save as-is
+- User describes data parameters — save as `data_parameters.md`
+- User provides URLs to data — save as `data_sources.md` with links and descriptions
+
+### security_approach.md (optional)
+
+If security requirements exist, document them. If the user says security is not a concern for this project, skip this file entirely.
+
+## Progress Tracking
+
+Create a TodoWrite with phases 1-4. Update as each phase completes.
+
+## Escalation Rules
+
+| Situation | Action |
+|-----------|--------|
+| User cannot provide acceptance criteria numbers | Suggest industry benchmarks, ASK user to confirm or adjust |
+| User has no input data at all | ASK what representative data would look like, create a `data_parameters.md` describing expected data |
+| User says "I don't know" to a critical dimension | Research the domain briefly, suggest reasonable defaults, ASK user to confirm |
+| Conflicting requirements discovered | Present the conflict, ASK user which takes priority |
+| User wants to skip a required file | Explain why downstream skills need it, ASK if they want a minimal placeholder |
+
+## Common Mistakes
+
+- **Writing files before the interview is complete**: gather everything first, then write
+- **Accepting vague criteria**: "fast", "accurate", "reliable" are not acceptance criteria without numbers
+- **Assuming technical choices**: do not suggest specific technologies unless the user constrains them
+- **Over-engineering the problem statement**: problem.md should be concise, not a dissertation
+- **Inventing restrictions**: only document what the user actually states as a constraint
+- **Skipping input data**: downstream skills (especially research and plan) need concrete data context
+
+## Methodology Quick Reference
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│           Problem Gathering (4-Phase Interview)                 │
+├────────────────────────────────────────────────────────────────┤
+│ PREREQ: Check if _docs/00_problem/ exists (resume/overwrite?)  │
+│                                                                │
+│ Phase 1: Open Discovery                                        │
+│   → "What are you building?" → summarize → confirm             │
+│ Phase 2: Structured Probing                                    │
+│   → 8 dimensions: problem, scope, hardware, software,          │
+│     acceptance criteria, input data, security, operations       │
+│   → skip what Phase 1 already covered                          │
+│ Phase 3: Gap Analysis                                          │
+│   → assess completeness per file → fill gaps iteratively       │
+│ Phase 4: Draft & Confirm                                       │
+│   → show all files → user confirms → save to _docs/00_problem/ │
+├────────────────────────────────────────────────────────────────┤
+│ Principles: Ask don't assume · Concrete over vague             │
+│             Exhaust before writing · User is authority          │
+└────────────────────────────────────────────────────────────────┘
+```