--- name: traceable-reqs description: "Install or update the traceable-reqs CLI and apply it correctly in host repos: author manifests, place tags near evidence, audit scan roots, interpret findings, and answer coverage questions through the CLI." allowed-tools: Bash, PowerShell, Read --- # traceable-reqs Use this skill for both installation and day-to-day use of `traceable-reqs`. The CLI reads a required `traceable-reqs.toml`, scans configured roots for `[stage->REQ-ID]` tags, and reports whether manifest-declared requirements have the required evidence stages. ## Applying traceable-reqs to a repo Start with the manifest, then place tags close to the evidence they prove. Do not satisfy coverage by putting tags at the top of a file; that is noisy and usually wrong. A tag belongs on or immediately above the function, test, config entry, doc section, or workflow step that actually satisfies that stage. Minimum manifest: ```toml [scan] roots = ["src", "tests", "docs"] [policy] required_stages = ["doc", "impl", "unit"] [[requirements]] id = "REQ-LOGIN" title = "User can sign in" required_stages = ["doc", "impl", "unit", "int"] ``` Audit `[scan].roots` against the real project tree before trusting coverage. If implementation lives in `.github/workflows`, `scripts`, `cmake`, or another directory, include it or the evidence will silently disappear from the trace. Requirement IDs must match `REQ-[A-Z0-9-]+`, with hyphen-separated uppercase segments. Prefer title-derived slugs such as `REQ-LOGIN-LOCKOUT` over bare numeric counters. IDs like `FR-001`, `NFR-002`, or `CON-010` are not valid unless they are written as `REQ-FR-001`, `REQ-NFR-002`, or `REQ-CON-010`. ## Stages Built-in stages are exactly: - `doc`: prose or design documentation. - `impl`: production implementation. - `unit`: unit tests. - `int`: integration, end-to-end, workflow, or system-level tests. Domain words such as HIL, e2e, smoke, QC, or security are not built-in stages. Map them to the closest built-in stage, usually `int`, or declare a custom stage in the manifest before using it: ```toml [stages.qc] description = "QC engineer signoff" ``` A tag with an undeclared stage, such as `[hil->REQ-CAMERA]`, is a `parse_error`. ## Tag examples ```rust // [impl->REQ-LOGIN] fn authenticate(...) { ... } ``` ```python # [unit->REQ-LOGIN] def test_login_accepts_valid_password(): ... ``` ```markdown # Login ``` Any bracketed text that looks like a tag candidate must be exact. A placeholder like `[stage->REQ-ID]` in scanned Markdown can become a `parse_error`; escape it, remove the arrow, or keep examples outside scanned roots when needed. ## Command choice Use the CLI for coverage questions, not grep. Grep does not know scan roots, comment-only rules, custom stages, docstrings, or parse errors. - `traceable-reqs check --json`: full coverage and findings for CI or audit. - `traceable-reqs list --json`: all requirements without treating findings as a failing command. - `traceable-reqs list --missing impl`: requirements missing a required stage. - `traceable-reqs list --type FR`: requirements of one declared type. - `traceable-reqs trace REQ-LOGIN`: evidence and findings for one requirement. - `traceable-reqs review`: agent-facing prompt to inspect tag placement quality. - `traceable-reqs lint`: agent-facing prompt plus deterministic title-quality findings. `check` returning exit code 1 means findings were produced; it is not a pipe or runtime failure by itself. Read stdout or use `--json` to inspect the findings. Operational failures such as bad arguments, invalid manifests, or unreadable files report diagnostics on stderr. ## Common findings - `missing_stage`: the requirement is declared but lacks evidence for a required stage. First check tag placement and scan roots. - `undeclared_id`: a tag references an ID not in `traceable-reqs.toml`. First check for typos and invalid ID prefixes. - `parse_error`: a tag-shaped token is malformed, uses an undeclared stage, has spaces, or has an invalid requirement ID. - `manifest_error`: the manifest is missing, invalid TOML, invalid UTF-8, has duplicate IDs, bad stages, bad types, or invalid scan roots. - `scan_error`: a scanned file could not be read. On Windows, avoid writing the manifest with a UTF-16 redirect. Use an editor, the Write tool, or `Out-File -Encoding utf8NoBOM` so TOML parsing sees UTF-8. For placeholder requirements that intentionally have no evidence yet, set `required_stages = []` so `check` does not report missing coverage until the requirement is ready. ## Installation Installs the latest `traceable-reqs` binary from a GitHub Release into a per-user location, verifies it runs, and prints PATH advice. Does not mutate the user's shell rc files or environment automatically — PATH changes are user intent, so surface the line and let them act on it. ## Defaults - Repo: `BigscreenVR/traceable-reqs` - Version: latest release tag - Install dir: `~/.local/bin` on Linux/macOS, `%LOCALAPPDATA%\Programs\traceable-reqs` on Windows Override per-call via env vars: `TRACEABLE_REQS_REPO`, `TRACEABLE_REQS_VERSION`, `TRACEABLE_REQS_INSTALL_DIR`. ## Procedure 1. **Verify `gh`.** Run `gh auth status`. If `gh` is missing or returns non-zero, stop and tell the user to install it from https://cli.github.com/ then run `gh auth login`. `gh auth login` is interactive — do not attempt to run it for them. 2. **Detect platform and target.** - macOS / Linux: use Bash. Read `uname -s` and `uname -m`, then map: - `Linux` + `x86_64` → target `linux-x86_64` - `Darwin` + `arm64` → target `macos-arm64` - Native Windows: use PowerShell. Target is `windows-x86_64.exe`. - Anything else (Linux arm64, Intel Mac, MINGW/Cygwin) is not in the release matrix. Stop and tell the user to build from source: `cargo install --git `. 3. **Resolve version.** If `TRACEABLE_REQS_VERSION` is set, use it. Otherwise `gh release view --repo --json tagName -q .tagName`. 4. **Download.** Asset name is `traceable-reqs--`. Make the install dir if needed, then: ``` gh release download --repo --pattern --output / --clobber ``` Binary name is `traceable-reqs` on Unix, `traceable-reqs.exe` on Windows. 5. **Make executable** (Unix only): `chmod +x /traceable-reqs`. 6. **Verify.** Run `/ --version`. If it errors, stop and report. 7. **PATH advice.** Check if the install dir is on `PATH`. If yes, done. If no, print these for the user to copy — do not execute them: - Bash / zsh: `export PATH=":$PATH"` (and add to `~/.bashrc` or `~/.zshrc` for persistence). - PowerShell, current session: `$env:PATH = ";" + $env:PATH` - PowerShell, persistent (open a new shell to take effect): `[Environment]::SetEnvironmentVariable('PATH', ';' + [Environment]::GetEnvironmentVariable('PATH','User'), 'User')` ## Failure modes - `gh` missing → install link, stop. - `gh` not authenticated → `gh auth login`, stop (interactive — user does it). - Unsupported target → "no prebuilt for ``; build from source with `cargo install --git`". - Asset not found → likely the release matrix did not finish; have the user check `gh release view --repo `.