---
_version: '1'
uuid: aab4dd35-5791-4efe-a72b-cbe320505e81
created: 2025-10-27T12:05:00Z
parents:
- uuid: 45541828-5887-4ba8-9679-d353908dfa85
fingerprint: b85ab44d075307ffabe4a6bd3baa215791dbe221faaf8399069dbdb31d03ae02
hrid: SYS-019
- uuid: 0a71da3b-3684-4d58-ba36-9b74fb2cec85
fingerprint: b59851f24948a974edb878632f18fc457a679dac87e2671d77259b43c4008246
hrid: SYS-018
- uuid: 0ac3ee79-3ee1-4f4b-ac07-7523f99f5383
fingerprint: c5ebe20e40dc26cad316e5ff6290ab9efde02a60484d9a61741e4e19c22dd4b3
hrid: SYS-017
---
# SPC-002 Requirement Listing CLI Experience
## Purpose
Deliver a single `req list` interaction pattern that supports three modes of working:
1. **Glanceable** overviews for quick status checks.
2. **Investigative** filtering for targeted questions.
3. **Exploratory** graph navigation that exposes context without overwhelming the screen.
## Experience Principles
- **Recognisable rhythm:** Every view begins with a headline (scope, filters, view mode), followed by a tidy table so users load the pattern into muscle memory.
- **Shape the noise:** Present the most important metadata first. Align columns, keep titles on-screen, and elide long paths with ellipses at the middle (`…/docs/src/requirements/SYS-017.md`).
- **Reveal on demand:** Advanced controls exist but stay out of the way; optional flags appear in help copy only when requested.
- **Composable:** Filters, views, and outputs layer without surprise—users can mix them freely and the resulting narrative still makes sense.
## Default Output
- Header line: `Listing requirements (view: summary, filters: none, limit: 200)`
- Columns (left-aligned, padded with two spaces between): `HRID`, `Kind`, `Parents`, `Children`, `Title`.
- When the dataset is truncated by the default limit, display `… +42 more (use --limit or --offset)` as a footer.
- No blank line between rows; use light grey row separators (`────────`) only when `--view tree` is active.
## Filters
- `--kind`, `--namespace`, `--tag`, `--contains`, and `--regex` appear in the header line so users can see active constraints without scrolling.
- When multiple filters of the same type are applied, join values with comma and space (`kind: SYS, TST`).
- Free-text filters highlight matches inside the `Title` column using faint underline (fallback: enclose with `<<` and `>>`).
- Empty results return a friendly message: `No requirements matched the filters provided.` plus the header.
## Relationship Views
- `--view parents|children|ancestors|descendants` switches to a block layout:
```
USR-004 Graph Analysis and Validation
↑ SYS-003 Parent Requirement Links
↑ SYS-005 Suspect Link Detection
```
- Tree view renders with UTF-8 guides when the terminal supports them:
```
USR-004 Graph Analysis and Validation
├─ SYS-003 Parent Requirement Links
│ └─ TST-001 Test Coverage
└─ SYS-005 Suspect Link Detection
```
Fallback uses ASCII (`|-` and ``\``) when `--ascii` is passed or terminal lacks box-drawing characters.
- Depth indicators appear in the header (`depth: 2`) and are enforced consistently across view types.
## Output Formats
- `--output json` returns an array of objects that mirrors the current view. Each object includes `hrid`, `title`, `kind`, `parents`, `children`, `tags`, `path`, and `view`-specific fields.
- `--output csv` follows RFC 4180: headers on the first row, quoted values when they contain commas.
- `--quiet` suppresses the header/footer and prints only the primary identifier relevant to the view: HRIDs in summary view, child HRIDs in `--view children`, etc.
## Help & Discoverability
- `req list --help` organises flags by intent: **Scope**, **Filters**, **Views**, **Output**, **Quality of life**.
- Short usage examples illustrate common combinations (two lines max each).
- When a user passes an unknown flag, respond with `Unrecognised option '--foo'. Run 'req list --help' for usage.` and exit `64`.
## Performance Considerations
- For large repositories (>5k requirements), show a progress spinner while the graph loads (frames: `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏`). Fallback to `...` animation on ASCII-only terminals.
- Spinner stops before the table header appears; do not mix the two outputs on one line.
## Accessibility & Internationalisation
- Respect terminal width: wrap titles gracefully and indent continuation lines so the HRID column stays readable.
- Use plain language and avoid abbreviations that rely on cultural context.
- Ensure table headers stay in English for now, but confirm they render with UTF-8 characters without misalignment.