Getting started
Install the skills into GitHub Copilot, Claude Code, or Claude.ai, confirm /problem-based-srs is available, and run a single step to see how artifacts land in .spec/.
Everything you can run with Problem-Based SRS
Problem-Based SRS is a plugin that extends your AI harness — Copilot first — to handle Software Specifications. Start a session in minutes, learn the ideas behind the traceability chain, wire it into your pipeline, and browse every command and Navigator feature in one place.
Start in three steps
Install the skills into your assistant, run the methodology, then open the result as a graph.
01
Install
RafaelGorski/Problem-Based-SRS
Ask your assistant to add the skills into .github/skills/ (or .claude/skills/).
02
Run
/problem-based-srs
Describe your situation. The agent walks you from context to requirements.
03
Visualize
/live
Open the SRS Navigator and explore the spec as a living graph.
Or jump straight to the step you need:
Tutorials
Guided walkthroughs, from a blank project to refining a spec alongside the agent.
Your first session
Describe a real situation in one paragraph, then let the agent guide the full sequence: business context, customer problems, a software glance, needs, a software vision, and functional requirements. End with 100% traceability from every requirement back to a problem.
Then open the NavigatorLearn from your codebase
Inherited a system with no spec? Open the Navigator on an existing project and choose Learn & Create Spec. It harvests evidence from your code, README, and docs, brings it back as a short round of questions to confirm what actually hurts, then drafts problems, needs, and requirements for you to refine.
See how the Navigator drafts itCore concepts
The three ideas that make a Problem-Based specification hang together.
The traceability chain
Every artifact answers one question and links to the next. A Customer Problem states why, a Customer Need states what, and a Functional Requirement states how. You can always walk backward from a line of work to the problem that justifies it.
CP CN FR
The .spec folder
Artifacts are written to a hidden .spec/ folder at the project root, so the specification lives beside the code it drives, versioned in git.
.spec/
├─ 00-business-context.md
├─ 01-customer-problems.md
├─ 02-software-glance.md
├─ 03-customer-needs.md
├─ 04-software-vision.md
├─ functional-requirements/
│ └─ FR.01.1.1-[short-name].md
└─ non-functional-requirements/
└─ NFR.01-[short-name].mdNaming conventions
IDs encode the chain itself, so a requirement's name tells you which need and problem it serves.
Problem severity
Not every problem carries the same weight. Each is classified so priority reflects real impact, not the loudest voice in the room.
- Obligation — must solve. Legal, contractual, or operational failure if unmet. Build first.
- Expectation — should solve. Degraded outcomes if unmet. Core value.
- Hope — could solve. A missed improvement if unmet. Build last.
Automation
Keep the specification honest and shippable without manual bookkeeping.
ZigZag validation
Walk the chain in both directions to catch gaps: problems with no need, needs with no requirement, and requirements that trace to nothing. Run it any time the spec changes.
/problem-based-srs validateThe optional complexity pass adds an Axiomatic Design score for independence, completeness, and information content.
Build & release
The methodology plugin ships through a single build script that validates the manifest and every skill, then packages a versioned artifact.
python scripts/build-plugin.py build --version X.Y
gh workflow run create-release.yml --ref main -f version=X.YThe SRS Navigator app releases on its own vX.Y.Z track, gated by npm test. The two pipelines never share a tag.
Hooks & settings
Event handlers live in hooks/hooks.json and default plugin behavior in settings.json, so a team can standardize how the methodology runs across projects.
The SRS Navigator
A GitHub Copilot canvas that renders your .spec/ folder as an interactive graph, then lets you decompose and iterate on it beside the agent.
Open it on a system that already exists
Launch the Navigator without a spec and it offers to read your current system and draft one. No blank page.
- 1 Scan the existing code, README, and documentation
- 2 Run the methodology to draft problems, needs, and requirements
- 3 Load the result as a graph you refine with the agent
Prefer your own file? Load a .spec JSON. Just looking? Explore the demo.
Problem-Based SRS
Load or generate a specification to visualize as an interactive graph.
Learn & Create SpecScan your project, confirm what hurts, generate a spec
Load SpecificationOpen an existing .spec JSON file from your project
Explore DemoLoad the CRM sample specification to explore features
- Force-directed graph
- Problem to requirement tracing
- Agent-driven generation
The graph
See every artifact and its links
The Navigator reads your .spec/ folder and draws each artifact as a node in a force-directed graph. Traceability links are dashed; drag to rearrange, scroll to zoom, and search any node by name.
Every node is color-coded by type:
- CP Customer Problem
- CN Customer Need
- FR Functional Requirement
- NFR Non-Functional Requirement
Action bar
Derive or decompose, inline
Hover any node to reveal a floating action bar. Type an instruction, then pick an action: derive the next artifact downstream, or decompose the node into finer-grained, independently testable sub-items. Each action runs the methodology skill that owns that step.
- Problem +CN+Sub-CP
- Need +FR+Sub-CN
- FR +NFR+Sub-FR
- NFR +Sub-NFR
Refine with the agent
Iterate on the spec in place
Triggering an action opens the node's detail panel (description, a complexity score, and its upstream and downstream traceability) next to a live Agent activity log. Your request runs through the skill, the spec files are edited, and the graph refreshes on its own.
Hover & describeskill runsgraph refreshes
Methodology skills
One command, /problem-based-srs, drives every step. Pass an action to run a single skill, or run it bare for the full walkthrough.
Context
/problem-based-srs business-context
Capture project identity, business principles, stakeholders, and domain boundaries before a single problem is written.
Discover
/problem-based-srs problems
Surface the real Customer Problems behind a request and classify each by severity: obligation, expectation, or hope.
/problem-based-srs software-glance
Sketch the first abstract picture of a solution: components, boundaries, and interfaces, for a shared understanding before details.
/problem-based-srs needs
Translate each problem into the Customer Needs that state what the software must deliver. Every need traces to a problem.
Specify
/problem-based-srs software-vision
Turn the glance and needs into positioning, stakeholders, features, and architecture: the technical roadmap.
/problem-based-srs functional-requirements
Derive detailed, testable Functional and Non-Functional Requirements, each traced backward to a need and a problem.
Validate
/problem-based-srs validate
Walk the CP → CN → FR chain to find orphaned problems, unmet needs, and untraceable requirements.
/problem-based-srs complexity
Optional Axiomatic Design pass: score independence, completeness, and information content of the specification.
Works with AgentSkills-compatible tools: GitHub Copilot, Claude Code, Claude.ai, Gemini CLI, and others.