eai-cli 0.0.0-bootstrap.0

package/resources/gofer/commands/0a_problem_validation.md

@@ -0,0 +1,405 @@
+---
+name: 0a_problem_validation
+description: "Validate the business problem using 5 Whys root-cause analysis and stakeholder mapping."
+title: "Problem Validation"
+category: pipeline
+surfaces:
+  - claude
+  - claude-mirror
+  - copilot
+  - vscode
+  - codex
+  - gemini
+  - github-prompts
+  - agents-skills
+  - system-skills
+aliases: [gofer:validate-problem]
+---
+---
+description:
+  Validate business problem using 5 Whys analysis, stakeholder impact mapping,
+  and market landscape research before any solution design
+---
+
+# Gofer Problem Validation
+
+## EAI Platform Session Preflight
+
+Before any Gofer stage/helper command does pipeline work:
+
+1. Treat durable delivery as EAI Platform delivery by default, with Azure second
+   and every other stack only by explicit exception.
+2. Run `eai whoami` and confirm the EAI CLI is installed, the user is logged in,
+   and an active tenant is visible.
+3. If `eai` is missing, `eai whoami` fails, the token is expired, or no active
+   tenant is available, stop and run `/gofer:eai-first-run` or ask the user to
+   approve login/setup before continuing.
+4. For EAI app delivery, do not continue into research, specification, planning,
+   tasks, implementation, or validation until
+   `.specify/specs/{feature}/eai-preflight.md` records login, tenant, template,
+   app-readiness, and next-action evidence.
+5. Do not write tokens, secrets, private tenant IDs, or local `.env` values into
+   Gofer artifacts; record only product-safe readiness status and evidence.
+
+## Token And Cost Policy
+<!-- gofer:token-cost-policy:start -->
+
+Before spawning agents, calling tools, or loading large files:
+
+1. Treat `.specify/memory/gofer-model-policy.yaml` as the repo-owned source of truth for simple, medium, hard, and arbiter model routing. If it is missing, run `/gofer:bootstrap-workspace` before continuing.
+2. Use the cheapest capable model first.
+   - Claude: Haiku for scouting/extraction; Sonnet for normal implementation, synthesis, validation, and security; Opus for high-risk arbitration or release-critical failures.
+   - Codex/OpenAI: GPT mini for simple coding; GPT nano only for locate/classify/summarize/mechanical work; GPT-5.3-Codex or flagship GPT for tool-heavy coding, architecture, and release-critical validation.
+   - Gemini: Flash-Lite for cheap large-context scan/summarize; Flash for default research synthesis; Pro for large-context architecture or high-risk arbitration.
+   - Copilot: prefer Auto for simple and default work; ask the user before choosing a paid/high-tier picker model for hard security, architecture, or release gates.
+3. Keep raw tool output out of the main conversation context. Save stable findings to `.specify/specs/{feature}/context-bundle.md`, then work from summaries.
+4. Use provider prompt/context caching only for stable, non-secret prefixes: Gofer scaffold, AGENTS/CLAUDE/Copilot instructions, constitution, repo map, stage contracts, and validation rubric.
+5. Before continuing after large research, planning, implementation, or validation bursts, checkpoint the durable artifacts and compact/clear/resume context when the host supports it.
+6. Escalate model tier only when a cheaper pass is low-confidence, contradictory, security-sensitive, or blocking release quality.
+<!-- gofer:token-cost-policy:end -->
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+This stage sits BEFORE `/1_gofer_research` in the pipeline. Your job is to:
+
+1. Deconstruct the problem statement
+2. Run 5 Whys root cause analysis
+3. Map stakeholder impact
+4. Assess business case (cost of doing nothing vs value of solving)
+5. Check if software is even the right answer
+6. Research the market for existing solutions
+7. Track initial assumptions
+8. Produce a validated Problem Brief
+
+**Output**: `.specify/specs/{feature}/problem-brief.md`,
+`.specify/specs/{feature}/assumptions.md`
+
+---
+
+## Step 0: Context Health Check
+
+```bash
+.specify/scripts/bash/check-context-health.sh
+```
+
+- If **< 50%**: Proceed normally
+- If **50-70%**: Be concise with outputs
+- If **> 70%**: Start new session with handoff summary
+
+---
+
+## Step 1: Get Problem Statement
+
+If no problem description provided in $ARGUMENTS:
+
+Use the AskUserQuestion tool:
+
+**"What business problem are you trying to solve?"**
+
+| Option | Description                                          |
+| ------ | ---------------------------------------------------- |
+| Custom | Describe the problem in your own words (Recommended) |
+
+Encourage the user to describe the PROBLEM, not the SOLUTION. If they describe a
+solution ("I need a dashboard"), probe deeper: "What problem would the dashboard
+solve?"
+
+---
+
+## Step 2: Create Feature Directory
+
+Once you have the problem statement:
+
+1. **Generate a short name** (2-4 words) for the feature
+2. Run `.specify/scripts/bash/create-new-feature.sh --json "$DESCRIPTION"` with
+   `--short-name "your-short-name"` to create the feature directory
+3. Parse JSON output for FEATURE_DIR and BRANCH_NAME
+
+---
+
+## Step 3: Problem Deconstruction
+
+Parse the user's problem statement and extract:
+
+- **Stated Problem**: What they said is wrong
+- **Implied Solution**: What they think should be built (if any)
+- **Context Clues**: Industry, scale, urgency
+- **Emotional Signals**: Frustration points, pain intensity
+
+Present back to the user:
+
+**"Let me make sure I understand the problem correctly:"**
+
+| Element          | My Understanding         |
+| ---------------- | ------------------------ |
+| Core Problem     | [extracted]              |
+| Who's Affected   | [extracted]              |
+| Current Impact   | [extracted or "unknown"] |
+| Implied Solution | [extracted or "none"]    |
+
+Use AskUserQuestion: "Is this correct? Would you like to adjust anything?"
+
+---
+
+## Step 4: Run 5 Whys Analysis
+
+Spawn the business-problem-validator agent:
+
+```
+Task: subagent_type="business-problem-validator", model="sonnet"
+Prompt: "Validate this business problem using 5 Whys analysis:
+
+Problem: [USER'S PROBLEM STATEMENT]
+Context: [ANY ADDITIONAL CONTEXT]
+
+Perform:
+1. 5 Whys root cause analysis
+2. Stakeholder impact mapping
+3. Business case assessment
+4. Problem-solution fit check
+
+Return structured report (<2000 tokens)."
+```
+
+---
+
+## Step 5: Market Landscape Research
+
+Spawn the market scanner agent **in parallel** with the problem validator:
+
+```
+Task: subagent_type="research-market-scanner", model="haiku"
+Prompt: "Research the market landscape for this business problem:
+
+Problem: [USER'S PROBLEM STATEMENT]
+Industry: [EXTRACTED FROM CONTEXT]
+
+Find:
+1. Commercial SaaS solutions that address this
+2. Open-source alternatives
+3. Industry standards or regulations
+4. Build vs Buy analysis
+
+Return structured report (<2000 tokens)."
+```
+
+**Run both agents in parallel.**
+
+---
+
+## Step 6: Synthesize Findings
+
+Once both agents complete:
+
+### 6.1 Present Root Cause
+
+Use AskUserQuestion to confirm the root cause:
+
+**"Based on my analysis, the root cause appears to be:"**
+
+| Element        | Finding                                     |
+| -------------- | ------------------------------------------- |
+| Stated Problem | [What user said]                            |
+| Root Cause     | [From 5 Whys]                               |
+| Gap            | [How far stated problem is from root cause] |
+
+| Option                                   | Description                  |
+| ---------------------------------------- | ---------------------------- |
+| A. Root cause is correct                 | Proceed with this root cause |
+| B. Root cause needs adjustment           | Let me clarify further       |
+| C. I want to solve the symptom, not root | Focus on the stated problem  |
+
+### 6.2 Present Market Findings
+
+Use AskUserQuestion to get build/buy decision:
+
+**"I found these existing solutions in the market:"**
+
+| Option           | Description                                              |
+| ---------------- | -------------------------------------------------------- |
+| A. Build custom  | No existing solution fits — we should build from scratch |
+| B. Buy/subscribe | [Solution X] looks like a good fit — investigate further |
+| C. Hybrid        | Use [Solution X] as foundation, customize on top         |
+| D. Not sure      | I need more information to decide                        |
+
+### 6.3 Present Business Case
+
+Display the impact assessment:
+
+```
+╔══════════════════════════════════════════════════════╗
+║  BUSINESS CASE SUMMARY                               ║
+╠══════════════════════════════════════════════════════╣
+║                                                       ║
+║  Problem: [Root cause in plain English]               ║
+║                                                       ║
+║  Cost of Doing Nothing: [$/hours per year]            ║
+║  Estimated Value of Solving: [$/hours per year]       ║
+║  Payback Period: [weeks/months]                       ║
+║                                                       ║
+║  Software Needed? [Yes/No/Partial]                    ║
+║  Recommendation: [PROCEED/INVESTIGATE/RECONSIDER]     ║
+║                                                       ║
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Step 7: Generate Problem Brief
+
+Write to `{FEATURE_DIR}/problem-brief.md` using the template at
+`.specify/templates/problem-brief-template.md`.
+
+Populate with:
+
+- User's confirmed root cause
+- Stakeholder impact from validator agent
+- Business case metrics
+- Market landscape findings
+- Build/buy decision
+- All identified assumptions
+
+---
+
+## Step 8: Generate Initial Assumptions Register
+
+Write to `{FEATURE_DIR}/assumptions.md` using the template at
+`.specify/templates/assumptions-template.md`.
+
+Extract assumptions from:
+
+- Problem statement (business assumptions)
+- Market research (competitive assumptions)
+- Root cause analysis (causal assumptions)
+- Stakeholder mapping (user behavior assumptions)
+
+Mark ALL assumptions as `UNVALIDATED` at this stage.
+Populate the **Drift Controls** table with an owner, expiry/revalidation date,
+trigger, and reopen stage for every assumption that could invalidate the plan
+later.
+
+---
+
+## Step 8a: Always Emit Market and Business Analysis Artifacts (FR-035)
+
+Regardless of the `competitiveAnalysisEnabled` constitutional setting, this
+stage MUST emit BOTH baseline traceability artifacts so downstream stages and
+audits can find them at deterministic paths:
+
+- `{FEATURE_DIR}/market-analysis.md` — competitive landscape and build-vs-buy
+  reasoning. When `competitiveAnalysisEnabled=false`, this file is still created
+  and contains a clearly worded **disabled-state notice** explaining that
+  competitive analysis was skipped per constitution and that the section is
+  reserved for future enrichment.
+- `{FEATURE_DIR}/business-analysis.md` — business case, ROI sketch,
+  cost-of-doing-nothing summary, and stakeholder impact mapping. Emitted
+  unconditionally; this is the primary record consumed by
+  `/7a_stakeholder_comms` and the validation council.
+
+When `competitiveAnalysisEnabled=false`, the market-analysis.md file includes
+the following stub at the top so consumers can detect the disabled state
+programmatically:
+
+```markdown
+> **Notice:** Competitive analysis is disabled in this project's constitution
+> (`competitiveAnalysisEnabled: false`). This file is emitted as a baseline
+> traceability artifact only and contains no competitor research. Re-enable in
+> `.specify/memory/constitution.md` if you want full market analysis on the next
+> pipeline run.
+```
+
+Both files participate in the same audit trail and are referenced from the
+`7_gofer_save` checkpoint and the `7a_stakeholder_comms` package.
+
+---
+
+## Step 9: Report and Continue
+
+After saving artifacts:
+
+```
+════════════════════════════════════════════════════════════════
+  PROBLEM VALIDATED: [Feature Name]
+════════════════════════════════════════════════════════════════
+
+  Root Cause: [One sentence]
+  Business Case: [Cost of doing nothing] vs [Value of solving]
+  Market: [Build/Buy/Hybrid decision]
+  Assumptions: [N] tracked ([N] critical)
+
+  Artifacts:
+  - {FEATURE_DIR}/problem-brief.md
+  - {FEATURE_DIR}/assumptions.md
+  - {FEATURE_DIR}/market-analysis.md
+  - {FEATURE_DIR}/business-analysis.md
+
+  Recommendation: [PROCEED/INVESTIGATE/RECONSIDER]
+
+════════════════════════════════════════════════════════════════
+```
+
+If recommendation is PROCEED or user confirms they want to continue:
+
+**AUTO-CHAIN (MANDATORY)**: You MUST immediately invoke the next pipeline stage
+by calling the Skill tool with skill="/1_gofer_research". Do NOT ask the user
+for confirmation. Do NOT output "Ready for next stage". Just invoke the skill
+NOW.
+
+If recommendation is RECONSIDER:
+
+Present alternatives and let user decide whether to proceed or stop.
+
+---
+
+## Step 10: Observability Logging
+
+```bash
+.specify/scripts/bash/log-stage.sh 0a_problem_validation --complete --tokens [N] --compactions [N]
+```
+
+---
+
+## Important Notes
+
+- **Write for business people** — no technical jargon in outputs
+- **Challenge assumptions** — don't take the problem at face value
+- **Quantify impact** — use numbers, not adjectives
+- **Consider process solutions** — code is expensive, process is cheap
+- **Keep it short** — max 15 minutes of user interaction
+- **Don't propose solutions** — this stage is about the PROBLEM, not the answer
+- **Track everything as assumptions** — they get validated later in the pipeline
+
+---
+
+## "Explain Like I'm a Consultant" Mode
+
+All outputs from this stage are written in business language by default. This
+stage sets the tone for the entire pipeline when `audience: business` is set.
+
+Check `.specify/memory/constitution.md` for audience setting. If
+`audience: business` is set, pass this context to all subsequent pipeline stages
+so they include plain-English companion sections in their outputs.
+
+---
+
+## Quick Reference: Pipeline Position
+
+```text
+  /0a_problem_validation  ← YOU ARE HERE
+       ↓ AUTO
+  /1_gofer_research
+       ↓ AUTO
+  /2_gofer_specify
+       ↓ AUTO
+  ... (rest of pipeline)
+       ↓ AUTO
+  /7a_stakeholder_comms
+```