Skip to content

Add SSVC doc explaining "human-scale bottleneck" idea#1087

Open
ahouseholder wants to merge 15 commits intomainfrom
fix-1033
Open

Add SSVC doc explaining "human-scale bottleneck" idea#1087
ahouseholder wants to merge 15 commits intomainfrom
fix-1033

Conversation

@ahouseholder
Copy link
Copy Markdown
Contributor

resolves #1033


This pull request adds a new documentation file explaining the role of SSVC (Stakeholder-Specific Vulnerability Categorization) as a human-scale bottleneck in automated vulnerability response processes. The document clarifies how SSVC condenses complex, automated data into manageable decision points, and emphasizes the importance of human oversight in policy definition and governance.

Key additions to documentation:

  • Introduced a comprehensive explanation of SSVC as a human-scale bottleneck, ensuring transparency and accountability in automated vulnerability response workflows.
  • Detailed the characteristics of SSVC decision points, including their ordinal, orthogonal, and "chunky" nature, which keeps the decision table compact and understandable.
  • Explained how the SSVC decision table codifies policy as code, mapping technical inputs to business-aligned outcomes, and outlined criteria for effective table design.
  • Provided guidance on governance and policy refinement, describing how SSVC enables straightforward modification and clear accountability for risk owners.
  • Clarified that SSVC is not a process bottleneck—automation can occur throughout, with humans responsible for designing and governing the decision framework rather than reviewing every decision.

Copilot AI review requested due to automatic review settings March 12, 2026 20:07
@ahouseholder ahouseholder self-assigned this Mar 12, 2026
@ahouseholder ahouseholder requested a review from sei-renae March 12, 2026 20:07
@ahouseholder ahouseholder added the content/semantic Changes to the semantic content of the SSVC documentation label Mar 12, 2026
@ahouseholder ahouseholder added this to the 2026-03 milestone Mar 12, 2026
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

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

Pull request overview

Adds a new How-To documentation page explaining SSVC’s role as a “human-scale bottleneck” between large-scale automated vulnerability data collection/analysis and large-scale operational response, emphasizing policy governance and accountability.

Changes:

  • Added a new documentation page describing SSVC decision points as a compact, human-governable interface in automated workflows.
  • Documented design characteristics (ordinal/orthogonal/chunky) and how decision tables encode organizational policy and governance refinement.

You can also share your feedback on Copilot code review. Take the survey.

@sei-renae
Copy link
Copy Markdown
Contributor

sei-renae commented Mar 18, 2026

Some high level notes:

  1. This does not read like a "how to guide" per the diataxis framework. It seems more akin to an "explanation."
  2. I don't know who the audience is
  3. H2 "The Decision Table: Policy as Code" lost my interest as a reader, if I'm expecting to learn about a human bottleneck

Copy link
Copy Markdown
Contributor

@sei-renae sei-renae left a comment

Choose a reason for hiding this comment

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

See comments in-line and in the Conversation.

ahouseholder and others added 4 commits March 30, 2026 15:03
- Move file from docs/howto/ to docs/topics/ (parallels decision_points_as_bricks.md,
  addresses Diataxis how-to vs. explanation concern)
- Update mkdocs.yml nav: remove from howto, add to topics alongside
  decision_points_as_bricks.md
- Fix intro: add 'designed by humans, for humans' thesis and 'not a process
  bottleneck' clarification at top of document (threads at lines 68, 107)
- Add diagram scope clarification: make explicit that Decision Model = SSVC scope,
  Data Mapping and Use & Respond are adjacent but outside scope (thread at line 36)
- Fix 'layer' jargon: replace 'any layer of the model' with explicit enumeration
  of outcomes, decision points, decision table, and data mapping (thread at line 97)
- Fix Use & Respond contradiction: remove direct feedback link that conflicted
  with use.md documentation; restate as 'observing real-world results' (line 105)
- Add prepare.md hyperlink to Input Automation section (thread at line 113)
- Fix all relative links: bootstrap/ -> ../howto/bootstrap/ after file move

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Introduces the standard AI/autonomy term 'human-on-the-loop' in two places
to connect it explicitly to the 'human-scale bottleneck' concept:

- Introduction: adds one sentence defining the term after establishing that
  the decision table can be fully automated
- Conclusion: replaces the closing sentence with an explicit 'human-on-the-loop'
  framing that ties accountability to policy governance, not per-decision review

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ahouseholder ahouseholder requested a review from sei-renae March 30, 2026 20:06
ahouseholder and others added 2 commits April 13, 2026 13:24
- Reframe opening sentence to lead with what SSVC does (not 'designed to provide')
- Emphasize 'on' in human-on-the-loop (H**O**TL) per reviewer request
- Fix broken CSAF URL split across lines
- Lowercase 'large language models' (not a proper noun)
- Simplify 'mathematical properties of intervals' to 'equal spacing between values'
- Replace repetitive lead-in for 'Role of the Human' section with fresh sentence
- Fix odd spacing: rejoin split quote in Output Automation bullet
- Keep link to prepare.md for data mapping (correct; collect.md covers data ops)
- Fix markdownlint issues (trailing spaces, list indentation)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ahouseholder ahouseholder requested a review from sei-renae April 13, 2026 17:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

content/semantic Changes to the semantic content of the SSVC documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write up the "SSVC as human-scale bottleneck" concept

3 participants