Most requirements start in the wrong place
"We need a reporting dashboard with 20 charts."
You build it. Three weeks. Ship it. They use 3 of the 20 charts. The actual problem was slow data access, not visualization. Two weeks of engineering time, gone.
This methodology reverses the order. Instead of starting with the stakeholder's solution, you start with their problem:
CP.01: "Managers must access sales data within 5 seconds to make decisions."
From that problem, you derive the need (CN: real-time data access), then the requirement (FR: data API + 3 targeted charts). Built in one week. Solves what actually matters.
How it works
Six steps. Each builds on the previous. Your AI assistant guides the conversation.
What governs this project?
Project identity, constraints, success criteria. Establishes principles for all downstream decisions.
/business-contextWhat is broken, and for whom?
Identify and classify problems by severity: Obligation (must solve), Expectation (should solve), Hope (could solve).
/customer-problemsWhat might help?
High-level solution sketch. Components, boundaries, interfaces. Shared understanding before details.
/software-glanceWhat must the system deliver?
Required outcomes per problem. Measurable, testable, scoped. Each need traces to a specific problem.
/customer-needsHow will it work?
Architecture, technical approach, constraints, stakeholder alignment. The technical roadmap.
/software-visionWhat are the details?
Detailed, testable behavior specifications. Each requirement traces backward to a need and a problem.
/functional-requirementsEvery requirement traces backward. You can always answer: "Why are we building this?"
Not all problems are equal
The methodology classifies each problem by severity, so priority reflects actual impact.
High priority. Legal, contractual, or operational failure if unsolved. Build this first.
Medium priority. Degraded business outcomes if unsolved. Core value and user satisfaction.
Low priority. Missed improvement opportunity if unsolved. Build this last.
Get started
Install
Ask your AI assistant:
Install the Problem-Based SRS skills from RafaelGorski/Problem-Based-SRS into .github/skills/For Claude Code, use .claude/skills/ instead. See the README for all installation methods.
Run your first session
/problem-based-srsDescribe your situation. The AI guides you through all six steps:
I need requirements for an inventory management system.
Our warehouse tracks everything in spreadsheets and loses $50k/month due to errors.What you get
Traced artifacts from business context through functional requirements, stored in your project's .spec/ directory. Every requirement links back to the customer problem it solves.
Commands
| Command | Purpose | Step |
|---|---|---|
| /problem-based-srs | Full methodology, all steps | All |
| /business-context | Project identity and constraints | 0 |
| /customer-problems | Identify and classify problems | 1 |
| /software-glance | Sketch solution approach | 2 |
| /customer-needs | Define required outcomes | 3 |
| /software-vision | Architecture and scope | 4 |
| /functional-requirements | Detailed, testable requirements | 5 |
| /zigzag-validator | Verify traceability across artifacts | Validate |
| /complexity-analysis | Axiomatic Design quality analysis | Optional |
Works with AgentSkills-compatible tools: GitHub Copilot, Claude Code, Claude.ai, Gemini CLI, and others.
Research and standards
Based on the methodology by Gorski & Stadzisz, published as peer-reviewed research.
DOI: 10.21529/RESI.2016.1502002
Requirement-writing guidance aligns with ISO/IEC/IEEE 29148:2018 for requirement quality, structured syntax, and bidirectional traceability. Normative keywords follow BCP 14 (RFC 2119 / RFC 8174) when written in ALL CAPITALS.
Case studies: CRM system walkthrough and renewable energy system walkthrough.