0a_problem_validation

Workspace Preflight

Before doing stage/helper work:

1. Resolve the repository root.
2. Check the core Gofer sentinels:
   • .specify/.gofer-version
   • .specify/commands/0_business_scenario.md
   • .specify/templates/spec-template.md
   • .specify/scripts/bash/create-new-feature.sh
   • .specify/scripts/node/parse-stage-command.mjs
   • .specify/scripts/hooks/post-tool-use.mjs
   • .specify/scripts/powershell/install-optional-tools.ps1
   • .specify/templates/gofer-model-policy.yaml
   • .specify/memory/gofer-model-policy.yaml
   • .specify/specs/
   • .specify/memory/
3. Check host-specific repo-owned files when relevant:
   • Claude: AGENTS.md, CLAUDE.md, .claude/settings.json
   • Codex: AGENTS.md
   • Copilot: .github/copilot-instructions.md
   • VS Code extension mirrors Claude/Copilot/Gemini resources itself and should still keep the core scaffold healthy
4. If the repo already has the workspace checker script, prefer running:
   • node .specify/scripts/node/gofer-workspace-check.mjs --host codex --json
5. If the workspace is missing or stale, ask exactly:
   • "This repo is missing or stale for Gofer. Initialize/update it now?"
6. If the user says yes, run the Gofer workspace bootstrap helper and then resume this command from the top.
7. If the user says no, stop and explain that Gofer stage/helper work depends on the repo-owned scaffold.

---

description: Validate business problem using 5 Whys analysis, stakeholder impact mapping, and market landscape research before any solution design

Gofer Problem Validation

Token And Cost Policy

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.

User Input

$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

.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:

> **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

.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

  /0a_problem_validation  ← YOU ARE HERE
       ↓ AUTO
  /1_gofer_research
       ↓ AUTO
  /2_gofer_specify
       ↓ AUTO
  ... (rest of pipeline)
       ↓ AUTO
  /7a_stakeholder_comms