Problem-Based SRS

🎯 Overview

An Agent Skill following the Problem-Based Software Requirements Specification (SRS) methodology. Designed for integration with AI agents like GitHub Copilot and Claude Code.

⚡ The Problem We Solve

Have you ever spent weeks building a feature, only to discover it didn't solve the actual problem? You're not alone. The #1 cause of software project failures is building what stakeholders asked for instead of what they actually need.

Real Example:
Stakeholder says: "We need a reporting dashboard with 20 charts."
You build it: 3 weeks of work.
Reality: They only use 3 charts. The real problem was slow data access, not visualization.

Result: Wasted effort, missed opportunity, frustrated team.

💡 Our Solution

Problem-Based SRS helps engineers discover real customer problems before writing any code. Your AI coding assistant guides you through a proven 5-step process that ensures every feature you build traces back to an actual business need.

Spend 30 minutes upfront with your AI agent to save weeks of building the wrong thing.

🎯 What You'll Get

🔍 Discover Real Problems

Identify what customers actually need before writing code

🎯 Align with Impact

Every line of code traces back to a problem it solves

⚡ Reduce Rework

Catch misunderstandings in minutes, not after weeks

🚀 Ship with Confidence

Know exactly why each feature matters and to whom

🤖 AI-Guided Process

Works with GitHub Copilot, Claude, and other AI agents

📊 Clear Priorities

Know what's critical vs nice-to-have based on problem severity

Research-Backed: Based on peer-reviewed methodology by Gorski and Stadzisz, published in academic research on software requirements specification.
DOI: 10.21529/RESI.2016.1502002

📊 The 5-Step Methodology

A systematic process that ensures you discover problems first, then design solutions. Each step builds on the previous to maximize your impact:

Step 1: Customer Problems (CP)

Identify the WHY - understand business pain and classify by problem class (Obligation / Expectation / Hope — roughly must-have / should-have / could-have)

✅ You get: Clear focus on what matters most, justification for every feature

/customer-problems

Step 2: Software Glance

Sketch high-level solution approach - components, interfaces, boundaries

✅ You get: Shared understanding with team, architectural direction

/software-glance

Step 3: Customer Needs (CN)

Define the WHAT - outcomes the system must deliver to solve the problems

✅ You get: Success criteria, measurable goals, scope boundaries

/customer-needs /zigzag-validator (validate)

Step 4: Software Vision

Detail architecture, features, constraints, and technical approach

✅ You get: Technical roadmap, stakeholder alignment, design decisions

/software-vision

Step 5: Functional Requirements (FR)

Define the HOW - detailed, testable requirements for implementation

✅ You get: Implementation checklist, acceptance criteria, full traceability

/functional-requirements /zigzag-validator (validate)

💡 Why This Order Matters:
Starting with problems (WHY) before solutions (HOW) ensures you build the right thing. Engineers who skip problem discovery often build features that look good but don't solve actual needs.

🔄 Development Workflow Integration

🔗 Artifact Traceability

Every requirement traces back to ensure it solves real problems. Each artifact is interconnected:

📊 Problem Classification

Customer Problems are classified by severity to prioritize what must be solved:

Obligation (Must/Required): High priority - severe consequences if unsolved (legal/contractual)
Expectation (Should/Expects): Medium priority - moderate impact if unsolved (business goals)
Hope (Wishes): Low priority - minimal penalty if unsolved (improvements)

🚀 Quick Start for Engineers

Step 1: Install the Skill

Ask your AI assistant to install it:

Install the Problem-Based SRS skill from RafaelGorski/Problem-Based-SRS

Many AI agents (including GitHub Copilot and Claude Code) can install AgentSkills when you ask them, but the exact installation steps vary by agent.

If your agent does not install it automatically, follow the Installation Options in the README to copy the skill manually or use the AgentSkills CLI.

Step 2: Start Your First Session

Using Skills (All AI Agents)

The skill is available in skills/problem-based-srs/. In VS Code, Visual Studio, JetBrains IDEs, or Claude:

/customer-problems        # Start with Customer Problems
/software-glance          # Create Software Glance
/customer-needs           # Generate Customer Needs
/software-vision          # Build Software Vision
/functional-requirements  # Specify Functional Requirements
/zigzag-validator         # Validate traceability
/complexity-analysis      # Optional: Axiomatic Design analysis
/problem-based-srs        # Full methodology orchestration

Using with Any AI Agent (Universal)

The methodology works with any LLM (ChatGPT, DeepSeek, Claude, Llama, etc.).

AgentSkills (Open Standard)

The skills/ directory follows the AgentSkills standard, compatible with any tool that implements it.

For GitHub Copilot: The skill will auto-discover from the skills directory.
For Claude Code: The skill will auto-discover when this repository is in your workspace.
For Claude.ai: Upload the skill from skills/problem-based-srs/ (including the references folder).

For New Features

Simply describe your business context or problem:

I need to create requirements for [feature name]

Business Context: [describe current situation and problem]

Example:
"I need requirements for an inventory management system.
Our warehouse tracks everything in spreadsheets and loses
$50k/month due to errors."

The AI will automatically:

✅ Guide you through all 5 steps
✅ Ask clarifying questions to uncover real problems
✅ Help you prioritize by problem severity
✅ Ensure traceability from problems to requirements
✅ Save your work as structured documents

Available Commands

Use these commands in VS Code, Visual Studio, JetBrains IDEs, or Claude:

/problem-based-srs        # Full methodology - start here for new projects
/customer-problems        # Customer Problems - identify business pain
/software-glance          # Software Glance - sketch solution approach
/customer-needs           # Customer Needs - define required outcomes
/software-vision          # Software Vision - detail architecture
/functional-requirements  # Functional Requirements - specify implementation
/zigzag-validator         # Validate traceability - quality check

Common Scenarios

🆕 New Feature

Use: /problem-based-srs

Start from scratch and go through all 5 steps with your AI guiding you.

🔍 Review Existing Requirements

Use: /functional-requirements then /zigzag-validator

Validate that requirements trace back to real problems.

💡 Stakeholder Proposes Solution

Use: /customer-problems

Dig deeper to uncover the actual problem they're trying to solve.

✅ Quality Check

Use: /zigzag-validator

Verify all requirements trace to customer needs and problems.

💡 Pro Tip: The skill works with any AI agent that supports the AgentSkills standard (GitHub Copilot, Claude Code, Claude.ai, etc.). Just upload the skill files or let your AI auto-discover them from your workspace.

💡 Real-World Use Cases

How engineers use Problem-Based SRS in different situations:

🆕 New Feature Development

Situation: Product manager asks for "a dashboard with analytics"

Your approach: Use /customer-problems to discover the real problem - turns out they need "real-time alerts when KPIs drop below threshold"

Result: Build the right thing (alerting) not the requested thing (dashboard)

🔍 Requirements Refinement

Situation: You inherited vague requirements from another team

Your approach: Use /zigzag-validator to validate traceability, identify gaps, then use /customer-problems to fill missing problems

Result: Clear, traceable requirements that justify every feature

💡 Problem Discovery

Situation: Stakeholders propose technical solutions ("Use Redis cache!")

Your approach: Use /customer-problems with discovery mode to ask "What problem does this solve?"

Result: Uncover actual need (faster queries) and evaluate best solution

⚖️ Priority Negotiation

Situation: Everything is "high priority" from stakeholders

Your approach: Use problem classification (Obligation/Expectation/Hope) to rank by severity

Result: Data-driven prioritization based on business impact

📋 Sprint Planning

Situation: Converting user stories to technical tasks

Your approach: Use /customer-needs for acceptance criteria, /functional-requirements for implementation tasks

Result: Clear sprint goals with traceable work items

✅ Code Review Context

Situation: Reviewing a PR and wondering "why this approach?"

Your approach: Check FR traceability to see which problem it solves

Result: Context-aware review focused on solving the actual problem

🔧 Integration with Development Workflow

During Sprint Planning

Use /customer-problems to capture user stories as customer problems
Use /customer-needs to define acceptance criteria
Use /functional-requirements to break down into technical requirements

During Feature Design

Reference /software-glance for high-level approach
Reference /software-vision for architectural decisions
Use /zigzag-validator to ensure design addresses all needs

During Implementation

Keep /functional-requirements requirements as implementation checklist
Trace each requirement back to CN and CP for context
Update requirements if new problems discovered

During Code Review

Verify implementation satisfies /functional-requirements requirements
Check requirements still trace to customer needs
Validate no scope creep beyond identified problems

📚 Additional Resources

Repository Structure

This repository provides both agents and skills in the AgentSkills format:

Agents

agents/problem-based-srs/ - Orchestrator agent for full methodology

Skills (Individual Steps)

For GitHub Copilot, Claude Code, Claude.ai, and other AI agents:

skills/problem-based-srs/ - Main orchestrator skill
- references/crm-example.md - Complete CRM walkthrough
- references/microer-example.md - Energy system walkthrough
skills/customer-problems/ - Step 1: CP generation
skills/software-glance/ - Step 2: Software Glance design
skills/customer-needs/ - Step 3: CN specification
skills/software-vision/ - Step 4: Software Vision design
skills/functional-requirements/ - Step 5: FR/NFR generation
skills/zigzag-validator/ - Traceability validation
skills/complexity-analysis/ - Optional: Axiomatic Design analysis

Additional Documentation

docs/ - Full methodology and research paper
README.md - Quick start guide and examples
CONTRIBUTING.md - Contribution guidelines

Get Started Today

Ready to improve your requirements engineering with AI-assisted methodology?

View on GitHub View Skills Release 1.1

🎉 Release 1.1 (February 2026)

We're excited to announce version 1.1 with Complexity Analysis and enhanced methodology features!

🆕 What's New in 1.1

Complexity Analysis (/complexity-analysis): Optional Axiomatic Design-based quality analysis for critical systems
- Independence axiom analysis (coupled/redundant/ideal specifications)
- Design matrix evaluation
- Information content assessment
Case Study Examples: Condensed walkthroughs for learning
- crm-example.md - CRM system from business context to requirements
- microer-example.md - Renewable energy system (technical domain)
C/P Completeness Markers: Enhanced traceability with Complete/Partial indicators
Problem Decomposition Guidance: When and how to break down Customer Problems
Expanded CN Outcome Classes: Detailed examples for Information, Control, Construction, Entertainment
Agile Integration Patterns: Sprint 0 planning, per-feature CP→CN→FR chains, minimal viable SRS

📦 Included from 1.0

AgentSkills Format: Full compatibility with GitHub Copilot, Claude Code, Claude.ai, and other AI agents
Complete 5-Step Methodology: Customer Problems → Software Glance → Customer Needs → Software Vision → Functional Requirements
Traceability Validation: ZigZag validator ensures all requirements trace back to real business problems
Python Test Infrastructure: 57+ tests validating YAML, markdown structure, and traceability IDs
Comprehensive Documentation: Detailed reference guides for each methodology step

View the full changelog for details.