customer-problems

Original source / Raw SKILL.md

---
name: customer-problems
description: Identify and document Customer Problems (CP) from business context. Use when starting requirements engineering or when stakeholders describe solutions instead of problems. Step 1 of Problem-Based SRS methodology.
license: MIT
metadata:
  author: rafael-gorski
  version: "1.2"
  methodology: problem-based-srs
  step: 1
---

# Customer Problems (CP)

> **Step 1** of the Problem-Based SRS methodology  
> **Domain:** WHY — Explains why the solution is needed  
> **Prerequisite:** Step 0 — Business Context (business-context skill)

## Purpose

Guide AI coding agents through identifying, documenting, and validating Customer Problems from business context. Customer Problems represent the **WHY domain** — they provide the business justification for why a software solution is needed. All subsequent artifacts (Software Glance, Customer Needs, Software Vision, Requirements) derive from CPs.

**Best input:** A structured Business Context (Step 0) with project identity, business principles, stakeholders, current situation, and domain boundaries. If no Business Context exists, consider running the `business-context` skill first.

---

## Scope

| Aspect | Boundary |
|--------|----------|
| **This skill does** | Discover problems from context, normalize statements, and validate quality |
| **This skill does NOT** | Define solutions or derive requirements |
| **Input from** | Step 0: Business Context (preferred) OR ad-hoc business context |
| **Output to** | Step 2: Software Glance (software-glance skill) |

---

## Two Modes of Operation

### Mode 1: CP Generation
Use when starting from **business context** to discover and document problems.

### Mode 2: CP Review & Normalization  
Use when you have **draft CP statements** that need quality review and formatting.

---

## Mode 1: CP Generation

### Your Task
Analyze the provided business context and generate Customer Problem statements.

### Input Required
- **Business Context (preferred):** Step 0 output (`00-business-context.md`) with project identity, principles, stakeholders, current situation, and domain boundaries
- **Alternative:** Description of the business domain, current situation, and scope (if Step 0 was skipped)
- **Stakeholder Information:** Who experiences the problems (optional but helpful)

### Discovery Questions

Ask these questions to elicit problems:

1. **Obligations:**
   - What legal or contractual requirements must be met?
   - What regulations apply to this business?
   - What happens if compliance fails?

2. **Expectations:**
   - What do customers/users expect that isn't being delivered?
   - What business goals are not being met?
   - What standards should be achieved but aren't?

3. **Hopes:**
   - What improvements would stakeholders like to see?
   - What optimizations are desired?
   - What new capabilities are wished for?

4. **Consequences:**
   - What happens if these issues aren't addressed?
   - What is the cost of the current situation?
   - Who is impacted and how severely?

---

## Mode 2: CP Review & Normalization

### Your Task
For each draft problem:
1. **Normalize** into the CP syntax: `[Subject] [Verb] [Object] [Penalty]`
2. **Classify** as **Obligation**, **Expectation**, or **Hope**
3. **Flag missing elements** (subject, object, penalty, or severity verb)
4. **Ask clarifying questions** only when required data is missing

---

## CP Structured Notation

Each Customer Problem MUST follow this syntax:

```
[Subject] [Verb] [Object] [Penalty/Consequence]
```

**Components:**
- **Subject:** Who suffers the problem (company, manager, customer, department)
- **Verb:** Indicates severity class (must/expects/hopes)
- **Object:** The difficulty or requirement
- **Penalty:** Consequence if problem persists

---

## Problem Classification

Classify each CP by severity:

| Class | Severity | Verbs | Description |
|-------|----------|-------|-------------|
| **Obligation** | High | must, have to, is required to | Legal/contractual; severe consequences if unmet |
| **Expectation** | Medium | expects, should, anticipates | Business goal; moderate impact if unmet |
| **Hope** | Low | hopes, aims, desires, wishes | Improvement; minimal penalty if unmet |

---

## Output Format

**⚠ ID Format:** Always use `CP-` with a dash (e.g., `CP-001`, `CP-002`). Do NOT use dots (e.g., `CP.01`).

### For Mode 1 (Generation)

For each identified problem, produce:

```markdown
### CP-001: [Brief Title]

**Statement:** [Subject] [Verb] [Object] [Penalty]

**Classification:** [Obligation | Expectation | Hope]

**Subject:** [Who has this problem]

**Consequence if Unsolved:**
- [Negative impact 1]
- [Negative impact 2]

**Benefit if Solved:**
- [Positive outcome 1]
- [Positive outcome 2]
```

### For Mode 2 (Review)

```markdown
## Normalized Customer Problems

| CP ID | Normalized Statement | Class | Missing Info |
|-------|----------------------|-------|--------------|
| CP-[ID] | [Subject] [Verb] [Object] [Penalty] | [Obligation/Expectation/Hope] | [None or list] |

## Clarification Questions (if any)
- [Question 1]
- [Question 2]
```

---

## Examples

### Example 1: Obligation
```markdown
### CP-001: Regulatory Compliance

**Statement:** The company must submit emission compliance reports within 30 days of each quarter end otherwise faces fines up to 5% of revenue.

**Classification:** Obligation

**Subject:** The company (compliance department)

**Consequence if Unsolved:**
- Financial penalties (5% revenue)
- Regulatory sanctions
- Public reputation damage

**Benefit if Solved:**
- Regulatory compliance maintained
- Avoid financial penalties
- Maintain operating license
```

### Example 2: Expectation
```markdown
### CP-002: Customer Response Time

**Statement:** Customers expect responses to support inquiries within 24 hours otherwise they become dissatisfied and may switch to competitors.

**Classification:** Expectation

**Subject:** Customers (end users)

**Consequence if Unsolved:**
- Customer dissatisfaction
- Increased churn rate
- Negative reviews

**Benefit if Solved:**
- Improved customer satisfaction
- Higher retention rates
- Positive word-of-mouth
```

### Example 3: Hope
```markdown
### CP-003: Sales Forecasting

**Statement:** Management hopes to predict quarterly sales with 85% accuracy otherwise strategic planning remains reactive rather than proactive.

**Classification:** Hope

**Subject:** Management (sales leadership)

**Consequence if Unsolved:**
- Suboptimal resource allocation
- Missed market opportunities
- Reactive decision making

**Benefit if Solved:**
- Better resource planning
- Proactive market positioning
- Improved profitability
```

---

## Quality Criteria

Ensure each CP:
- ✅ Uses the structured notation (Subject + Verb + Object + Penalty)
- ✅ Has a clear classification (Obligation/Expectation/Hope)
- ✅ Identifies the subject who experiences the problem
- ✅ Specifies consequences if unsolved
- ✅ Specifies benefits if solved
- ✅ Is problem-focused, NOT solution-focused
- ✅ Uses natural language (no technical jargon)

---

## Problem Decomposition

### When to Decompose

Decompose a CP into sub-CPs when:

| Trigger | Example |
|---------|---------|
| Multiple distinct facets | CP-001 has communication AND frequency aspects |
| Different subjects affected | CP-001 affects both company AND customers |
| Independent penalties | Failure of one aspect doesn't cause all penalties |
| Separate solutions likely | Each facet could be solved by different FRs |

### Numbering Convention

```
CP-001        → Main problem
CP-001.1      → First sub-problem of CP-001
CP-001.2      → Second sub-problem of CP-001
CP-001.2.1    → Sub-sub-problem (rarely needed)
```

### Decomposition Example

**Before decomposition:**
```
CP-001: The company must ensure effective communication with customers, 
      otherwise it loses customers affecting marketing and sales.
```

**After decomposition:**
```
CP-001: The company must ensure effective communication with customers, 
      otherwise it loses customers affecting marketing and sales.

CP-001.1: The company must ensure it can contact all customers 
        (having valid contact information).

CP-001.2: The company must ensure each customer is contacted regularly 
        (frequency of communication).
```

---

## Anti-Patterns to Avoid

| ❌ Wrong | ✅ Correct |
|----------|-----------|
| "We need a mobile app" | "Field staff cannot access inventory data outside office" |
| "System is slow" | "Report generation takes >5 minutes causing missed deadlines" |
| "Improve UX" | "Users abandon checkout 40% of time due to confusing navigation" |
| "Need better reporting" | "Managers must submit compliance reports within 10 days or face fines" |

---

## Validation Checklist

Before proceeding to Step 2 (Software Glance), verify:

- [ ] All identified problems are documented as CPs
- [ ] Each CP uses structured notation
- [ ] Every CP includes Subject, Verb, Object, Penalty
- [ ] Verb matches correct severity class
- [ ] Classifications assigned to all CPs
- [ ] Consequences and benefits documented
- [ ] Stakeholders agree these represent real business problems
- [ ] No solutions are embedded in problem statements

---

## Handoff to Next Step

When CPs are complete, provide:

```
✅ Step 1 Complete: Customer Problems Specified

Summary:
- [N] Obligations identified
- [N] Expectations identified  
- [N] Hopes identified

Artifacts:
[List CP-IDs with brief titles]

→ Next Step: 2 - Software Glance
→ Use skill: software-glance
→ Input: The CPs documented above
```

---

## References
- Problem-Based SRS Paper (Gorski & Stadzisz)

**Version:** 1.2  
**Step:** 1 of 5  
**Next:** software-glance skill