Skip to content

issue_69: Separate what a risk affects from what mitigates it - #70

Merged
dieterbaier merged 2 commits into
mainfrom
issue_69
Jul 29, 2026
Merged

issue_69: Separate what a risk affects from what mitigates it#70
dieterbaier merged 2 commits into
mainfrom
issue_69

Conversation

@dieterbaier

Copy link
Copy Markdown
Member

Closes #69. Two commits, one per problem.

1. The register labelled harm as mitigation

fa0c854. The Risk index headed a column Mitigation/action and filled it
from the risk's outgoing affects relations — which point at what the risk
endangers. This repository's own register was the clearest case: every risk
names a quality scenario there, so it read as if the scenario mitigated the risk
it is threatened by.

mitigates was in the relation enum and no generator had ever read it.
grep -n mitigates scripts/validate-metamodel.rb returned nothing, while four
ADRs here declare it. Relations are only ever authored outgoing, so the question
"what mitigates this risk?" can only be answered from the incoming direction —
which ArtifactRenderHelper already had the artifacts for.

The column is split rather than replaced, per the discussion on #69: what a risk
affects is worth seeing next to what is being done about it.

Before, for this repository's own R-001:

ID Risk Mitigation/action
R-001 AI Suggestions Are Mistaken For Reviewed Architecture Truth QS-004-ai-suggestion-reviewability

After:

ID Risk Affects Mitigation/action
R-001 AI Suggestions Are Mistaken For Reviewed Architecture Truth QS-004-ai-suggestion-reviewability ADR-007-artifact-provenance-metadata

That ADR-007 link is data this repository has carried all along.

2. Prose assessments collapsed the table

1bbb773. Likelihood, Impact and Priority were lifted verbatim into
columns one tenth of the table wide. Nothing said those fields had to be terse,
so writing the explanatory sentence an assessment actually wants wrecked the
generated register — discoverable only by rendering it.

summary_cell takes the leading sentence, so the verdict reaches the register
and the reasoning stays in the artifact. Only a real sentence boundary counts, so
Medium (rises when hosted) survives whole.

Truncating silently would swap one invisible rule for another, so
templates/risk.adoc and skills/risk/SKILL.md now state it, and the template
gained a place to put the reasoning.

Verification

  • ./build.sh test, validate, check-adapters, generate — all exit 0, and
    the worktree is clean after generate.
  • Two new tests in test/validate_metamodel_test.rb. Both were confirmed to fail
    against main before the fix — the register test on the column header, the
    truncation test with NoMethodError.
  • The 38 pre-existing bidirectional-relation warnings are unchanged; they are on
    main too and are not touched here.

Provenance

Found while writing a second risk artifact in a project that consumes the
toolkit. The register only became visibly wrong once there was a second row to
compare against.

🤖 Generated with Claude Code

Dieter Baier and others added 2 commits July 29, 2026 20:02
The risk register headed a column "Mitigation/action" and filled it from
the risk's outgoing `affects` relations. Those are opposites: `affects`
points at what the risk endangers. Every risk in this repository names a
quality scenario there, so the register told readers that the scenario
mitigates the risk it is threatened by -- in the one artifact people scan
without opening the detail pages.

`mitigates` already existed in the relation enum and no generator had
ever read it. Four ADRs here declare it, and none of that reached the
register. It is only ever authored outgoing, so answering "what mitigates
this risk?" needs the incoming direction -- which the render helper
already held the artifacts for.

Splits the column in two rather than replacing it: what a risk affects is
worth seeing next to what is being done about it.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The register lifts likelihood, impact and priority verbatim into columns
one tenth of the table wide. Nothing says those source fields have to be
terse, so writing a normal explanatory sentence -- which is what an
assessment wants -- collapses the generated table, and the author only
finds out by rendering it.

The source artifact should not have to be written for its own index.
`summary_cell` takes the leading sentence, so the verdict reaches the
register and the reasoning stays where it belongs. Only a real sentence
boundary counts: "Medium (rises when hosted)" survives whole.

The template and the risk skill now say so too. Truncating silently would
trade one invisible rule for another.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@dieterbaier dieterbaier left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review-Ergebnis: sieht gut aus. ✅

Die beiden in #69 beschriebenen Probleme sind sauber und an der richtigen Stelle behoben:

  • Der Generator trennt jetzt korrekt zwischen dem, was ein Risiko gefährdet (affects), und dem, was es mindert (eingehende mitigates-Relationen). Damit wird die Semantik aus dem Metamodell nicht länger im wichtigsten Überblicksartefakt umgedreht.
  • incoming_relation_sources folgt konsequent der bestehenden Regel, Relationen nur ausgehend zu pflegen und die Gegenrichtung bei der Generierung abzuleiten. Sortierung und Fallback sind deterministisch.
  • Die Bewertungsspalten übernehmen mit summary_cell nur noch das führende Urteil. Gleichzeitig wird diese Projektionsregel nicht heimlich eingeführt, sondern sowohl im Risk-Skill als auch im Template erklärt.
  • Die Tests decken die falsche Spaltenbelegung sowie Satzgrenze, Klammerzusatz und leeren Wert ab.
  • Der GitHub-Workflow Validate ist für den aktuellen Head erfolgreich durchgelaufen.

Besonders gut: Affects wurde nicht einfach entfernt. Beide Richtungen sind für ein Risk Register relevant und stehen nun mit ehrlichen Überschriften nebeneinander.

Von meiner Seite keine blockierenden Findings. Eine formale Freigabe lässt GitHub nicht zu, weil der PR vom verbundenen Benutzer selbst stammt.

@dieterbaier
dieterbaier merged commit 1197086 into main Jul 29, 2026
1 check passed
@dieterbaier
dieterbaier deleted the issue_69 branch July 29, 2026 18:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Risk register labels harm as mitigation, and lifts prose into a width-1 column

1 participant