# 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

```markdown
# 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

```bash
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

```bash
# 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

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

### Step 2 — Register the MCP server

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

### Step 3 — Verify

```bash
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)

```bash
claude mcp remove requirements-risk-analyser -s user
```

---

## Switching between Ollama and Claude API

### Ollama → Claude API

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

### Claude API → Ollama

```bash
ollama pull qwen2.5-coder:7b
```

```env
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.