--- name: traceable-reqs description: "Install or update the traceable-reqs CLI plus its bundled req-confusion-audit skill, and apply the CLI correctly in host repos: author manifests, place tags near evidence, audit scan roots, interpret findings, and answer coverage questions." 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. - `misplaced_tag`: the tag is not attached to an item that can carry its stage — it sits in a file's comment header, in dead space, or on something ineligible (a `unit`/`int` tag on a bare value declaration, a code-stage tag in Markdown). The message names what the tag landed on. Fix by moving the tag onto, or directly above, the evidence it claims (only blank/comment/attribute lines in between). For deliberate module-banner tags set `[placement].module_banner = "accept"`; to disable the rule entirely set `[placement].enforce = "off"`. 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 Install the latest `traceable-reqs` binary from a GitHub Release into a per-user location, install the bundled `req-confusion-audit` skill as a top-level Claude skill, and install the workflow that skill dispatches. Verify all three, then print PATH advice. Do 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. The skill and the workflow are a pair: `req-confusion-audit` invokes `req-confusion-score` by name, so installing the skill without the workflow leaves it dispatching to something that is not there. ## Defaults - Repo: `BigscreenVR/traceable-reqs` - Version: latest release tag - Install dir: `~/.local/bin` on Linux/macOS, `%LOCALAPPDATA%\Programs\traceable-reqs` on Windows - Bundled skill target: `~/.claude/skills/req-confusion-audit` - Bundled workflow target: `~/.claude/workflows/req-confusion-score.js` 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. **Install the bundled skill.** Resolve `` as the directory containing this `SKILL.md`. The source is `/.claude/skills/req-confusion-audit`; the target is `~/.claude/skills/req-confusion-audit`. If the source is missing, stop and report a corrupt or incomplete clone. If the target already exists and its `SKILL.md` does not declare `name: req-confusion-audit`, stop rather than overwrite another skill. Otherwise create the target and copy the source contents over it: - Bash: ```bash source_dir="/.claude/skills/req-confusion-audit" target_dir="$HOME/.claude/skills/req-confusion-audit" mkdir -p "$target_dir" cp -R "$source_dir"/. "$target_dir"/ ``` - PowerShell: ```powershell $sourceDir = Join-Path "" ".claude\skills\req-confusion-audit" $targetDir = Join-Path $HOME ".claude\skills\req-confusion-audit" New-Item -ItemType Directory -Force -Path $targetDir | Out-Null Get-ChildItem -Force -LiteralPath $sourceDir | Copy-Item -Destination $targetDir -Recurse -Force ``` Verify `/SKILL.md` exists and declares `name: req-confusion-audit`. 6. **Install the bundled workflow.** The skill dispatches its scoring phase to a workflow named `req-confusion-score`, which Claude resolves from `~/.claude/workflows`. Source is `/.claude/workflows/req-confusion-score.js`; target is `~/.claude/workflows/req-confusion-score.js`. If the source is missing, stop and report a corrupt or incomplete clone. If the target already exists and does not declare `name: 'req-confusion-score'` in its `meta` block, stop rather than overwrite another workflow. Otherwise create the directory and copy: - Bash: ```bash source_file="/.claude/workflows/req-confusion-score.js" target_dir="$HOME/.claude/workflows" mkdir -p "$target_dir" cp "$source_file" "$target_dir/req-confusion-score.js" ``` - PowerShell: ```powershell $sourceFile = Join-Path "" ".claude\workflows\req-confusion-score.js" $targetDir = Join-Path $HOME ".claude\workflows" New-Item -ItemType Directory -Force -Path $targetDir | Out-Null Copy-Item -LiteralPath $sourceFile -Destination (Join-Path $targetDir "req-confusion-score.js") -Force ``` Verify the target exists and contains `name: 'req-confusion-score'`. 7. **Make executable** (Unix only): `chmod +x /traceable-reqs`. 8. **Verify the CLI.** Run `/ --version`. If it errors, stop and report. 9. **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 `. - Bundled skill source missing → report an incomplete clone; do not create an empty target. - Bundled skill target belongs to another skill → stop; do not overwrite it. - Bundled workflow source missing → report an incomplete clone. Do not install the skill alone and call it done: the audit's scoring phase dispatches to this workflow by name, and without it the skill fails at the point where it fans out. - Bundled workflow target belongs to another workflow → stop; do not overwrite it.