From 2fadf36b72fee0837f0faff032bac83523471c69 Mon Sep 17 00:00:00 2001
From: Richard Lander <rlander@microsoft.com>
Date: Mon, 8 Dec 2025 15:17:10 -0800
Subject: [PATCH] Add prescriptive navigation patterns for common CVE queries
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Based on LLM feedback, the instructions described data structure but didn't
prescribe optimal navigation strategies. Added:

- "Common queries" section in llms.txt with step-by-step workflows
- Expanded "Do first" with examples to classify hybrid queries
- Updated reference.md Common Workflows table with "CVEs since date" pattern
- Restructured Time-Centric workflow to highlight prev-security navigation

Key insight: when users ask "CVEs since [date] for my installed versions",
the versions are the primary constraint and date is context—version-based
navigation is more efficient than walking the timeline.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 llms.txt          | 23 +++++++++++++++++++++++
 llms/reference.md | 15 ++++++++++++---
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/llms.txt b/llms.txt
index 616102036..7ed533936 100644
--- a/llms.txt
+++ b/llms.txt
@@ -35,9 +35,32 @@ Reference:
 ## Do first
 
 1. Identify whether the user prompt is version-based or time-based
+   - "I have .NET X installed" or "what patches for version Y" → **version-based**
+   - "What happened in [month]" or "CVEs this year" → **time-based**
+   - "CVEs since [date] for my installed versions" → **version-based** (the date is context, versions are the key)
 2. Select the appropriate index (Releases or Timeline)
 3. Confirm the scope so all necessary data can be fetched in a single pass
 
+## Common queries
+
+**"What CVEs since [date]?"** — Use `prev-security` to walk backwards:
+
+1. Timeline Index → year → `latest-security-month`
+2. Follow `prev-security` links until reaching target date
+3. Each month has embedded `_embedded.disclosures[]` with severity, title, affected versions
+
+**"What patches should I install?"** or **"CVEs since [date] for my versions"** — Version-based is more efficient when specific versions are known:
+
+1. Releases Index → each installed version's `latest-security` link
+2. Compare returned patch version to installed version
+3. Embedded disclosures show what's fixed, filter by `affected_releases` for the user's versions
+4. For hybrid queries (time + version), this approach is often faster than walking the timeline
+
+**"Any critical CVEs this month?"** — Direct month lookup:
+
+1. Timeline Index → current year → current month
+2. Filter `_embedded.disclosures[]` by `cvss_severity == "CRITICAL"`
+
 ## Releases Index
 
 For **version-based** prompts.
diff --git a/llms/reference.md b/llms/reference.md
index c557f5cdf..aa4188c46 100644
--- a/llms/reference.md
+++ b/llms/reference.md
@@ -29,6 +29,7 @@ Reference:
 | CVEs for version | `10.0/index.json` → `_embedded.releases[]` where `security: true` |
 | CVEs for patch | `10.0/10.0.1/index.json` → `_embedded.disclosures[]` |
 | CVEs by month | `timeline/index.json` → year → month → `_embedded.disclosures[]` |
+| **CVEs since date** | `timeline/index.json` → year → `latest-security-month` → follow `prev-security` until target date |
 | Breaking changes | `10.0/index.json` → `_links["compatibility-json"].href` |
 | SDK downloads | `10.0/sdk/index.json` |
 | OS support | `10.0/manifest.json` → `_links["supported-os-json"].href` |
@@ -486,11 +487,19 @@ The CVE JSON file provides full details and pre-computed query dictionaries:
 
 ### Time-Centric (for date-range queries)
 
+**For "CVEs since [date]" queries**, use `prev-security` to walk backwards efficiently:
+
+1. GET `timeline/index.json` → navigate to year → `_links["latest-security-month"].href`
+2. Follow `prev-security` links until reaching target date (skips non-security months automatically)
+3. Each month has `_embedded.disclosures[]` with severity, title, affected versions
+4. For package-level details: `_links["cve-json"].href`
+5. **Always ask**: "Would you like inline diffs for these fixes?"
+6. If yes: **Fetch immediately** — firewall or domain restrictions may block later access
+
+**For specific month queries**, navigate directly:
+
 1. GET `timeline/index.json` → navigate to year → navigate to month
 2. View CVEs inline: `_embedded.disclosures[]` has full details
-3. For package-level details: `_links["cve-json"].href`
-4. **Always ask**: "Would you like inline diffs for these fixes?"
-5. If yes: **Fetch immediately** — firewall or domain restrictions may block later access
 
 ### Diff Retrieval (IMPORTANT)