StressSpec

Screenshots

Overview

StressSpec is a full-stack platform for detecting risk in software requirements documents before a single line of implementation code is written. It scans requirements for structural ambiguity, scope gaps, testability failures, and compliance risks, then produces prioritized analysis reports for stakeholders.

The project ships as both a FastAPI web application (file upload, interactive views, downloadable HTML/CSV/JSON reports) and a standalone CLI — both powered by the same analysis pipeline, making it usable in automated workflows as well as manual review sessions.

Problem

Requirements defects are disproportionately expensive when discovered late. A vague or incomplete requirement that slips into implementation creates rework, misaligned features, and untestable code. Most teams lack a structured way to audit requirements quality before development begins — they rely on ad hoc review or discover problems during testing.

I wanted to build a tool that makes requirements risk visible and prioritized, giving teams a concrete starting point for requirements review rather than open-ended discussion.

Approach

The core of StressSpec is a modular rule-based detection engine. Each rule targets a specific risk category — vague language, missing acceptance criteria, implicit dependencies, untestable assertions — and produces a severity-weighted finding. Rules are isolated and extensible, so adding a new risk category requires no changes to the pipeline core.

On top of the engine, I built two interfaces that share identical analysis logic:

• FastAPI web app: accepts file uploads, runs the pipeline, and renders interactive results with an executive summary highlighting the Top 5 riskiest requirements.
• CLI: accepts file paths, writes analysis to stdout or file, and integrates cleanly into shell scripts or CI pipelines.

Reports are available in HTML (rendered Jinja2 template), CSV (flat export for stakeholder review), and JSON (machine-readable for downstream tooling).

Tech Stack

Key Decisions & Tradeoffs

Rule-based vs. ML-based detection. I chose rule-based detection over a machine learning approach intentionally. ML models produce probabilistic findings that are difficult to explain to a stakeholder; rule-based findings come with a clear, auditable rationale. For a tool whose purpose is to build confidence in requirements quality, explainability matters more than recall.

Unified pipeline for both interfaces. I invested time in keeping the CLI and web app as thin wrappers over the same pipeline module rather than duplicating analysis logic per interface. The tradeoff was a slightly more constrained API design (the pipeline must produce a serializable result), but the benefit — single source of truth for all analysis behavior — made testing and iteration far simpler.

Severity scoring vs. binary pass/fail. Rather than flagging requirements as simply "good" or "bad," the system assigns weighted severity scores and ranks findings. This reflects real-world triage: not all risks are equally urgent, and giving stakeholders a prioritized list (Top 5 riskiest requirements) is more actionable than an undifferentiated list.

What I Learned

• Designing a rule engine that is both extensible and consistent requires thinking carefully about the interface between rules and the pipeline before writing the first rule. Retrofitting extensibility is expensive.
• Dual interfaces (CLI + web) are a powerful feature, but only if the shared core is designed for it from the start. Shared logic built as an afterthought tends to carry interface-specific assumptions.
• Writing tests for a text analysis tool surfaced edge cases in my rules faster than manual testing ever would have. The pytest suite became my primary feedback loop during rule development.