Requirements Risk Analyser

An AI-powered requirements risk analysis pipeline built with TypeScript, Claude API, and MCP.

Finds gaps, ambiguities, and missing acceptance criteria in user stories and PRDs — before a single line of code is written.

Architecture

Three specialised agents run in sequence:

1. Agent 1 — Requirements Analyst: Extracts structured data from raw requirement text — acceptance criteria, user roles, business rules, third-party dependencies, integrations, and data fields
2. Agent 2 — Risk Identifier: Analyses the structured requirement against all business rules and acceptance criteria, identifies genuine gaps across 10 risk categories with HIGH / MEDIUM / LOW severity. Only flags risks that are missing from both AC and business rules combined
3. Agent 3 — Report Generator: Produces a quality score /100, a markdown risk report with a Sources Analysed section, and posts a comment on the Jira ticket if applicable

Input Sources

Three ways to provide requirements:

Method	How	What gets fetched
File	Paste requirement into input/requirement.md	File content only
Jira	Pass --jira TICKET-ID or use the MCP tool	Jira description + linked Confluence pages + linked Jira tickets + attachments
Inline	Pass text as CLI argument	Inline text only

Jira + Confluence integration

When a Jira ticket is provided, the pipeline automatically:

• Fetches the ticket description
• Follows remote links to linked Confluence pages and fetches full page content
• Fetches linked Jira tickets (parent / child / related) — 1 level deep
• Downloads and reads plain text attachments
• Merges all content into one combined requirement before analysis
• Posts the risk report summary as a comment back on the Jira ticket

All sources fetched are listed in the Sources Analysed section of the report.

Risk Categories

Category	What it catches
missing_negative_scenario	No sad path defined
undefined_boundary_value	Ranges implied but not specified
missing_error_handling	Network/DB calls with no failure state
ambiguous_language	should, might, fast, valid, strong
missing_user_role	Which user type does this apply to?
missing_acceptance_criteria	Business rule exists but no testable AC written for it
security_gap	No auth, rate limiting, or input validation
third_party_dependency	Named external service with no fallback defined
integration_assumption	External API assumed always available — no timeout/retry
data_privacy_gap	PII collected with no compliance mention

Sample Output

# Requirements Risk Report

**Requirement:** Password Reset
**Quality Score: 30/100** 🔴

## Risk Summary
| Severity | Count |
|----------|-------|
| 🔴 HIGH   | 4     |
| 🟡 MEDIUM | 2     |
| 🟢 LOW    | 0     |

## Sources Analysed
| Source | Type | Reference |
|--------|------|-----------|
| QRA-1 — User Password Reset | jira ticket | [Link](...) |
| Password Reset — Detailed Requirements | confluence page | [Link](...) |

MCP Tools

• analyse_requirement — full 3-agent pipeline (file or Jira input)
• extract_requirements — Agent 1 only
• identify_risks — Agent 2 only
• get_risk_report — read last generated report

Tech Stack

• TypeScript + Node.js
• Anthropic Claude API (Sonnet 4.6 + Haiku 4.5)
• Ollama (local LLM support — toggle via USE_OLLAMA)
• Model Context Protocol (MCP) SDK
• Jira REST API v3
• Confluence REST API v1

---

Setup

git clone https://github.com/abchahal/requirements-risk-analyser.git
cd requirements-risk-analyser
npm install
cp .env.example .env
# Add your credentials to .env

---

Running the pipeline

Via terminal

# Analyse input/requirement.md
npm run pipeline

# Analyse a Jira ticket (fetches Confluence + linked tickets automatically)
npm run pipeline -- --jira PROJ-123

# Analyse inline text
npm run pipeline "As a user I want to reset my password..."

Via Claude Desktop / Claude Code

Analyse the requirement in input/requirement.md

Analyse Jira ticket QRA-1 for requirement risks

---

Output

output/
├── risk_report.md          ← full risk report with score and sources
└── archive/
    └── 2026-xx-xx/
        └── risk_report.md  ← previous runs archived automatically

Each report includes:

• Quality score /100 with colour indicator
• Executive summary
• Risks grouped by HIGH / MEDIUM / LOW severity
• Suggested acceptance criteria in Given/When/Then format
• Sources Analysed table — every URL fetched during analysis

---

Model Strategy

Agent	Model	Reason
Agent 1	Haiku 4.5	Structured JSON extraction — fast and accurate
Agent 2	Sonnet 4.6	Risk reasoning — requires deeper analysis
Agent 3	Haiku 4.5	Report formatting — structured output

---

MCP Setup via CLI

Step 1 — Update start-mcp.bat with your path

@echo off
cd /d "C:\path\to\requirements-risk-analyser"
node --loader ts-node/esm src/server.ts

Step 2 — Register the MCP server

claude mcp add -s user requirements-risk-analyser "C:\path\to\requirements-risk-analyser\start-mcp.bat"

Step 3 — Verify

claude mcp get requirements-risk-analyser

Expected output:

requirements-risk-analyser:
  Scope: User config (available in all your projects)
  Status: ✔ Connected
  Type: stdio
  Command: C:\path\to\requirements-risk-analyser\start-mcp.bat

Step 4 — Remove the server (if needed)

claude mcp remove requirements-risk-analyser -s user

---

Switching between Ollama and Claude API

Ollama → Claude API

USE_OLLAMA=false
ANTHROPIC_API_KEY=sk-ant-your-key-here

Claude API → Ollama

ollama pull qwen2.5-coder:7b

USE_OLLAMA=true
OLLAMA_MODEL=qwen2.5-coder:7b

Restart the MCP server after changing .env.

Provider comparison

	Ollama (local)	Claude API (cloud)
Cost	Free	Per token
Speed	15–25 minutes	30–60 seconds
Quality	Good	Best
Internet required	No	Yes
Best for	Development and debugging	Production runs and demos

---

Environment Variables

Variable	Required	Description
ANTHROPIC_API_KEY	Yes (if USE_OLLAMA=false)	Anthropic API key from console.anthropic.com
USE_OLLAMA	Yes	true for local Ollama, false for Claude API
OLLAMA_MODEL	No	Default: qwen2.5-coder:7b
JIRA_BASE_URL	No	Your Atlassian instance URL e.g. https://yourcompany.atlassian.net
CONFLUENCE_BASE_URL	No	Same as JIRA_BASE_URL on Atlassian Cloud
JIRA_EMAIL	No	Your Atlassian account email
JIRA_API_TOKEN	No	API token from id.atlassian.com/manage-profile/security/api-tokens

Note: On Atlassian Cloud, JIRA_BASE_URL and CONFLUENCE_BASE_URL are the same URL. The same API token works for both Jira and Confluence.