sjames / sjames/syscribe

feat(show): surface related traceability commands (trace/impact/who-verifies/refs) in show output

Open
#117 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Rust
Stars
7
Forks
1
Avg merge
21m
Merged PRs (30d)
2

Description

Summary

show <qname|id> prints an element's own fields and documentation, but nothing pointing at the traceability commands (trace, impact, who-verifies, refs) that already exist and answer the natural next questions about that same element. Add a short "Related" footer to show's output suggesting the applicable follow-up commands for the element's type, pre-filled with its id.

Motivation

trace, impact, who-verifies, refs, and connectivity already do real traceability-graph work — exactly the kind of thing that's expensive to reconstruct by hand (I found myself running grep -rl "REQ-MQTT-009" specification/ and manually cross-referencing PlanningItem/Requirement/TestCase files during a verification pass, when syscribe trace REQ-WEB-011 would have produced the same answer in one call). The commands aren't missing — they're just not surfaced at the moment they'd help, which is right after looking at the element itself via show. --agent-instructions documents them well up front, but that's a one-time read at the start of a session; there's nothing in the steady-state, per-command output that re-surfaces them mid-task.

For an LLM agent in particular, this matters more than it would for a human: a human skimming show's output has the CLI's --help a keystroke away and may already remember the command exists; an agent re-derives its next action from whatever's in front of it in that turn, and is much likelier to default back to grep/Read if the tool itself doesn't mention the shortcut.

Proposed shape

Append a short, type-appropriate footer to show's output:

$ syscribe show REQ-WEB-011
[... existing fields/documentation ...]

Related:
  syscribe trace REQ-WEB-011          full traceability slice
  syscribe who-verifies REQ-WEB-011   verifying TestCases
  syscribe impact REQ-WEB-011         downstream/upstream change impact
  syscribe refs REQ-WEB-011           inbound references

Only list commands that are meaningful for the shown element's type (e.g. who-verifies for a Requirement, not a PartDef; n2/connectivity for architecture elements). Suppressible with a flag (show --no-related) for scripting/piping contexts where the extra lines aren't wanted.

Acceptance criteria

  • show on a Requirement suggests trace/who-verifies/impact/refs
  • show on an architecture element (PartDef/Part) suggests impact/connectivity/n2/refs instead, not the requirement-specific ones
  • --json output is unchanged (footer is text-mode only)
  • --no-related suppresses the footer

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the existing show command and inspect how element types select behavior, how text and --json output are separated, and how command-line flags are defined. Verify the related-command footer for Requirements and architecture elements, confirm --no-related suppresses it, and ensure --json output remains unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.