alerts original and scoped; write spec commmand changes

.claude/commands/product/write-spec.md

@@ -4,6 +4,31 @@
 
 Write a new feature spec from an idea, or scope a versioned iteration from an existing spec.
 
+## What a spec IS — and is NOT
+
+A spec is a **Product Requirements Document (PRD)**. It captures the **what** and the **why** from a user/product perspective. It does **not** capture the **how**.
+
+**Belongs in a spec:**
+- The user problem and who has it
+- User flows / user stories / acceptance criteria
+- Scope: what's in, what's out, and why
+- Success metrics (user/business outcomes)
+
+**A spec does NOT have an "Open Questions" section.** Open product questions must be **grilled with the user and resolved** before the spec is saved. The spec is the answer, not the question list. If a question can't be answered yet, either (a) explicitly defer that capability to a later version and add it to "What's deferred," or (b) state the chosen default in the spec and move on. Never leave ambiguity for engineering to resolve.
+
+**Does NOT belong in a spec** (these live in `plan.md`, written by `/engineering/plan-feature`):
+- Data models, schemas, tables, columns, field types
+- API endpoints, routes, request/response shapes
+- Specific libraries, frameworks, services, queues, workers
+- Code-level architecture (modules, classes, files)
+- Migration steps, infrastructure choices, deployment notes
+- "Technical Scope" or "Engineering Implementation" sections naming repos/services
+- Any sentence that prescribes *how* the thing will be built
+
+If you catch yourself writing `Alert` model fields, FK relationships, "Celery beat job," or "FastAPI endpoint" — stop. That's plan content. The spec describes user-visible behavior; engineering decides the implementation.
+
+The only acceptable engineering-adjacent content in a spec is a **Dependencies** line that names *other features* a version depends on (e.g. "Requires: Metric primitive from features/metrics_kpis/v1"). Not technologies.
+
 ## Process
 
 ### Step 1: Parse Input & Determine Mode
@@ -34,15 +59,14 @@ Use the senior-product-manager agent approach:
 1. **Understand the idea** — Parse the input, identify the core problem being solved.
 2. **Research context** — Search the codebase for related features, check existing features.
 3. **Pressure-test from user perspective** — Apply comprehension, confidence, workflow, trust, and independence tests for NGO users.
-4. **Structure the spec** with these sections:
+4. **Grill open questions with the user until resolved.** As you draft, list every product question that's unclear (default behavior, edge cases, UX of disputed flows, what's in vs out, ambiguous wording in the input). Ask them, in batches via `AskUserQuestion` where useful. Do NOT save the spec until every open question is either answered, explicitly deferred to a later version with rationale, or has an explicitly chosen default written into the spec. The final spec contains no "Open Questions" section.
+5. **Structure the spec** with these sections (product-only — no engineering content):
    - Problem Statement — What problem, for whom?
    - Target Users — Which Dalgo persona(s)?
-   - Success Metrics — How to measure success?
-   - User Stories — As a [role], I want [thing], so that [outcome]. With acceptance criteria.
-   - Scope — What's IN for MVP, what's OUT for later?
-   - Technical Implications — Which repos/services affected?
-   - Open Questions — What needs deciding before planning?
-   - Handoff Checklist — Is this ready for engineering?
+   - Success Metrics — User/business outcomes to measure.
+   - User Stories / User Flows — As a [role], I want [thing], so that [outcome]. With acceptance criteria written as user-visible behavior.
+   - Scope — What's IN for MVP, what's OUT for later, and why.
+   - Handoff Checklist — Is the product surface clear enough for engineering to plan against?
 
 ### Save
 Save to: `features/{feature-name}/spec.md`
@@ -102,24 +126,22 @@ Create `features/{feature-name}/v{N}/spec.md` with:
 ### What's deferred to later versions
 - [Deferred item] — [reason for deferral]
 
-## User Stories (scoped)
+## User Stories / User Flows (scoped)
 
 ### Story 1: [Title]
 **As a** [role], **I want** [capability], **so that** [outcome].
 
-**Acceptance Criteria:**
+**Acceptance Criteria** (written as user-visible behavior, not implementation):
 - [ ] [Criterion 1]
 - [ ] [Criterion 2]
 
-## Technical Scope
-- **DDP_backend**: [what changes in this version]
-- **webapp_v2**: [what changes in this version]
-
 ## Dependencies
-- Requires: [any prerequisites or previous version completion]
+- Requires: [other features or versions this depends on — not technologies]
 - Enables: [what future versions this unblocks]
 ```
 
+**No Open Questions section.** Before saving, grill the user on every unclear product decision (channel multi-select rules, default behavior on edge cases, what each picker shows, what's in vs deferred). Resolve each one — either an explicit answer baked into the spec, or an explicit deferral added to "What's deferred to later versions" with rationale.
+
 ### Print Next Step
 ```
 Scoped version saved to: features/{feature-name}/v{N}/spec.md
@@ -130,10 +152,12 @@ Next: /engineering/plan-feature features/{feature-name}/v{N}/spec.md
 ---
 
 ## Guidelines
+- **A spec describes user-visible behavior, not implementation.** No data models, API endpoints, libraries, services, or code architecture. If it could change based on engineering choices without changing what the user sees, it doesn't belong in the spec.
 - Be specific, not generic. Name real user roles, real workflows, real data.
 - Scope ruthlessly for MVP. Move nice-to-haves to "Out of Scope" explicitly.
 - Think in user workflows, not isolated features.
 - Each version should be independently shippable — users get value even if v2 never happens.
 - Don't over-scope v1. Ship a thin slice fast rather than a thick slice late.
 - Explicitly list what's deferred and why — makes scoping v2 easier.
 - If the original spec is small enough for one iteration, v1/spec.md can be a near-copy with tightened acceptance criteria.
+- If the original spec already contains engineering content (data models, technical scope sections), do NOT carry it forward into the versioned spec. Strip it. Engineering content belongs in `plan.md`, not `spec.md`.