Problem-Based SRS

Problem-Based SRS is a plugin that extends your AI harness to handle Software Specifications. It plugs into GitHub Copilot first — and Claude Code and other AI coding assistants too — turning a general-purpose coding agent into one that can reason about, trace, and evolve requirements instead of just emitting code.

On top of your harness, the plugin adds three things:

	What it adds
🛡️ AI‑slop prevention	Guardrails tuned to the specific model that stop the agent from inventing features, skipping steps, or drifting off the actual problem.
🧭 A spec language + command palette	A shared vocabulary (Business Context → CP → CN → FR) and a /problem-based-srs command set that steer you toward great design, one decision at a time.
🌱 A method for brownfield and greenfield	A rigorous way to evolve existing systems (learn a spec from the code you inherited) as well as specify new ones from scratch.

It traces every feature back to the customer problem it solves, using the AgentSkills open standard.

Don't take the anti-drift claim on faith — audit it. Every push runs four suites (plugin validation, canvas unit tests, deterministic skill evals, and a Playwright visual suite) and publishes the result to the Skills Health Dashboard. The snapshot is regenerated by pwsh run-tests.ps1 and committed, so the published page always reflects the last full run on main.

The plugin ships two surfaces in one project:

	What it is	Where it runs
🧠 Skills	The Problem-Based SRS methodology as agent-native skills (Business Context → CP → CN → FR, with traceability and validation).	GitHub Copilot first; Claude Code and any AgentSkills-compatible assistant
🗺️ App	The SRS Navigator — a GitHub Copilot canvas app that visualizes your spec as an interactive graph and lets you decompose and iterate requirements with the agent, in place.	The GitHub Copilot side panel (/live)

The problem this solves

A stakeholder says: "We need a CRM — with a mobile app and a dashboard."

Hand that to an AI agent and you get a feature list in seconds. Six months later nobody can say why the dashboard exists, which customer problem it closes, or what breaks if you delete it. The requirements were never written down — only the code was.

This happens because requirements start with what stakeholders ask for instead of what they need. Problem-Based SRS fixes the order: identify the problem first, then derive the solution.

With this methodology, the same request becomes:

CP.01 · Scattered Customer Information Sales teams waste valuable time searching for customer information across multiple disconnected systems.

The need follows from the problem, the requirement from the need. Each identifier names its parent, so the chain reads in both directions — forward to what you build, backward to why:

CP.01 → CN.01.1 Centralized Customer Database → FR.01.1.1 Contact and Company Management

That is not an illustration. It is .spec/crm-system.json, the specification shipped with the plugin: 5 problems, 7 needs, 12 requirements, 5 quality attributes, no orphans. Run /live and the SRS Navigator opens that graph.

How it works

Your AI assistant walks you through six steps. Each builds on the previous:

graph LR
    A[Your input] --> B0[CONTEXT]
    B0 --> B[WHY]
    B --> C[Glance]
    C --> D[WHAT]
    D --> E[Vision]
    E --> F[HOW]
    F --> G[Build]

    style B0 fill:#dda0dd,color:#000
    style B fill:#c44,color:#fff
    style C fill:#3ba,color:#fff
    style D fill:#47a,color:#fff
    style E fill:#6a8,color:#fff
    style F fill:#da6,color:#000

Loading

Step	Command	You answer	You get
0. Business Context	/problem-based-srs business-context	Project identity, constraints, success criteria	Governing principles for all decisions
1. Customer Problems	/problem-based-srs problems	What's broken and for whom	Prioritized problems (Obligation / Expectation / Hope)
2. Software Glance	/problem-based-srs software-glance	High-level solution direction	Shared understanding of scope and boundaries
3. Customer Needs	/problem-based-srs needs	Required outcomes per problem	Measurable success criteria
4. Software Vision	/problem-based-srs software-vision	Architecture and technical approach	Technical roadmap with stakeholder alignment
5. Functional Requirements	/problem-based-srs functional-requirements	Detailed behavior specs	Testable requirements traced to problems

Every requirement traces backward: FR → CN → CP. You can always answer "Why are we building this?"

Use /problem-based-srs validate at any point to verify the chain is complete.

Problem classification

Not all problems are equal. The methodology classifies each by severity:

Class	Verb	Priority	Consequence if unsolved
Obligation	must	High	Legal, contractual, or operational failure
Expectation	expects	Medium	Degraded business outcomes
Hope	hopes	Low	Missed improvement opportunity

This prevents "everything is P1" by grounding priority in the problem's actual impact.

Quick start

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. Skills must go in the agent-specific directory, not a skills/ folder at the repo root.

Run your first session:

/problem-based-srs

Describe your situation. The AI handles the rest:

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

The methodology will produce traced artifacts from business context through functional requirements, stored in your project's .spec/ directory.

Full example

Here is one pass through the methodology for the warehouse scenario above:

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"

WHY (Customer Problems)
  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

WHAT (Customer Needs)
  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

HOW (Functional Requirements)
  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

Every FR traces to a CN, which traces to a CP. The $50k problem is the root. Nothing ships without a reason.

Commands

The methodology is driven by a single command, /problem-based-srs, with an action argument. Run it with no action (or full) for the complete walkthrough.

Command	Purpose
/problem-based-srs	Full methodology, all steps
/problem-based-srs business-context	Step 0: project identity and constraints
/problem-based-srs problems	Step 1: identify and classify problems
/problem-based-srs software-glance	Step 2: sketch solution approach
/problem-based-srs needs	Step 3: define required outcomes
/problem-based-srs software-vision	Step 4: architecture and scope
/problem-based-srs functional-requirements	Step 5: detailed, testable requirements
/problem-based-srs validate	Verify traceability across all artifacts
/problem-based-srs complexity	Optional: Axiomatic Design quality analysis
/live	Launch the SRS Navigator canvas to visualize the spec as an interactive graph

Visualize it live

This repository is both the methodology skill and the UX to navigate it. The SRS Navigator is a GitHub Copilot canvas extension (in .github/extensions/srs-navigator/) that renders a specification as an interactive force-directed graph of Customer Problems, Customer Needs, and Functional/Non-Functional Requirements — explore traceability, filter by analysis mode, search nodes, and inspect dependencies inside the Copilot side panel.

Run /live and your assistant opens the navigator on the current .spec/ (or a built-in CRM demo if you haven't created one yet). The extension also bundles the full methodology as agent tools, so every step is available without leaving the panel.

Prefer a preview first? The project website plays app-faithful animations of the methodology: the traceability chain building itself (Customer Problems first, then the Needs that address them, then the Requirements that satisfy them), a real 28-node spec with its five Customer Problems highlighted, and a Copilot CLI walkthrough calling each skill in order.

Decompose and iterate with the agent

The navigator isn't read-only — it's where you refine the spec together with the agent. Hover any node to reveal an inline action bar. Describe the change you want, then pick an action: derive a downstream artifact (+CN, +FR, +NFR) or decompose the node into finer-grained, independently testable sub-items (+Sub-FR).

Triggering an action opens the node's detail panel on the right. You see the full context — description, complexity, and upstream/downstream traceability — alongside a live Agent Activity conversation. Your request is sent to the matching methodology skill, the agent edits the specification, and the graph refreshes automatically when it's done.

The result: a tight loop where the visual graph, the methodology skills, and the agent all operate on a single, fully-traced specification.

Installation

All installation methods

AI-assisted (recommended)

Ask your AI assistant to install. Specify the target directory:

Agent	Install command
GitHub Copilot	Install the Problem-Based SRS skills from RafaelGorski/Problem-Based-SRS into .github/skills/
Claude Code	Install the Problem-Based SRS skills from RafaelGorski/Problem-Based-SRS into .claude/skills/

Claude Code plugin

Claude Code installs plugins from a marketplace, in two steps — register the catalog, then install the plugin it lists. This repository is its own marketplace (.claude-plugin/marketplace.json), so nothing has to be cloned first:

/plugin marketplace add RafaelGorski/Problem-Based-SRS
/plugin install problem-based-srs@problem-based-srs
/reload-plugins

Plugin skills are namespaced, so the methodology then answers to /problem-based-srs:problem-based-srs. Run /plugin marketplace update problem-based-srs to pick up a new release.

To hack on the plugin instead of installing it, clone it and load the working copy for a single session:

git clone https://github.com/RafaelGorski/Problem-Based-SRS.git
claude --plugin-dir ./Problem-Based-SRS

Plugin release archive

Both commands above need the repository on disk. Every methodology release also attaches problem-based-srs-v<version>.zip — the same plugin with no repository around it, for installing without git. The canvas app ships on its own vX.Y.Z tags interleaved with the methodology's vX.Y ones, so check the title: methodology releases are named 🎉 Version …. Download the asset from the releases page.

The archive already carries its own problem-based-srs/ folder, so extract it into the directory above the one the plugin will occupy:

Scope	Extract into	Produces
Personal (all projects)	~/plugins/	~/plugins/problem-based-srs/.claude-plugin/plugin.json
Project (one repo)	vendor/	vendor/problem-based-srs/.claude-plugin/plugin.json

Then point Claude Code at the extracted folder — claude --plugin-dir ~/plugins/problem-based-srs.

What is inside, and how to use each piece on its own:

Path inside the archive	What it is
problem-based-srs/.claude-plugin/plugin.json	the plugin manifest
problem-based-srs/skills/problem-based-srs/	the methodology skill and its reference/<action>.md files — copy this one folder into .github/skills/ (Copilot) or .claude/skills/ (Claude Code) to use the skill without the plugin wrapper
problem-based-srs/agents/problem-based-srs/	the agent that orchestrates the actions

There is no npm install and no build step: the archive is markdown plus a JSON manifest. It carries the methodology only — the SRS Navigator canvas app is a separate download, below.

AgentSkills CLI

npx skills add RafaelGorski/Problem-Based-SRS

This installs the single skill the repository publishes into .agents/skills/problem-based-srs/ — the shared location AgentSkills-aware agents read, GitHub Copilot included — and records what it took in a skills-lock.json beside it. That is where to look to confirm the install landed; the CLI does not write to .github/skills/.

Browse the published listing at skills.sh/rafaelgorski/problem-based-srs.

SRS Navigator canvas app

The graph UI is a GitHub Copilot canvas extension, installed separately from the skills. Ask the Copilot app to install it directly from this repository:

Install the canvas extension from https://github.com/RafaelGorski/Problem-Based-SRS/tree/main/.github/extensions/srs-navigator

Or install it by hand from a release archive. The canvas app ships on its own vX.Y.Z tags, interleaved with the methodology plugin's vX.Y releases — so the newest release is usually not the one that carries it. Use the filtered release list to find the latest srs-navigator-<version>.zip / .tar.gz.

The archive already contains a srs-navigator/ folder, so extract it into the directory above the one the extension will occupy:

Scope	Extract into	Produces
Personal (all projects)	~/.copilot/extensions/	~/.copilot/extensions/srs-navigator/extension.mjs
Project (this repo only)	.github/extensions/	.github/extensions/srs-navigator/extension.mjs

The extracted folder runs as-is — there is no npm install step. The archive carries no node_modules/ and declares no dependencies; the Copilot app supplies the host SDK.

Then run /live in the Copilot app to open the canvas.

Manual

git clone https://github.com/RafaelGorski/Problem-Based-SRS.git

# Copy to your agent's skills directory:
cp -r Problem-Based-SRS/skills/problem-based-srs <target>/

Agent	Personal directory	Project directory
GitHub Copilot	~/.copilot/skills/	.github/skills/
Claude Code	~/.claude/skills/	.claude/skills/
Gemini CLI	~/.gemini/skills/	—
Cursor	—	.cursor/skills/
Cline	~/.cline/skills/	—
Goose	~/.config/goose/skills/	—

Project-level installation means your whole team uses the same methodology automatically.

Repository structure

Problem-Based-SRS/
├── agents/problem-based-srs/    # Agent orchestrator
├── skills/
│   └── problem-based-srs/       # The single methodology skill
│       ├── SKILL.md             # Orchestrator: /problem-based-srs
│       └── reference/           # One file per action (filename == action)
│           ├── business-context.md        # Step 0
│           ├── problems.md                 # Step 1
│           ├── software-glance.md          # Step 2
│           ├── needs.md                    # Step 3
│           ├── software-vision.md          # Step 4
│           ├── functional-requirements.md  # Step 5
│           ├── validate.md                 # Traceability validation (ZigZag)
│           ├── complexity.md               # Optional: Axiomatic Design
│           ├── live.md                     # Launch the SRS Navigator canvas
│           └── {crm,microer}-example.md    # Case study walkthroughs
├── .github/extensions/
│   └── srs-navigator/           # Canvas extension (UX) + bundled skills
├── .spec/crm-system.json        # Demo specification for the navigator
├── scripts/                     # build-plugin.py, bump-version, package-extension
├── docs/                        # Research paper and methodology
└── .claude-plugin/              # Plugin manifest + marketplace catalog

Case studies: crm-example.md and microer-example.md walk through complete sessions.

Two development workflows

This repository is maintained along two complementary tracks:

1. Agent-native skills (the methodology). The canonical skills live in skills/ as SKILL.md files. Validate and package them with python scripts/build-plugin.py validate / package; CI (.github/workflows/ci.yml) checks every push and the plugin release (.github/workflows/create-release.yml) publishes the AgentSkills/Claude plugin.

2. The SRS Navigator canvas app (the UX). The extension in .github/extensions/srs-navigator/ bundles a flattened copy of the methodology skills and renders the graph. Its own release workflow (.github/workflows/release-canvas.yml) runs the extension test suite, refreshes the bundled skills, bumps the version, and publishes packaged archives.

The two tracks are bridged by skill sync: the canvas app's bundled skills/*.md are generated from the canonical single skill at skills/problem-based-srs/ (its SKILL.md orchestrator plus reference/<action>.md files) in this repo. Run it locally with:

node .github/extensions/srs-navigator/scripts/sync-skills.mjs   # copy from skills/

In this monorepo it copies straight from skills/problem-based-srs/ on disk — the single source of truth. The runtime also reads the canonical SKILL.md / reference/<action>.md directly, so the bundled copies only exist for standalone installs and packaging. Maintainers edit a skill once in skills/problem-based-srs/, and both the agent plugin and the canvas app stay in sync.

Thursday release cadence

The standard release cadence now runs on Thursday. Two GitHub Actions workflows handle it:

1. .github/workflows/thursday-release-report.yml opens or refreshes a weekly report issue at 12:00 BRT with the commits and files waiting for each release train.
2. .github/workflows/thursday-release.yml dispatches releases at 16:00 BRT.

The canvas train auto-releases when commits are waiting. The plugin train only auto-releases when plugin.json and CHANGELOG.md already advertise an unpublished version; otherwise the Thursday run reports the accumulated plugin changes and skips that train until the version is prepared. The report is for review, not gating — the 16:00 BRT dispatch still runs even if no approval arrives in time, and the plugin release workflow itself no longer auto-runs from a tag push outside that cadence.

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.

Uses the AgentSkills open standard and Claude Code Plugins format.

Inspirations

• Impeccable — The clarifying questions pattern: forcing AI agents to stop and ask targeted questions before generating artifacts, rather than making assumptions.
• spec-kit — The project constitution concept: establishing non-negotiable principles and governance before specification work begins. Inspired our Business Context (Step 0) skill.

---

Changelog · Contributing · Report an issue · MIT License