Stop building the wrong thing. If you've ever spent weeks building a feature only to discover it didn't solve the actual problem—or worse, solved the wrong problem—this methodology is for you.
Let your AI agent guide you through proven requirements engineering that starts with real customer problems, not feature wish lists. Works with GitHub Copilot, Claude, and other AI coding assistants to help you create software requirements that actually solve business problems and maximize the impact of your work.
This methodology helps engineers:
- ✅ Discover real problems - Identify what customers actually need before writing any code
- ✅ Align your work with business impact - Every line of code traces back to a problem it solves
- ✅ Avoid wasted effort - Stop building "nice-to-have" features disguised as critical requirements
- ✅ Ship with confidence - Know exactly why each feature matters and to whom
- ✅ Reduce rework - Catch misunderstandings early, before weeks of coding are invested
- ✅ AI-guided process - Your coding assistant walks you through each step automatically
Based on peer-reviewed research by Gorski & Stadzisz, this approach systematically addresses the #1 cause of software project failures: building what stakeholders asked for instead of what they actually need.
Before Problem-Based SRS:
- Stakeholder: "We need a reporting dashboard with 20 charts."
- You: Build it over 3 weeks.
- Result: They only use 3 charts. The real problem was slow data access, not visualization.
With Problem-Based SRS:
- Step 1: Discover the actual problem → "Managers must access sales data within 5 seconds to make decisions."
- Step 2: Design solution → Simple data API + 3 key charts.
- Result: Built in 1 week. Solves the real problem. Stakeholders happy.
ROI: Spend 30 minutes upfront with your AI agent to save weeks of building the wrong thing.
Here's what happens when you use this methodology:
Your input:
I need requirements for an inventory management system. Our warehouse
tracks everything in spreadsheets and loses $50k/month due to errors.
The AI guides you through:
-
Business Context (CONTEXT)
- Project: "InventoryPro" — Warehouse logistics
- Principle: "Inventory data must reflect physical reality within 0.1% tolerance" (Mandatory)
- Success: "Reduce inventory discrepancy from $50k to $5k/month"
-
Customer Problems (WHY)
- CP.01: "Warehouse must track inventory accurately otherwise $50k/month lost to errors"
- CP.02: "Staff expects real-time inventory visibility otherwise delays in fulfillment"
-
Software Glance
- "Web-based inventory system with barcode scanning and real-time sync"
-
Customer Needs (WHAT)
- CN.01.1: "Warehouse needs system to track inventory with 99.9% accuracy"
- CN.02.1: "Staff needs system to scan items and update inventory within 2 seconds"
-
Software Vision
- "Cloud inventory platform with mobile scanning app for 50 concurrent users"
-
Functional Requirements (HOW)
- FR.01.1.1: "System shall maintain 99.9% accuracy in inventory counts"
- FR.02.1.1: "System shall scan barcodes and update inventory database within 2 seconds"
Result: Every requirement traces back to the $50k problem. You build only what solves the actual business need. No wasted features.
Perfect for:
- Software Engineers building features from vague stakeholder requests
- Tech Leads ensuring team builds the right thing
- Product Engineers validating ideas before sprint planning
- Solution Architects aligning technical design with business problems
- Anyone using AI coding assistants who wants better requirements
Use it when:
- Starting a new feature or project
- Stakeholders describe solutions instead of problems ("We need a dashboard!")
- Requirements are unclear or conflicting
- You need to justify technical decisions with business value
- Reviewing existing requirements for quality
Step 1: Install (one-time setup)
Ask your AI assistant:
Install the Problem-Based SRS skill from RafaelGorski/Problem-Based-SRS
Step 2: Start your first requirements session
/problem-based-srs
Your AI will guide you through the complete process interactively.
First time? Just tell your AI about your project challenge. Example: "We need a mobile app for field technicians who can't access customer data offline." The AI will handle the rest.
Once installed, use these commands to work with different parts of the methodology:
| Command | When to Use | What It Does |
|---|---|---|
/problem-based-srs |
Starting a new project | Guides you through all steps from scratch |
/business-context |
Establishing project context | Captures business context, principles, and constraints (CONTEXT) |
/customer-problems |
Analyzing business problems | Identifies and classifies customer problems (WHY) |
/software-glance |
Quick project overview | Creates high-level software summary |
/customer-needs |
Defining what to build | Translates problems into customer needs (WHAT) |
/software-vision |
Planning architecture | Documents software architecture and vision |
/functional-requirements |
Writing requirements | Specifies detailed functional requirements (HOW) |
/zigzag-validator |
Quality check | Validates that all requirements trace to problems |
/complexity-analysis |
Deep analysis (optional) | Axiomatic Design quality analysis for critical systems |
Common scenarios:
- 🆕 New project? → Use
/problem-based-srsto start from scratch (begins with/business-context) - 📋 Need structured context? → Use
/business-contextto establish business principles and boundaries - 🔍 Reviewing existing requirements? → Use
/functional-requirementsthen/zigzag-validatorto validate - 💡 Stakeholders proposing solutions instead of problems? → Use
/customer-problemsto dig deeper - ✅ Need to verify requirements quality? → Use
/zigzag-validatorfor traceability check
The methodology follows a proven process that ensures you discover problems first, then design solutions:
graph LR
A[Stakeholder Input] --> B0[Step 0: Business Context - CONTEXT]
B0 --> B[Step 1: Customer Problems - WHY]
B --> C[Step 2: Software Glance]
C --> D[Step 3: Customer Needs - WHAT]
D --> E[Step 4: Software Vision]
E --> F[Step 5: Functional Requirements - HOW]
F --> G[Ready to Code]
style B0 fill:#dda0dd
style B fill:#ff6b6b
style C fill:#4ecdc4
style D fill:#45b7d1
style E fill:#96ceb4
style F fill:#ffeaa7
The WHY → WHAT → HOW progression ensures:
- ✅ You understand the business problem before designing solutions
- ✅ Every requirement traces back to a real customer pain point
- ✅ Priorities are clear (must-solve vs nice-to-have)
- ✅ You maximize impact by focusing on what actually matters
- ✅ Stakeholders see their problems reflected in your work
Each step builds on the previous: 0. CONTEXT (Business Context) → Establish principles and boundaries ("What governs this project?")
- WHY (Customer Problems) → Identify business pain ("What's broken?")
- Software Glance → Sketch solution approach ("What might help?")
- WHAT (Customer Needs) → Define required outcomes ("What must it do?")
- Software Vision → Detail architecture and scope ("How will it work?")
- HOW (Requirements) → Specify exact behavior ("What are the details?")
Customer Problems are classified by severity so you know what to build first:
graph TD
CP[Customer Problem] --> O{Classification}
O -->|Must, Required| OB[Obligation<br/>High Priority<br/>Legal/Contractual]
O -->|Expects, Should| EX[Expectation<br/>Medium Priority<br/>Business Goal]
O -->|Hopes, Wishes| HO[Hope<br/>Low Priority<br/>Improvement]
OB --> I1[Severe consequences<br/>if unsolved]
EX --> I2[Moderate impact<br/>if unsolved]
HO --> I3[Minimal penalty<br/>if unsolved]
style OB fill:#ff6b6b
style EX fill:#ffa502
style HO fill:#ffeaa7
Why this matters to you:
- Obligation (Must) → Build this first. Compliance, legal, contractual requirements.
- Expectation (Should) → Build this next. Core business value and user satisfaction.
- Hope (Wishes) → Build this last. Nice-to-have improvements and optimizations.
This ensures you're not treating "nice to have" features the same as "business critical" requirements. Maximize impact by focusing engineering time on high-severity problems first.
Install directly as a Claude Code plugin:
# Test locally during development
claude --plugin-dir ./Problem-Based-SRS
# Or install from repository
/plugin install https://github.com/RafaelGorski/Problem-Based-SRSAfter installation, skills are available with the problem-based-srs: namespace:
/problem-based-srs:customer-problems- Customer Problems/problem-based-srs:customer-needs- Customer Needs/problem-based-srs:functional-requirements- Functional Requirements
The easiest way—just ask your AI assistant:
Install the Problem-Based SRS skill from RafaelGorski/Problem-Based-SRS
Your AI will handle the installation automatically. Works with GitHub Copilot, Claude, and other agents.
Click to expand manual installation instructions
Install to your personal skills directory:
# Clone the repository
git clone https://github.com/RafaelGorski/Problem-Based-SRS.git
# Copy to your AI agent's skills directory
# For Claude Code:
cp -r Problem-Based-SRS/skills/problem-based-srs ~/.claude/skills/
# For GitHub Copilot:
cp -r Problem-Based-SRS/skills/problem-based-srs ~/.copilot/skills/Skills directory by AI agent:
| Agent | macOS/Linux | Windows |
|---|---|---|
| Claude Code | ~/.claude/skills/ |
%USERPROFILE%\.claude\skills\ |
| GitHub Copilot | ~/.copilot/skills/ |
%USERPROFILE%\.copilot\skills\ |
| Gemini CLI | ~/.gemini/skills/ |
%USERPROFILE%\.gemini\skills\ |
| Cline | ~/.cline/skills/ |
%USERPROFILE%\.cline\skills\ |
| Goose | ~/.config/goose/skills/ |
%USERPROFILE%\.config\goose\skills\ |
Install into your repository so everyone on the team automatically gets it:
Using the AgentSkills CLI:
npx skills add RafaelGorski/Problem-Based-SRSOr manually:
# Clone the repository
git clone https://github.com/RafaelGorski/Problem-Based-SRS.git
# Copy to your project's skills directory
# For GitHub Copilot:
cp -r Problem-Based-SRS/skills/problem-based-srs your-project/.github/skills/
# For Claude Code:
cp -r Problem-Based-SRS/skills/problem-based-srs your-project/.claude/skills/
# Commit to version control
cd your-project
git add .github/skills/ # or .claude/skills/
git commit -m "Add Problem-Based SRS methodology"Project-level skills directories:
| Agent | Project Directory |
|---|---|
| GitHub Copilot | .github/skills/ |
| Claude Code | .claude/skills/ |
| Cursor | .cursor/skills/ |
Tip: Project-level installation ensures your entire team follows the same requirements methodology and the skill is automatically available in CI/CD.
- Research Paper - The peer-reviewed methodology by Gorski & Stadzisz
- Contributing - Help improve the methodology
- Changelog - Version history and updates
Traceability = Accountability: Every functional requirement (FR) traces to a customer need (CN), which traces to a customer problem (CP). This means you can answer "Why are we building this?" for every line of code. No more building features that nobody uses.
WHY → WHAT → HOW = Engineering Efficiency: The methodology enforces this logical progression:
- WHY (Customer Problems) = The business pain you're solving → Gives you focus
- WHAT (Customer Needs) = Capabilities required to solve it → Defines success criteria
- HOW (Functional Requirements) = Specific features to implement → Your implementation guide
Impact: When stakeholders ask for changes, you can quickly assess impact by checking which problems are affected. When prioritizing work, you prioritize by problem severity, not by who shouts loudest.
AgentSkills Format: This repository uses the AgentSkills open standard and Claude Code Plugins format, making it compatible with Claude Code, Claude.ai, GitHub Copilot, and other AI agents.
Released February 2026 with:
- NEW:
/complexity-analysiscommand for optional Axiomatic Design quality analysis - NEW: Condensed case study examples (CRM and MicroER systems)
- NEW: C/P (Complete/Partial) completeness markers in traceability
- NEW: Business Context step (
/business-context) for structured project context and principles - NEW: Problem decomposition guidance with heuristics
- NEW: Expanded CN outcome class examples (Control, Construction, Entertainment)
- NEW: Agile/sprint integration patterns
- Complete methodology (Step 0-5) with traceability validation
- AgentSkills format for GitHub Copilot, Claude, and other AI agents
- Comprehensive documentation based on peer-reviewed research
This repository follows the Claude Code plugins standard:
Problem-Based-SRS/
├── .claude-plugin/
│ └── plugin.json # Plugin manifest
├── agents/
│ └── problem-based-srs/ # Agent orchestrator
│ └── AGENT.md
├── skills/
│ ├── problem-based-srs/ # Main SRS methodology skill
│ │ ├── SKILL.md
│ │ └── references/ # Examples only
│ │ ├── crm-example.md
│ │ └── microer-example.md
│ ├── business-context/ # Step 0: Business context and principles
│ │ └── SKILL.md
│ ├── customer-problems/ # Step 1: WHY
│ │ └── SKILL.md
│ ├── software-glance/ # Step 2: High-level view
│ │ └── SKILL.md
│ ├── customer-needs/ # Step 3: WHAT
│ │ └── SKILL.md
│ ├── software-vision/ # Step 4: Architecture
│ │ └── SKILL.md
│ ├── functional-requirements/ # Step 5: HOW
│ │ └── SKILL.md
│ ├── zigzag-validator/ # Traceability validation
│ │ └── SKILL.md
│ └── complexity-analysis/ # Optional: Axiomatic Design
│ └── SKILL.md
├── hooks/
│ └── hooks.json # Hook configurations
├── settings.json # Default plugin settings
└── docs/ # Research paper and methodology
- CHANGELOG.md - Version history
- docs/ - Research paper and methodology details
- agents/problem-based-srs/ - Agent orchestrator for AI agents
- skills/ - Individual skills for each methodology step
problem-based-srs/references/crm-example.md- Complete CRM case study walkthroughproblem-based-srs/references/microer-example.md- Renewable energy system walkthrough
For deeper quality analysis on critical systems, you can explicitly call /complexity-analysis to:
- Analyze specification independence (coupled vs. uncoupled)
- Use C/P (Complete/Partial) completeness markers
- Apply Axiomatic Design principles
This is not part of the standard flow—use it when you need formal quality gates.
Built with ❤️ by the requirements engineering community | Report Issues | MIT License