From problem-based-srs
Orchestrates Problem-Based SRS methodology to derive traceable functional requirements from business problems via 6 structured steps and sub-skills.
npx claudepluginhub rafaelgorski/problem-based-srsThis skill uses the workspace's default tool permissions.
> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119) [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) when, and only when, they appear in all capitals, as shown here.
Elicits requirements through structured questioning and generates high-quality SRS documents aligned with ISO/IEC/IEEE 29148 when no prior specs exist.
Generates Functional Requirements (FR) and Non-Functional Requirements (NFR) from Customer Needs and Software Vision, creating individual traceable files. Step 5 of Problem-Based SRS methodology.
Share bugs, ideas, or general feedback.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC 2119 RFC 8174 when, and only when, they appear in all capitals, as shown here.
Orchestrate requirements engineering using the Problem-Based SRS methodology (Gorski & Stadzisz). This skill coordinates a structured process (Step 0 through Step 5) that ensures every requirement traces back to a real business problem.
Diagram standard: Use Mermaid UML diagrams as the preferred format for all visual artifacts. Mermaid is mandatory for Software Glance (Step 2) and Software Vision (Step 4), and preferred for other steps where diagrams add value.
Stakeholder Input
β
ββββββββββββββββββββ
β Step 0: BC β β Use skill: business-context
β Business Context β
ββββββββββ¬ββββββββββ
β
ββββββββββββββββββββ
β Step 1: CP β β Use skill: customer-problems
β Customer Problemsβ
ββββββββββ¬ββββββββββ
β
ββββββββββββββββββββ
β Step 2: SG β β Use skill: software-glance
β Software Glance β
ββββββββββ¬ββββββββββ
β
ββββββββββββββββββββ
β Step 3: CN β β Use skill: customer-needs
β Customer Needs β
ββββββββββ¬ββββββββββ
β
ββββββββββββββββββββ
β Step 4: SV β β Use skill: software-vision
β Software Vision β
ββββββββββ¬ββββββββββ
β
ββββββββββββββββββββ
β Step 5: FR/NFR β β Use skill: functional-requirements
β Requirements β
ββββββββββββββββββββ
Traceability Chain: FR β CN β CP (every requirement traces back to a problem)
Domain Mapping (WHY β WHAT β HOW):
| Domain | Artifact | Question Answered |
|---|---|---|
| WHY | Customer Problems (CP) | Why is the solution needed? (Business justification) |
| WHAT | Customer Needs (CN) | What outcomes must the software provide? |
| HOW | Functional Requirements (FR) | How will the system behave? |
This orchestrator coordinates the following skills:
| Skill | Command | Purpose |
|---|---|---|
business-context | /business-context | Step 0: Establish structured business context and principles |
customer-problems | /customer-problems | Step 1: Identify and classify customer problems |
software-glance | /software-glance | Step 2: Create high-level solution view |
customer-needs | /customer-needs | Step 3: Specify customer needs (outcomes) |
software-vision | /software-vision | Step 4: Define software vision and architecture |
functional-requirements | /functional-requirements | Step 5: Generate functional requirements |
zigzag-validator | /zigzag-validator | Validate traceability across domains |
complexity-analysis | /complexity-analysis | Optional: Axiomatic Design quality analysis |
IMPORTANT: At each step, you MUST save the produced artifacts to files. Progress is NOT automatically saved between sessions.
NEVER create multiple artifact files in parallel. Always create files one at a time, sequentially β wait for each file to be saved before creating the next one. Batch/parallel file creation causes JSON serialization errors in tool calls when the combined content is too large.
When starting a new project, ask the user:
Before we begin, where would you like to save your SRS artifacts?
Options:
1. `docs/srs/` (recommended - keeps SRS separate from code docs)
2. `requirements/` (alternative - at project root)
3. Custom path: [specify your preferred location]
All artifacts will be saved in this folder with consistent naming.
Create the following folder structure as you progress through each step:
[chosen-folder]/ # e.g., docs/srs/
βββ 00-business-context.md # Step 0: Business context, principles, and constraints
βββ 01-customer-problems.md # Step 1: CPs (WHY)
βββ 02-software-glance.md # Step 2: High-level solution view
βββ 03-customer-needs.md # Step 3: CNs (WHAT)
βββ 04-software-vision.md # Step 4: Architecture and scope
βββ functional-requirements/ # Step 5: Individual FR files
β βββ _index.md # FR summary and traceability matrix
β βββ FR-001.md # Individual FR file
β βββ FR-002.md # Individual FR file
β βββ ... # One file per FR
βββ non-functional-requirements/ # NFR files (quality attributes)
β βββ _index.md # NFR summary
β βββ NFR-001.md # Individual NFR file
β βββ ... # One file per NFR
βββ traceability-matrix.md # CP β CN β FR complete mapping
Each Functional Requirement and Non-Functional Requirement is saved as a separate file so that:
Each FR file follows this template:
# FR-XXX: [Brief Title]
## Requirement
**Statement:** The [System] shall [verb] [object] [constraint] [condition].
**Priority:** [Must Have | Should Have | Could Have | Won't Have]
**Status:** [Draft | Review | Approved | Implemented | Tested]
## Traceability
| Traces To | ID | Description |
|-----------|-----|-------------|
| Customer Need | CN-XXX | [Brief CN description] |
| Customer Problem | CP-XXX | [Brief CP description] |
## Acceptance Criteria
- [ ] Criterion 1 (testable)
- [ ] Criterion 2 (testable)
- [ ] Criterion 3 (testable)
## Notes
[Any additional context, assumptions, or dependencies]
<!-- β οΈ NO CODE SNIPPETS: Do not include code examples, SQL, or implementation details here.
Construction details belong in design/ folder (see design/implementation-notes/) -->
---
*Created: [Date]*
*Last Updated: [Date]*
*Author: [Name]*
# NFR-XXX: [Brief Title]
## Requirement
**Category:** [Performance | Security | Usability | Reliability | Scalability | Maintainability]
**Statement:** The [System] shall [quality attribute with measurable criteria].
**Priority:** [Must Have | Should Have | Could Have | Won't Have]
**Status:** [Draft | Review | Approved | Implemented | Tested]
## Traceability
| Traces To | ID | Description |
|-----------|-----|-------------|
| Customer Need | CN-XXX | [Brief CN description] |
| Applies To FRs | FR-XXX, FR-YYY | [Related functional requirements] |
## Acceptance Criteria
- [ ] Criterion 1 (measurable)
- [ ] Criterion 2 (measurable)
## Measurement Method
[How this NFR will be verified/tested]
<!-- β οΈ NO CODE SNIPPETS: Do not include code examples or implementation details here.
Technical specifications belong in design/ folder -->
---
*Created: [Date]*
*Last Updated: [Date]*
After completing each step, ALWAYS:
Example handoff for Step 5:
β
Step 5 Complete: Functional Requirements Specified
π Saved to: docs/srs/functional-requirements/
βββ _index.md (summary with 8 FRs)
βββ FR-001.md β CN-001 (User Registration)
βββ FR-002.md β CN-001 (User Authentication)
βββ FR-003.md β CN-002 (Data Validation)
βββ FR-004.md β CN-002 (Error Handling)
βββ FR-005.md β CN-003 (Report Generation)
βββ FR-006.md β CN-003 (Export Functionality)
βββ FR-007.md β CN-004 (Search Capability)
βββ FR-008.md β CN-004 (Filter Options)
π Updated: docs/srs/traceability-matrix.md
Engineers can now work on individual requirements independently.
Each FR file contains full context and acceptance criteria.
Create this file at the start of every project using the business-context skill.
The business context captures: project identity, business principles (Mandatory/Guiding/Aspirational), stakeholders with influence levels, current situation (process, pain points, existing systems), domain boundaries, constraints with impact assessment, and measurable success criteria.
Use the
business-contextskill for the full template, discovery questions, and examples.
When user provides business context or problem description:
business-context skill to establish structured context00-business-context.md with the structured business contextIf user has existing artifacts (CPs, CNs, etc.):
At any point, use zigzag-validator skill to check consistency.
Determine current step by checking what artifacts exist:
| If user has... | Current Step | Use Skill | Save To |
|---|---|---|---|
| Nothing / business idea only | 0 | business-context | 00-business-context.md |
| Business Context (BC) | 1 | customer-problems | 01-customer-problems.md |
| Customer Problems (CPs) | 2 | software-glance | 02-software-glance.md |
| CPs + Software Glance | 3 | customer-needs | 03-customer-needs.md |
| CPs + CNs + Software Glance | 4 | software-vision | 04-software-vision.md |
| CPs + CNs + Software Vision | 5 | functional-requirements | functional-requirements/*.md |
Purpose: Establish structured business context and project principles
Input: Stakeholder conversations, project briefs, existing documentation
Output: Business context document with identity, principles, stakeholders, boundaries, constraints, success criteria
Save to: 00-business-context.md
Skill: business-context
Purpose: Identify and document business problems
Input: Business Context (Step 0)
Output: List of CPs classified as Obligation/Expectation/Hope
Syntax: [Subject] [must/expects/hopes] [Object] [Penalty]
Save to: 01-customer-problems.md
Skill: customer-problems
Purpose: Create initial abstract solution view
Input: Customer Problems
Output: High-level system description with boundaries and components
Save to: 02-software-glance.md
Skill: software-glance
Purpose: Specify outcomes software must provide
Input: CPs + Software Glance
Output: CNs with outcome classes (Information/Control/Construction/Entertainment)
Syntax: [Subject] needs [system] to [Verb] [Object] [Condition]
Save to: 03-customer-needs.md
Skill: customer-needs
Purpose: Define high-level scope and positioning
Input: CNs + Software Glance
Output: Vision document with stakeholders, features, architecture
Save to: 04-software-vision.md
Skill: software-vision
Purpose: Generate detailed requirements
Input: CNs + Software Vision
Output: Individual FR and NFR files with traceability
Syntax FR: The [System] shall [Verb] [Object] [Constraint] [Condition]
Save to: functional-requirements/FR-XXX.md and non-functional-requirements/NFR-XXX.md
Skill: functional-requirements
IMPORTANT: Zigzag validation using zigzag-validator skill is MANDATORY after Steps 3 and 5 to verify traceability and identify gaps.
00-business-context.md01-customer-problems.md02-software-glance.md03-customer-needs.md04-software-vision.mdfunctional-requirements/non-functional-requirements/_index.md)design/ folder (not in FR/NFR files)traceability-matrix.mdIf user attempts to skip to solutions, redirect:
Detect: User mentions specific technology, feature, or implementation before CPs exist
Redirect:
I notice you're describing a solution. Let's first understand the problem.
Before we design [mentioned solution], help me understand:
1. What is the business context? (β business-context skill)
2. What business obligation, expectation, or hope drives this need?
3. What negative consequences occur without this?
4. Who is impacted?
β Loading: business-context skill (if no BC exists)
β Loading: customer-problems skill (if BC exists)
| Artifact | Syntax Pattern |
|---|---|
| CP | [Subject] [must/expects/hopes] [Object] [Penalty] |
| CN | [Subject] needs [system] to [Verb] [Object] [Condition] |
| FR | The [System] shall [Verb] [Object] [Constraint] [Condition] |
| NFR | The [System] shall [quality attribute with measurable criteria] |
When completing each step:
Example:
β
Step 3 Complete: Customer Needs Specified
π Saved to: docs/srs/03-customer-needs.md
Outputs:
- CN-001: [Information] User needs system to display...
- CN-002: [Control] Admin needs system to manage...
- CN-003: [Information] Manager needs system to report...
Gate Check:
- [x] All CNs use structured notation
- [x] Outcome classes assigned
- [x] Every CP has at least one CN
- [x] File saved
β Next: Step 4 - Software Vision
β Loading: references/step4-software-vision.md
β Will save to: docs/srs/04-software-vision.md
β Input: The CNs documented above
Start with Step 0 (Business Context) and progress through all steps sequentially. Remember: Ask where to save files, establish business context first.
Detect what artifacts exist, skip completed steps, resume at current step. Remember: Check for existing SRS folder and read current files.
Complete initial pass, then iterate on specific steps as understanding improves. Remember: Update existing files rather than creating new ones.
Use zigzag-validator skill to check existing artifacts without generating new ones.
After Step 5, engineers can pick up individual FR files and develop independently. Each FR file contains all context needed (traceability, acceptance criteria).
Use Problem-Based SRS iteratively within agile workflows:
For quick prototypes or MVPs:
For deeper quality analysis, users can explicitly invoke the complexity-analysis skill for Axiomatic Design-based specification quality analysis. Use for critical systems, large specifications, or formal reviews. This is NOT part of the standard flow.
For complete walkthroughs, see:
Use skills individually based on current step to minimize context usage.