---
_version: '1'
uuid: 791b2934-600f-4882-8a8f-4126df4c5a6d
created: 2025-10-27T20:46:06.371462981Z
parents:
- uuid: 96bcbcca-a8e4-450f-bdaa-0f23c93e1a36
fingerprint: 34e04ddb515030e490922d8d7a64a04cb5495954bc44d460310ce6c37a5ecd46
hrid: SYS-008
- uuid: f86dfe3c-ceb9-4e28-bbb4-66588076f2b2
fingerprint: 2c908e949aafeefdeee65f572508e0ac429aa6fafc956c36bcc9c479b03779f8
hrid: SYS-009
- uuid: d1b46364-2297-409c-9bbe-8b0134cf86e6
fingerprint: 45352c3d0c3192db4c7514b1182eea4220ad39661603c0983a9c7dc250d8a28e
hrid: SYS-010
---
# SPC-005 Enhanced Suspect Command Ergonomics
## Purpose
Extend the `req suspect` command with context-rich output, filtering capabilities, and interactive workflows that help engineers efficiently triage, understand, and resolve suspect links across repositories of any size.
## Experience Principles
- **Context over cryptography:** Surface requirement titles, paths, and modification context instead of expecting users to decode fingerprint hashes.
- **Triage efficiency:** Provide filtering, grouping, and statistics so engineers can prioritise reviews by impact (most affected parents, specific requirement types, etc.).
- **Scriptable depth:** Balance human-readable defaults with machine-parseable formats that integrate into CI pipelines and review tracking systems.
- **Progressive complexity:** Keep the default path simple; reveal advanced features through discoverable flags rather than overwhelming the initial experience.
## Enhanced Default Output
Current baseline from SPC-001 remains the foundation. This specification extends it with contextual enrichment:
```
Suspect Links Found: 3
CHILD PARENT TITLE (CHILD → PARENT)
─────────────────────────────────────────────────────────────────
TST-002 → USR-001 Test case for login → User authentication
SYS-005 → USR-001 System integration → User authentication
TST-003 → SYS-005 Integration test → System integration
Run 'req suspect --detail' for paths and fingerprints
Run 'req accept --all --apply' to accept all changes
```
**Changes from baseline:**
- Add title columns showing `CHILD_TITLE → PARENT_TITLE` for semantic context
- Include helpful footer with next-step commands
- Maintain clean column alignment with proper padding
- Show count in header (`Found: N`)
## Extended Detail Mode
Enhance `--detail` output with file paths, timestamps, and actionable commands:
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Suspect Link #1 of 3
CHILD: TST-002 Test case for login functionality
Path: ./tests/TST-002.md
PARENT: USR-001 User authentication requirements
Path: ./requirements/USR-001.md
REASON: Parent content changed (fingerprint drift)
STORED: 2520e9b3a2ce93d942f5288ffebec2fbdbf877367edd9968a0ae930b343dbac7
CURRENT: 2836f44e05c344dff2764275e0645829c2ef88c073f0d0062bc625f515d2d577
ACTIONS:
req accept TST-002 USR-001 --apply
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```
**Additions:**
- Requirement titles in full
- File paths for both child and parent
- Numbered suspects (`#1 of 3`) for orientation
- Concrete action commands
- Clear section separators using box-drawing characters
## Filtering Capabilities
### By Requirement Identifiers
- `--child <HRID>` filters to suspects where the given requirement is the child
- `--parent <HRID>` filters to suspects where the given requirement is the parent
- `--kind <KIND>` filters by child requirement kind
**Example:**
```bash
req suspect --parent USR-001
# Shows only suspects where USR-001 is the parent
req suspect --kind TST
# Shows only test requirements with suspect parent links
```
### Output Grouping
- `--group-by <FIELD>` organises output hierarchically
- Supported fields: `parent`, `child`, `none` (default)
**Example with `--group-by parent`:**
```
Suspect Links by Parent (2 parents, 5 links total)
USR-001 (User authentication requirements)
├─ TST-002 Test case for login
├─ TST-003 Test case for logout
└─ SYS-005 System component integration
SYS-005 (System integration)
├─ TST-010 Integration test alpha
└─ TST-011 Integration test beta
```
Tree formatting uses UTF-8 box characters with ASCII fallback (`--ascii` or when terminal lacks support).
## Summary Statistics
- `--stats` displays aggregate information before the table
- Helps teams understand review scope and prioritise high-impact parents
**Example:**
```
Suspect Link Statistics
Total suspect links: 12
Unique parents affected: 5
Unique children affected: 12
By child requirement kind:
TST → * 7 links
SYS → * 3 links
USR → * 2 links
Most affected parents:
USR-001 (5 children)
SYS-003 (3 children)
SYS-005 (2 children)
```
When combined with `--format json`, include a `summary` object at the root level mirroring this data.
## Quiet Mode for Scripting
- `--quiet` outputs minimal, parseable data: one line per suspect, space-separated HRIDs
- No colours, no headers, no footers
- Exit codes remain unchanged (0 when clean, 2 when suspects exist)
**Example:**
```bash
req suspect --quiet
TST-002 USR-001
SYS-005 USR-001
TST-003 SYS-005
```
Enables shell pipelines:
```bash
done
```
## Enhanced JSON Output
Extend JSON format to include titles, paths, and summary statistics:
```json
{
"timestamp": "2025-10-27T20:45:00Z",
"summary": {
"total_count": 3,
"unique_parents": 2,
"unique_children": 3,
"by_kind": {
"TST": 2,
"SYS": 1
}
},
"links": [
{
"child": {
"hrid": "TST-002",
"title": "Test case for login",
"path": "./tests/TST-002.md",
"kind": "TST"
},
"parent": {
"hrid": "USR-001",
"title": "User authentication",
"path": "./requirements/USR-001.md",
"kind": "USR"
},
"status": "fingerprint drift",
"stored_fingerprint": "2520e9b3a2ce...",
"current_fingerprint": "2836f44e05c3..."
}
]
}
```
## Accessibility & Performance
- Maintain colour detection and `NO_COLOR` compliance from SPC-001
- For repositories >500 requirements, show a progress indicator during graph load: `Analysing suspect links…` with spinner (⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏) or ASCII fallback (`...`)
- Spinner disappears before output begins; never mix spinner and table on the same line
- Keep default (no filters) execution under 500ms for repositories <1k requirements
## Messaging & Error Handling
- Unknown filter values exit `64` with message: `Unknown requirement: <HRID>. Check 'req list' for available identifiers.`
- Invalid `--group-by` values exit `64` with message: `Invalid group field '<value>'. Use: parent, child, or none.`
- Empty filter results print: `No suspect links matched the specified filters.` and exit `0`
- Maintain existing empty-state messaging from SPC-001 when no suspects exist at all
## Interaction with Other Commands
- `req status` surfaces suspect counts; `req suspect` provides the investigation layer
- `req accept` consumes the HRIDs displayed by `req suspect`, enabling a natural workflow progression
- JSON output format should be consumable by external tracking systems and CI reporting tools