reqsmart 0.1.0

Requirement qualification tool: extract, score, review, export

smart-req

SMART Requirement Qualification Tool — extract requirements from specification PDFs, score them against quality gates, review with your team, and export gate-clean spreadsheets.

Quick Start

Install

Option A — One-line installer (recommended):

curl -sSL https://raw.githubusercontent.com/aisterna/smart-req/main/install.sh | bash

This checks prerequisites, creates an isolated environment, and adds smart-req to your PATH.

Option B — Manual install:

git clone https://github.com/aisterna/smart-req.git
cd smart-req
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Prerequisites

• Python 3.11 or later (download)
• An Anthropic API key (get one)

Configure

smart-req configure

Enter your Anthropic API key when prompted. Optionally set a default client config:

smart-req configure --client mycompany

This is saved locally at ~/.smart-req/config.yaml.

Usage

Step 1: Create a working directory

mkdir ~/dc28-sfs-review
cd ~/dc28-sfs-review

All output files will be saved here.

Step 2: Extract requirements from your PDF

smart-req extract --input /path/to/your-spec.pdf

Extract specific sections only:

smart-req extract --input /path/to/SFS.pdf --sections 3.5,3.22

Output: raw_extract.csv — open in Excel to sanity-check before scoring.

Step 3: Score against quality gates

smart-req score

Output: manifest.xlsx with four tabs:

• Instructions — what to do next
• PASS — requirements that passed all gates
• REVIEW — requirements with warnings
• FAIL — requirements with failures, including suggested fixes

Step 4: Review (choose one)

Option A — Spreadsheet review:

1. Open manifest.xlsx
2. Go to REVIEW and FAIL tabs
3. Use the dropdown in the Decision column: Accept, Modify, or Reject
4. Add notes in the Engineer Notes column
5. Save the spreadsheet
6. Run:

smart-req finalize

Option B — Browser review:

smart-req review

A local browser UI opens. Click Accept/Modify/Reject for each requirement. When done, the server auto-exports and closes.

Step 5: Done

Your final output:

your-spec_Final.xlsx       ← gate-clean requirements
your-spec_Final.audit.json ← audit trail (who decided what, when)

Commands

Command	What it does
smart-req run	Full pipeline — extract, score, review, export in one command
smart-req extract	PDF → requirements CSV
smart-req score	CSV → scored manifest (XLSX + JSON)
smart-req review	Browser-based HITL review
smart-req finalize	Import spreadsheet decisions → export final XLSX
smart-req export	Export final XLSX (after browser review)
smart-req import-decisions	Import decisions from spreadsheet only (advanced)
smart-req configure	Set API key and default client

Quickest path

# Browser review (one command does everything)
smart-req run --input /path/to/spec.pdf

# Spreadsheet review (two commands)
smart-req run --input /path/to/spec.pdf --spreadsheet
# fill in decisions in manifest.xlsx, save, then:
smart-req finalize

Quality Gates

Default (IEEE 29148 Baseline — 6 gates)

Six universal gates derived from IEEE/ISO/IEC 29148:2018 Clause 5.2.5:

Gate	IEEE 29148 Characteristic	What it checks
RQ1 Unambiguous	§5.2.5(c)	Single interpretation. No vague terms.
RQ2 Verifiable	§5.2.5(l)	Can be proven by test, analysis, or inspection.
RQ3 Singular	§5.2.5(i)	One concern per requirement.
RQ4 Appropriate	§5.2.5(a)	Right abstraction level. WHAT, not HOW.
RQ5 Traceable	§5.2.5(k)	Maps to source AND to implementation + verification.
RQ6 Complete	§5.2.5(b)	All values specified. No TBDs.

Domain Templates

Pre-built gate configurations for regulated industries. Copy a template and customize:

Template	Standards	Additional gates
telecom.md	TL9000, ITU-T, RFC 2119	Protocol compliance, keyword compliance, interface completeness, interop reference
aerospace-do178c.md	DO-178C, ARP 4754A	DAL allocation, derived req flagging, safety traceability, verification method
medical-iec62304.md	IEC 62304, ISO 14971, FDA	Safety class, hazard traceability, intended use, SOUP identification
automotive-iso26262.md	ISO 26262, ASPICE	ASIL allocation, freedom from interference, fault handling, bidirectional trace

cp config/templates/telecom.md ~/.smart-req/clients/mycompany/gates.md
smart-req configure --client mycompany

Further customization

After applying a template, you can add domain terms to suppress false positives on your terminology:

# Create domain_terms.md in your client config
cat > ~/.smart-req/clients/mycompany/domain_terms.md << 'EOF'
## Domain-Specific Terms
- [your acronyms and defined terms here]
- [terms that sound vague but have precise meaning in your domain]
EOF

For gates fully tailored to your methodology and document conventions, contact [e-mail].

Example

# Full pipeline on a 100-page SFS document
mkdir ~/dc28-review && cd ~/dc28-review

smart-req extract --input ~/Documents/my-spec.pdf
# → 480 requirements extracted (45s)

smart-req score
# → 347 PASS, 98 REVIEW, 35 FAIL (12 min)

smart-req review
# → Browser opens, review 133 items, auto-exports when done

ls *_Final.*
# your-spec_Final.xlsx
# your-spec_Final.audit.json

First Run: What to Expect

When you run smart-req for the first time without a custom client config, here's what happens:

The good

• Requirements with real quality issues (vague, untestable, compound, incomplete) are correctly flagged
• Suggested fixes are actionable — you can Accept them directly
• The 5 default quality gates catch universal problems that apply to any domain

The noise

• Domain terms flagged as ambiguous (~15-30% of warnings): Terms like "traffic-affecting fault" or "NETCONF" have precise meaning in your domain, but the default scorer doesn't know that. These show up as G1/Specific warnings.
• Missing domain-specific checks: The default 5 gates cover universal requirement quality. Your domain may need additional gates (interface completeness, protocol compliance, safety traceability).

What to do about it

1. Just Reject the false positives (5 minutes): The dropdown makes this fast. Your rejections are recorded in the audit trail — they don't slow you down.

2. Apply a domain template (10 minutes): Pick the template for your industry. This adds domain-specific gates and reduces noise immediately:

mkdir -p ~/.smart-req/clients/mycompany
cp config/templates/telecom.md ~/.smart-req/clients/mycompany/gates.md
smart-req configure --client mycompany
smart-req score    # now uses your domain gates

Available templates: telecom.md, aerospace-do178c.md, medical-iec62304.md, automotive-iso26262.md.

3. Add your domain terms (1 hour): Create a terms list so your team's vocabulary stops triggering false warnings:

cat > ~/.smart-req/clients/mycompany/domain_terms.md << 'EOF'
## Domain-Specific Terms
- [your acronyms and defined terms here]
- [terms that sound vague but have precise meaning in your domain]
EOF

Re-score — false positives drop to <5%.

4. Professional onboarding (2-3 hours): Gates fully tailored to your methodology, document conventions, and quality standards. Contact [e-mail].

Example: Reducing noise step by step

Suppose your spec contains this requirement:

"The system shall support NETCONF for NBI configuration management."

Step 0 — Default scoring result:

RQ1 Unambiguous: FAIL — "support" is a prohibited vague term (support what exactly?)
RQ2 Verifiable:  FAIL — no testable criteria (which NETCONF operations? which datastore?)
RQ6 Complete:    FAIL — no protocol version, no transport, no error handling
Suggested fix: "The system shall implement NETCONF (RFC 6241) over SSH (RFC 6242)
for NBI configuration management, supporting <get>, <get-config>, <edit-config>,
and <lock> operations on the running and candidate datastores."

Three failures. The suggested fix is good but aggressive — maybe you only need some of those operations.

After Step 1 (Reject): You click Reject on RQ1: "support has defined meaning in our NBI spec — it means implement all mandatory operations per our NBI compliance matrix." Audit trail records your justification. RQ2 and RQ6 failures are legitimate — you Accept those fixes.

After Step 2 (Telecom template): You applied telecom.md. Now the scoring also checks TQ1 (Protocol Compliance) and TQ3 (Interface Completeness):

TQ1 Protocol Compliance: FAIL — no NETCONF version (RFC 6241 vs RFC 4741?)
TQ3 Interface Completeness: FAIL — no operations, no datastore, no error handling specified

The template catches what the baseline missed — and the failures are more precise.

After Step 3 (Domain terms): You added to domain_terms.md:

- NBI (Northbound Interface — management plane access)
- NETCONF, RESTCONF, SNMP (management protocols)
- "support" when followed by a protocol name (means implement per compliance matrix)

Now RQ1 no longer flags "support NETCONF" as vague. Only the real gaps (RQ2, RQ6, TQ1, TQ3) remain.

After Step 4 (Professional onboarding): iSterna adds a custom gate:

### CQ1: NBI Compliance Matrix Reference
- Pass: NBI requirement references the compliance matrix row/column
        specifying mandatory vs optional operations for this protocol.
- Fail: NBI requirement without compliance matrix reference.

Now every NBI requirement is automatically checked against your compliance matrix — something no generic template could know about.

Typical results by configuration

Configuration	False positive rate	Gates	Setup time
Default (no config)	15-30%	6 RQ baseline	0 min
Domain template	10-15%	6 RQ + 4 domain	10 min
Template + domain terms	3-5%	6 RQ + 4 domain	1 hour
Professional onboarding	<3%	Custom (8-12 gates)	2-3 hours with specialist

---

FAQ

How much does it cost? LLM costs depend on document size. A 100-page SFS (~480 requirements) costs approximately $15-25 for extraction + scoring using Claude Sonnet.

Can I use a different LLM? Currently Claude only. Pass --model claude-opus-4-6 for higher quality at higher cost, or --model claude-sonnet-4-20250514 (default) for the best cost/quality balance.

Does my data leave my machine? Requirement text is sent to the Anthropic API for extraction and scoring. No data is stored by the tool beyond your local machine. Review and export are fully offline.

Can I re-score after editing the CSV? Yes. Edit raw_extract.csv, then run smart-req score again. The manifest is regenerated from scratch.

What if I disagree with a gate score? Reject it. The Decision column lets you override any gate result with a justification. Rejected items keep their original text and your reason is recorded in the audit trail.

License

Business Source License 1.1 (BSL-1.1). See LICENSE for details.