[docs] docs: unbloat safe rollout guidance#41272
Conversation
github-actions
Bot
added
automation
doc-unbloat
documentation
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #41272 does not have the 'implementation' label and has 0 new lines of code in business logic directories (1 file changed, default_business_additions=0, threshold=100). |
|
✅ PR Code Quality Reviewer completed the code quality review. |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped. |
There was a problem hiding this comment.
Pull request overview
This PR tightens the “Safe Rollout” practice documentation by reducing repetition and converting some list-heavy guidance into more compact prose, while keeping the same conceptual rollout ladder (report-only → staged → shadow evaluation → direct writes).
Changes:
- Condensed the introductory explanation and rollout ladder framing into fewer sentences.
- Converted “When Shadow Evaluation Is Needed” and “Example Shape” bullet lists into concise prose.
- Removed a duplicate “Related Documentation” link.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/practices/safe-rollout.md | Condenses and de-duplicates safe rollout guidance while preserving the ladder and key distinctions (staged vs shadow evaluation). |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
| - concurrency, deduplication, or serialization needs to be tested on a live-like surface | ||
| - maintainers need to inspect the actual produced state, not only proposed intent | ||
| - cross-repository writes, permissions, or dispatch boundaries need to be exercised safely | ||
| It is a good fit when the workflow must update real target objects to prove behavior, when concurrency or deduplication must be tested on a live-like surface, when maintainers need to inspect produced state rather than proposed intent, or when cross-repository writes, permissions, or dispatch boundaries need safe exercise. |
| - production repository: emits live events and contains authoritative later human truth | ||
| - ops repository: persists predictions, collects corrections, publishes reports, and updates instructions | ||
| - shadow repository: temporary non-production write target during rollout | ||
| A common repository split uses a production repository for live events and authoritative later human truth, an ops repository for predictions, corrections, reports, and instruction updates, and a shadow repository as a temporary non-production write target during rollout. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
One content regression in the compression
The prose condensation is generally clean and the duplicate link removal is correct. One finding: the bullet-to-prose conversion in "When Shadow Evaluation Is Needed" silently drops serialization from the list of conditions, reducing three distinct technical concerns to two. The other two existing review comments (awkward phrasing on line 29, hard-to-parse prose on line 53) are valid non-blocking style issues already raised.
🔎 Code quality review by PR Code Quality Reviewer · 29.6 AIC · ⌖ 7.28 AIC · ⊞ 5.2K
| - concurrency, deduplication, or serialization needs to be tested on a live-like surface | ||
| - maintainers need to inspect the actual produced state, not only proposed intent | ||
| - cross-repository writes, permissions, or dispatch boundaries need to be exercised safely | ||
| It is a good fit when the workflow must update real target objects to prove behavior, when concurrency or deduplication must be tested on a live-like surface, when maintainers need to inspect produced state rather than proposed intent, or when cross-repository writes, permissions, or dispatch boundaries need safe exercise. |
There was a problem hiding this comment.
Information loss: serialization was silently dropped from the shadow evaluation conditions.
💡 Details
The original bullet list explicitly listed three distinct concerns:
- concurrency, deduplication, or serialization needs to be tested on a live-like surface
The compressed prose omits serialization entirely:
when concurrency or deduplication must be tested on a live-like surface
Serialization (write ordering, idempotency under reordering) is distinct from concurrency (simultaneous access) and deduplication (repeated identical writes). These are three separate reasons to reach for shadow evaluation; removing one strips actionable guidance for workflows that need ordering guarantees.
Suggested fix:
when concurrency, deduplication, or serialization must be tested on a live-like surface
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — requesting changes on a factual omission and two scanability regressions.
📋 Key Themes & Highlights
Key Themes
- Factual omission:
serializationwas dropped from the shadow evaluation trigger list during bullet-to-prose conversion (line 29). - Scanability regressions: Two sections that served as decision checklists (shadow evaluation triggers, three-repository split) are harder to scan as run-on prose sentences than as the original bullets.
Positive Highlights
- ✅ The intro now explicitly names "shadow evaluation" instead of the vague "a more realistic safe-write technique" — this is a real vocabulary improvement.
- ✅ The
stagedvs. shadow evaluation contrast sentence is tighter and equally clear in its merged form. - ✅ Duplicate
MultiRepoOpslink removed cleanly. - ✅ Prose consolidations in the intro and staged-mode sections work well.
Note on Automation
This PR was generated by the Documentation Unbloat workflow. The prose simplifications are mostly successful; the two cases worth addressing are where list-to-prose conversion either lost information (serialization) or made the doc harder to use as a quick reference.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 42.6 AIC · ⌖ 7.49 AIC · ⊞ 6.5K
| - concurrency, deduplication, or serialization needs to be tested on a live-like surface | ||
| - maintainers need to inspect the actual produced state, not only proposed intent | ||
| - cross-repository writes, permissions, or dispatch boundaries need to be exercised safely | ||
| It is a good fit when the workflow must update real target objects to prove behavior, when concurrency or deduplication must be tested on a live-like surface, when maintainers need to inspect produced state rather than proposed intent, or when cross-repository writes, permissions, or dispatch boundaries need safe exercise. |
There was a problem hiding this comment.
[/grill-with-docs] The bullet-to-prose conversion silently drops serialization as a shadow-evaluation trigger condition — and the resulting when...when...when...or when sentence is harder to scan than the original list when practitioners use this as a decision checklist.
💡 Suggested restoration
The original bullets served two purposes: they were scannable, and they explicitly listed serialization alongside concurrency and deduplication. Consider keeping the list and restoring the missing condition:
It is a good fit when:
- the workflow must update real target objects to prove the behavior is correct
- concurrency, deduplication, or serialization needs to be tested on a live-like surface
- maintainers need to inspect the actual produced state, not only proposed intent
- cross-repository writes, permissions, or dispatch boundaries need to be exercised safelyIf prose is strongly preferred, at minimum restore serialization: "...when concurrency, deduplication, or serialization must be tested on a live-like surface..."
| - production repository: emits live events and contains authoritative later human truth | ||
| - ops repository: persists predictions, collects corrections, publishes reports, and updates instructions | ||
| - shadow repository: temporary non-production write target during rollout | ||
| A common repository split uses a production repository for live events and authoritative later human truth, an ops repository for predictions, corrections, reports, and instruction updates, and a shadow repository as a temporary non-production write target during rollout. |
There was a problem hiding this comment.
[/grill-with-docs] The three-repository split is easier to grasp as bullets than as a single 42-word compound sentence — readers scanning this section to understand the three roles must parse a complex clause chain rather than read three short labels.
💡 Suggested restoration
The original bullet list mapped one-to-one with the three distinct repository types and made each role immediately visible:
The common repository split is:
- production repository: emits live events and contains authoritative later human truth
- ops repository: persists predictions, collects corrections, publishes reports, and updates instructions
- shadow repository: temporary non-production write target during rolloutIf the goal is reducing line count, the intro sentence can be removed without converting to prose (just use the bullets directly).
docs: unbloat safe rollout
What changed
Prose edits to
docs/src/content/docs/practices/safe-rollout.md:Why
The page had accumulated bloat — redundant phrasing and unnecessary list structure — that made it harder to scan. This cleans it up without changing any technical guidance.
Impact