Repository navigation
Make the LLM architectural brief actionable (lead with the dependency story, not a 13-vector table) #3113
Description
Found by the real-repo plausibility audit of a galaxyscope scan of IBM's zopeneditor-sample (COBOL/PL-I/JCL/HLASM/REXX, 51 files / 3,265 LOC), engine main just after REXX #2504 / PR #3107.
Coupled with #3112 (remove the Cumulative Risk composite): that issue retires section 11's ranking basis, this one owns what replaces the presentation. They should land together or in order.
What the scan shows
The scan produced an 883-line brief for 51 files / 3,265 LOC. Its most verifiable and most valuable content — the cross-language dependency graph — is buried in section 7, behind ~170 lines of lexicon, formula exposition and a 13-row statistics table. Meanwhile sections 11 and 12 repeat per-file detail in two formats.
The graph content was independently verified correct against the source on this audit:
INCLUDES/BALSTATS.increally is the most-depended-on artifact — 3 inbound, and all three PL/I programs do%INCLUDE BALSTATS.JCL/RUN.jclreally is the top orchestrator — 14 outbound; it is the compile-and-link-everything job.
That is the differentiated output, and it should lead.
The gap
The brief answers "what do I have" but never "what should I do next" — and it already holds the substrate for the second answer without assembling it. Per-file dependency edges plus per-function magnitude are exactly what is needed to say "changing SAM1 touches these copybooks and these JCL jobs — here is the blast radius." No section states a consequence or a recommended order of work.
Requested direction
The shape is the maintainer's call; recording these as the asks:
- An up-front executive section — dominant languages, the orchestration story, the load-bearing artifacts, the articulation points — before any formula exposition.
- A per-finding "why this matters / what it affects" line, derived from the dependency edges the brief already computes, replacing the current Primary-Risk-Drivers line that reprints ceiling-defaulted vectors (see Make the Spec Alignment (risk_spec_match) vector opt-in, default OFF #3111, Remove the Cumulative Risk composite (unitless sum of 13 mixed-unit vectors) #3112).
- Deduplicate sections 11 and 12 into one ranked file list, now that the cumulative-risk ranking is being retired (Remove the Cumulative Risk composite (unitless sum of 13 mixed-unit vectors) #3112). The ranking basis becomes structural magnitude and/or blast radius, which are unit-honest.
- Keep the section 2 lexicon and the Epic: exposure deltas vs independently identified events — risk over Git history (Rung 6; the validation.md harness) #2982/The risk_* vectors measure activity, not risk — rename, reframe, or split (evidence: the full #2982 validation record) #2991 non-predictive disclaimer, but move them to an appendix. The honesty is an asset and should not be the first thing a reader wades through.
Audience split
This artifact is consumed by an LLM and read by humans, and those two want different shapes. If the resolution is two renderings from one data set rather than one compromise document, that is a legitimate answer to this issue.
Activity
feat(report): stop the risk surface claiming more than it measures (#…