Tech debt clean-up in skills for rel note workflow

.agents/README.md

@@ -74,10 +74,12 @@ The agent handles the rest: reading the repo context guide, looking up PRs, sear
         ├── style-guide.md          # Grafana style rules and templates
         ├── best-practices.md       # Lessons learned and common pitfalls
         ├── verification-checklist.md  # Pre-submission quality checklist
-        ├── release-notes-workflow.md  # Multi-phase release notes process
         ├── metrics-generator-knowledge.md  # Domain knowledge for metrics-generator
         └── docs-context-guide.md   # Tempo docs context guide
 
+.claude/skills/shared/
+└── release-notes-workflow.md      # Multi-phase release notes process (moved here, #7446)
+
 .claude/skills/
 ├── README.md                       # Skills workflow overview
 ├── docs-workflow/SKILL.md          # End-to-end pipeline: check → write → review
@@ -111,9 +113,10 @@ These files live in [`doc-agents/shared/`](doc-agents/shared/) and are used by a
 | [`style-guide.md`](doc-agents/shared/style-guide.md)                                 | Grafana documentation style rules, templates, and formatting requirements                                    |
 | [`best-practices.md`](doc-agents/shared/best-practices.md)                           | Pre-writing checklist, common pitfalls, documentation patterns (for human writers)                           |
 | [`verification-checklist.md`](doc-agents/shared/verification-checklist.md)           | Comprehensive pre-submission checklist for accuracy, consistency, and completeness                           |
-| [`release-notes-workflow.md`](doc-agents/shared/release-notes-workflow.md)           | Multi-phase workflow for creating release notes, from CHANGELOG curation through final polish                |
 | [`metrics-generator-knowledge.md`](doc-agents/shared/metrics-generator-knowledge.md) | Pointer to `modules/generator/AGENTS.md` (metrics-generator domain knowledge) |
 
+The release notes workflow moved to [`.claude/skills/shared/release-notes-workflow.md`](../.claude/skills/shared/release-notes-workflow.md) (#7446) — it's no longer under `doc-agents/shared/`.
+
 ### Skills
 
 Skills are invokable workflows that live in `.claude/skills/`. They perform specific tasks and can be used independently or as part of a larger workflow.
@@ -156,7 +159,7 @@ Use the PR workflow when you have a list of PRs that need documentation work (ou
 
 Use the release notes workflow for creating per-version release notes. This is a multi-session process that combines shared resources and skills.
 
-1. Follow [`release-notes-workflow.md`](doc-agents/shared/release-notes-workflow.md) — it covers the full process from CHANGELOG curation (Phase 0) through final polish (Phase 5).
+1. Follow [`release-notes-workflow.md`](../.claude/skills/shared/release-notes-workflow.md) — it covers the full process from source curation (Phase 0) through final polish (Phase 5).
 2. At Phase 1.5, run `/docs-pr-check` to assess documentation status for each PR.
 3. At Phase 1.75, run `/docs-pr-write` to fill documentation gaps.
 4. Reference [`style-guide.md`](doc-agents/shared/style-guide.md) throughout for formatting and conventions.

.claude/skills/README.md

@@ -72,6 +72,7 @@ These files are loaded by skills automatically. This section is for maintainers
 | `.claude/skills/shared/verification-checklist.md` | Pre-submission checklist for accuracy and completeness |
 | `.claude/skills/shared/best-practices.md` | Pre-writing checklist and common pitfalls |
 | `.claude/skills/shared/release-notes-workflow.md` | Multi-phase workflow for release notes |
+| `.claude/skills/shared/release-notes-placement.md` | Where changelog entries belong in the release notes |
 | `.claude/skills/shared/docs-context-guide.md` | General repo orientation for doc tasks |
 | `.claude/skills/shared/load-context.md` | Instructions for loading local project context |
 | `.claude/skills/shared/personas.md` | Persona and intent model for audience-fit checks |

.claude/skills/shared/README.md

@@ -88,11 +88,41 @@ This directory contains **foundation** resources for documentation agents and wr
 
 **Key contents**:
 
-- Multi-phase workflow (CHANGELOG curation, docs assessment, gap resolution, drafting, validation)
+- Multi-phase workflow (pending-entry curation, docs assessment, gap resolution, drafting, validation)
 - PR classification (docs present, docs needed, docs update needed, no docs required)
 - Templates and prompts
 - Iteration checklist for quality
 
+### [`release-notes-placement.md`](release-notes-placement.md)
+
+**Purpose**: Where each changelog entry belongs in the release notes
+
+**When to use**:
+
+- Phase 0 sorting (required from Step 3b of the workflow)
+- Deciding highlight vs brief include vs cite prior notes vs exclude
+
+**Key contents**:
+
+- Placement labels
+- Normal-minor vs cite-earlier-notes
+- Always-keep and exclude lists
+
+### [`vale-compact.sh`](vale-compact.sh)
+
+**Purpose**: Compact Vale output for linting docs
+
+**When to use**:
+
+- Running the linter during Phase 5 of the release notes workflow or during `docs-review`
+- Anywhere `vale <file>` would be used -- same findings, without Vale's repeated per-finding boilerplate paragraph
+
+**Key contents**:
+
+- Wraps `vale --output=JSON` and prints one line per finding (`file:line:col  severity  Rule  'matched text'`) plus a count-by-rule summary
+- Falls back to raw `vale` output (or a warning) if `jq` or `vale` aren't installed
+- Exits non-zero only if an `error`-severity finding remains
+
 ### [`personas.md`](personas.md)
 
 **Purpose**: Persona and intent model for audience-fit checks
@@ -122,10 +152,11 @@ This directory contains **foundation** resources for documentation agents and wr
 ### For Release Notes
 
 1. **Follow** [`release-notes-workflow.md`](release-notes-workflow.md) for the complete multi-phase process
-2. **Use** [`../docs-pr-check/SKILL.md`](../docs-pr-check/SKILL.md) for documentation assessment
-3. **Use** [`../docs-pr-write/SKILL.md`](../docs-pr-write/SKILL.md) for documentation gap resolution
-4. **Reference** [`style-guide.md`](style-guide.md) for general style rules
-5. **Use** [`verification-checklist.md`](verification-checklist.md) before submitting
+2. **Read** [`release-notes-placement.md`](release-notes-placement.md) during Phase 0 sorting
+3. **Use** [`../docs-pr-check/SKILL.md`](../docs-pr-check/SKILL.md) for documentation assessment
+4. **Use** [`../docs-pr-write/SKILL.md`](../docs-pr-write/SKILL.md) for documentation gap resolution
+5. **Reference** [`style-guide.md`](style-guide.md) for general style rules
+6. **Use** [`verification-checklist.md`](verification-checklist.md) before submitting
 
 ### For Updating Existing Documentation
 
@@ -147,7 +178,7 @@ This directory contains **foundation** resources for documentation agents and wr
 |------|-----------------|-------------------|
 | Starting new docs | `docs-context-guide.md` | `style-guide.md` |
 | Updating docs | `docs-context-guide.md` | `verification-checklist.md` |
-| Writing release notes | `release-notes-workflow.md` | `style-guide.md` |
+| Writing release notes | `release-notes-workflow.md` | `release-notes-placement.md` |
 | PR docs assessment (triage) | `../docs-pr-check/SKILL.md` | `release-notes-workflow.md` |
 | PR docs writing (execution) | `../docs-pr-write/SKILL.md` | `release-notes-workflow.md` |
 | Metrics-generator work | `.agents/doc-agents/shared/metrics-generator-knowledge.md` | `verification-checklist.md` |

.github/instructions/docs/release-notes.instructions.md

@@ -16,12 +16,14 @@ Write release notes for software developers, SREs, and platform engineers who us
 
 Focus on user impact, practical examples, and clear upgrade guidance.
 
-## Workflow
+## Style
 
-Follow the full multi-phase workflow defined in [`.claude/skills/shared/release-notes-workflow.md`](../../../.claude/skills/shared/release-notes-workflow.md).
+Use "Grafana Tempo" on first mention, then "Tempo." Use "TraceQL" (not "traceql"), "vParquet4"/"vParquet5" (lowercase v, no space), "metrics-generator" (hyphenated), and reference versions as "Tempo X.Y." Use "refer to," not "see," for links. Use the version placeholder for internal doc links: `/docs/tempo/<TEMPO_VERSION>/path/to/doc/`. Always include PR links: `[[PR 5982](https://github.com/grafana/tempo/pull/5982)]`, or `(PRs [#5939](...), [#6001](...))` for multiple. For general documentation style, refer to [`.claude/skills/shared/style-guide.md`](../../../.claude/skills/shared/style-guide.md).
 
-That file is the source of truth for all release notes phases, including CHANGELOG curation (Phase 0), documentation assessment (Phase 1.5), documentation gap resolution (Phase 1.75), writing, validation, patch release handling, example prompts, and the iteration checklist.
+This style block applies to every edit under `release-notes/`, including small fixes to already-shipped files. It does not require reading the full workflow.
 
-## Style
+## Workflow
+
+Load the full multi-phase workflow at [`.claude/skills/shared/release-notes-workflow.md`](../../../.claude/skills/shared/release-notes-workflow.md) only when **creating a new version's release notes** or **applying a patch-release update** (for example, adding a `X.Y.Z` security or bug-fix section to an existing file). That file is the source of truth for all release notes phases: source curation (Phase 0, with its own human-review gate), documentation assessment (Phase 1.5), documentation gap resolution (Phase 1.75), writing, validation, patch release handling, example prompts, and the iteration checklist.
 
-Follow the style conventions in [`.claude/skills/shared/release-notes-workflow.md`](../../../.claude/skills/shared/release-notes-workflow.md) (the "Style guidelines" section) for Tempo-specific naming, PR link format, documentation links, and TraceQL and configuration examples. For general documentation style, refer to [`.claude/skills/shared/style-guide.md`](../../../.claude/skills/shared/style-guide.md).
+Do not load it for style-only edits, typo fixes, or link corrections — the style block above already covers those.

docs/project-context.md

@@ -141,6 +141,7 @@ Paths the agent should check when validating documentation claims against code.
 | `.agents/guidance/precommit.md` | Pre-commit checklist |
 | `.claude/skills/shared/style-guide.md` | Docs style guide |
 | `.claude/skills/shared/release-notes-workflow.md` | Release notes process |
+| `.claude/skills/shared/release-notes-placement.md` | Changelog-to-release-notes placement |
 | `.claude/skills/shared/verification-checklist.md` | Docs verification |
 | `.claude/skills/shared/best-practices.md` | Docs best practices |
 | `.claude/skills/shared/docs-context-guide.md` | Docs context guide |