Update CVE navigation strategy for parallel fetches with date filtering

- cve.md: Split strategy by scope (1-3 months: prev-security walk, 4+ months: year index with date filter + parallel fetch) - cve.md: Clarify "last N months" means calendar months, not security releases - cve.md: Update common mistakes to focus on proper date filtering - llms.txt, SKILL.md: Switch skill URLs from commit-specific to branch-based 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-19 18:06:02 -05:00 · 2025-12-16 21:05:42 -08:00
parent f5562f9462
commit 70e931460a
3 changed files with 47 additions and 38 deletions
--- a/llms.txt
+++ b/llms.txt
@@ -27,17 +27,17 @@ Fetch these when your query matches. **Core Rules above apply to all skills.**

 | Skill | Fetch When | URL |
 |-------|------------|-----|
-| cve.md | CVE queries needing severity, CVSS, or history | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/cve.md |
-| breaking-changes.md | Compatibility or migration questions | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/breaking-changes.md |
-| version-eol.md | EOL versions, support lifecycle, or version history | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/version-eol.md |
-| os-support.md | OS packages, distro support, or glibc requirements | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/os-support.md |
+| cve.md | CVE queries needing severity, CVSS, or history | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/cve.md |
+| breaking-changes.md | Compatibility or migration questions | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/breaking-changes.md |
+| version-eol.md | EOL versions, support lifecycle, or version history | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/version-eol.md |
+| os-support.md | OS packages, distro support, or glibc requirements | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/os-support.md |

 ### Broad Skills

 | Skill | Fetch When | URL |
 |-------|------------|-----|
-| navigation.md | Multi-hop query and unsure which links to follow | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/navigation.md |
-| schema.md | Need to understand document structure, properties, or link relations | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/schema.md |
+| navigation.md | Multi-hop query and unsure which links to follow | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/navigation.md |
+| schema.md | Need to understand document structure, properties, or link relations | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/schema.md |

 ## Quick Answers (1 fetch)

--- a/release-notes/skills/SKILL.md
+++ b/release-notes/skills/SKILL.md
@@ -32,17 +32,17 @@ Fetch these when your query matches. **Core Rules above apply to all skills.**

 | Skill | Fetch When | URL |
 |-------|------------|-----|
-| cve.md | CVE queries needing severity, CVSS, or history | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/cve.md |
-| breaking-changes.md | Compatibility or migration questions | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/breaking-changes.md |
-| version-eol.md | EOL versions, support lifecycle, or version history | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/version-eol.md |
-| os-support.md | OS packages, distro support, or glibc requirements | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/os-support.md |
+| cve.md | CVE queries needing severity, CVSS, or history | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/cve.md |
+| breaking-changes.md | Compatibility or migration questions | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/breaking-changes.md |
+| version-eol.md | EOL versions, support lifecycle, or version history | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/version-eol.md |
+| os-support.md | OS packages, distro support, or glibc requirements | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/os-support.md |

 ### Broad Skills

 | Skill | Fetch When | URL |
 |-------|------------|-----|
-| navigation.md | Multi-hop query and unsure which links to follow | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/navigation.md |
-| schema.md | Need to understand document structure, properties, or link relations | https://raw.githubusercontent.com/dotnet/core/f2e0092e15c15c520b8279ecde8c7b554e9c4fbe/release-notes/skills/schema.md |
+| navigation.md | Multi-hop query and unsure which links to follow | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/navigation.md |
+| schema.md | Need to understand document structure, properties, or link relations | https://raw.githubusercontent.com/dotnet/core/refs/heads/release-index/release-notes/skills/schema.md |

 ## Quick Answers (1 fetch)

--- a/release-notes/skills/cve.md
+++ b/release-notes/skills/cve.md
@@ -26,39 +26,43 @@ llms.json

 ## Navigation Strategies

-Choose based on query type:
+**Important:** "Last N months" means **calendar months** from today, not "N security releases." Security months are sparse—there may be only 9 security months in a 12-calendar-month window.
+
+Choose based on query scope:

 | Query Type | Strategy | Why |
 |------------|----------|-----|
-| "Last N months" (bounded) | `prev-security` walk | Self-limiting, stops when done |
-| "All CVEs in [year]" or multi-year | Year index batch | Parallel fetches for known scope |
+| "Last 1-3 months" | `prev-security` walk | Low overhead, few fetches |
+| "Last 4+ months" | Year index with date filter | Parallel fetches, fewer round trips |
+| "All CVEs in [year]" | Year index batch | Known scope, parallel fetches |

-### Strategy 1: `prev-security` Walk (Default)
+### Strategy 1: `prev-security` Walk

-**Use for:** Any "last N months" query, regardless of N
+**Use for:** Small scope (1-3 calendar months)

 ```
-llms.json → latest-security-month → prev-security → prev-security... → stop after N months
+llms.json → latest-security-month → prev-security → stop when date < cutoff
 ```

- Self-limiting: you stop when you've collected enough months
- Works for 3 months or 12 months—just walk until done
- No risk of over-fetching
+- Sequential but low overhead for small N
+- Stop when month date falls before your cutoff date

-**Example:** "Last 12 months" = start at latest-security-month, walk `prev-security` until you've covered 12 calendar months, stop.
+### Strategy 2: Year Index with Date Filter

-### Strategy 2: Year Index Batch
-
-**Use ONLY for:** "All CVEs in 2024" or "CVEs from 2023-2025" (explicit year scope)
+**Use for:** Larger scope (4+ calendar months) or explicit year queries

 ```
-llms.json → timeline-index → year index
-         → batch fetch month indexes where security: true
+llms.json → timeline-index → year index(es)
+         → filter _embedded.months[] by date range AND security: true
+         → parallel fetch only the months you need
 ```

- Appropriate when query explicitly names years
- Fetch all security months within those years
- NOT for "last N months" queries (use walk instead)
+**Critical:** Filter to your date range—don't fetch entire years when only part is needed.
+
+**Example:** "Last 12 months" query, today is Oct 2025:
+1. Fetch 2024 and 2025 year indexes
+2. Filter to months where `security: true` AND date >= Oct 2024
+3. Parallel fetch those month indexes (typically 8-10 fetches in one turn)

 ### Filtering by Version

@@ -78,12 +82,17 @@ Do NOT navigate to the version index (e.g., `8.0/index.json`) for CVE queries—
 2. Follow `_links["latest-security-month"]` → month index
 3. Filter `_embedded.disclosures[]` where `cvss_severity == "CRITICAL"`

-### CVEs for .NET X in last N months (2-4 fetches)
+### CVEs for .NET X in last N months (3-5 fetches)

-1. Fetch `llms.json`
-2. Follow `_links["latest-security-month"]` → month index
-3. Filter `_embedded.disclosures[]` where `affected_releases` contains "X.0"
-4. Walk `_links["prev-security"]` for N months, filtering each
+**For 1-3 months:** Use `prev-security` walk
+1. Fetch `llms.json` → follow `latest-security-month`
+2. Walk `prev-security` until date < cutoff, filtering by `affected_releases`
+
+**For 4+ months:** Use year index with date filter
+1. Fetch `llms.json` → follow `timeline-index` → fetch relevant year index(es)
+2. Filter `_embedded.months[]` to date range + `security: true`
+3. Parallel fetch those month indexes
+4. Filter `_embedded.disclosures[]` where `affected_releases` contains "X.0"
 5. For code fixes: use `fixes[].href` directly (already `.diff` URLs)

 ### Deep CVE analysis (3 fetches)
@@ -137,11 +146,11 @@ Example:

 | Mistake | Why It's Wrong |
 |---------|----------------|
-| Using year index batch for "last N months" queries | Use `prev-security` walk instead—it self-limits |
-| Fetching all security months from year indexes | Year index batch is for explicit year queries ("all of 2024"), not "last 12 months" |
+| Fetching ALL months from year indexes | Filter by date range first—"last 12 months" doesn't need all of 2024 |
+| Confusing "12 months" with "12 security releases" | Calendar months, not security months—filter by date, not count |
 | Fetching `cve.json` for severity/CVSS | Month index `_embedded.disclosures[]` already has this data |
 | Constructing month URLs without checking year index | Always check `_embedded.months[]` for `security: true` first |
-| Fabricating intermediate month URLs | Trust `prev-security` links—they skip non-security months automatically |
+| Fabricating intermediate month URLs | Use `_links` from year index or `prev-security` links |
 | Fabricating GitHub commit URLs | Use `fixes[].href` from disclosures—already formatted as `.diff` URLs |

 ## Tips