[docs] docs: unbloat correction-ops.md#33375
Conversation
Consolidate duplicate statements about "production stays authoritative", collapse repetitive intro/how-it-works paragraphs into tighter prose, convert a 4-bullet rollout list to prose, and tighten verbose subsection descriptions while preserving all code examples, the mermaid diagram, the stable-contracts list, and all reference links. Reduction: ~17% words, ~25% bullet points. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
automation
doc-unbloat
documentation
There was a problem hiding this comment.
Pull request overview
This PR trims and consolidates the experimental CorrectionOps documentation to reduce repetition while keeping the core workflow description, examples, and reference links intact.
Changes:
- Consolidates the intro and “When to Use” sections into tighter prose while preserving the 3-step loop and usage guidance.
- Streamlines “How It Works” and the post-diagram explanation, removing repeated statements and tightening phrasing.
- Shortens the “Full Workflow Pieces” subsection lead-ins while keeping the four-part breakdown and code examples.
Show a summary per file
| File | Description |
|---|---|
docs/src/content/docs/experimental/correction-ops.md |
Reduces repetition/verbosity across the CorrectionOps explainer while preserving examples, diagram, stable contracts, and related links. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
docs/src/content/docs/experimental/correction-ops.md:90
- “Forwards stable facts…” is a sentence fragment and also uses “ops” lowercase. Consider rewriting as a full sentence (e.g., starting with “The relay forwards…”) and capitalizing “Ops” if you mean the Ops surface defined above.
Forwards stable facts and provenance into ops only — no diffs, no human-intent inference, no correctness decisions.
- Files reviewed: 1/1 changed files
- Comments generated: 1
| That means the workflows usually stay in Ops. Early on they report, compare, and adapt from Ops without writing back to production. After promotion they can write directly to production. | ||
| A clean CorrectionOps setup has two long-lived surfaces. Production stays authoritative. Ops hosts prediction, correction intake, reporting, instruction updates, and rollout control — early on without writing back to production, later with direct writes once promoted. | ||
|
|
||
| Most implementations reduce to three workflow classes: a thin relay that forwards stable facts into ops, a prediction workflow that persists snapshots and writes safely, and a compare/report/decide workflow that checks later human truth and updates the system when the evidence is strong enough. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs and /zoom-out based on this documentation refactoring.
Summary
This is a well-executed compression pass that removes genuine bloat — duplicate statements, verbose subsection intros, and low-value bullet lists — while preserving all technical content (code examples, mermaid diagram, stable contracts, links). The -17% word reduction makes the document easier to scan without sacrificing accuracy.
Two inline comments flag places where the compression may have removed slightly too much scaffolding for first-time readers: the "healthy loop" characteristics and concrete use-case examples. Both are minor and optional.
Key Themes
- Domain language preserved: CorrectionOps terminology (Production, Ops, staged, predictions, corrections) remains consistent throughout
- Architectural clarity maintained: Two-surface model and three-workflow-class breakdown still clear
- Pedagogical trade-off: Tighter prose assumes faster reader comprehension; some helpful repetition removed
Positive Highlights
- ✅ Excellent duplicate removal — "Production stays authoritative" consolidated from 3× to 1×
- ✅ Bullet-to-prose conversions — Rollout path now reads more fluidly inline
- ✅ Complete preservation — All code, diagrams, and contracts intact
- ✅ Consistent technical accuracy — No errors introduced during compression
- ✅ Professional PR description — Clear bloat-type taxonomy and reduction metrics
Verdict
The compression is sound. The two inline comments are suggestions, not blockers — the doc is already improved. Approving with optional refinements noted.
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · ● 2.6M
| In a healthy CorrectionOps loop, production truth stays authoritative, predictions are saved explicitly, corrections include provenance, and diffs are built deterministically before the agent is asked to reason about them. | ||
|
|
||
| CorrectionOps does not require a separate evaluation repository. The normal progression is to start with `staged: true`, then use ops-managed adaptation and gated review, then enable direct production writes once the evidence is strong enough. | ||
| Unlike Reinforcement Learning from Human Feedback (RLHF), which updates model weights, CorrectionOps changes instruction files, routing rules, deterministic checks, thresholds, or rollout decisions — no separate evaluation repository required. |
There was a problem hiding this comment.
[/grill-with-docs] The compressed post-mermaid sentence loses important operational characteristics that help readers understand what makes a CorrectionOps loop "healthy".
The original listed specific practices:
- Production truth stays authoritative
- Predictions are saved explicitly
- Corrections include provenance
- Diffs are built deterministically before agent reasoning
Consider restoring at least a condensed version:
In a healthy CorrectionOps loop, production truth stays authoritative, predictions are saved explicitly, corrections include provenance, and diffs are built deterministically before the agent reasons about them.These aren't just nice-to-haves — they're the implementation checklist for the pattern.
| 4. rollout gate contract: what evidence or approvals are required before direct production writes are enabled | ||
|
|
||
| Discussion labeling, routing, moderation, prioritization, approvals, and summaries can all reuse this shape. The production object changes, but the CorrectionOps setup does not. | ||
| The production object changes across use cases, but the CorrectionOps shape does not. |
There was a problem hiding this comment.
[/zoom-out] The abstraction here is cleaner but loses concrete anchoring examples that help readers connect the pattern to their own use cases.
The original explicitly listed:
- Discussion labeling
- Routing
- Moderation
- Prioritization
- Approvals
- Summaries
While these were mentioned earlier in the doc, repeating them here reinforces the pattern's generality with tangible scenarios. Consider keeping at least 2-3 examples inline:
The production object changes across use cases (discussion labeling, routing, moderation, prioritization), but the CorrectionOps shape does not.This maintains the tight prose while giving readers concrete footholds.
Summary
Documentation refactoring that condenses and streamlines the CorrectionOps experimental pattern guide by consolidating verbose explanations into tighter prose, removing redundant examples, and shortening workflow descriptions while preserving all technical content.
Change Classification
Type: Documentation
Scope: Experimental patterns guide
Impact: Low
Breaking Changes: None
Files Changed
Modified
docs/src/content/docs/experimental/correction-ops.mdTechnical Details
This is a documentation quality improvement with no functional changes:
Testing & Validation
Documentation-only change. No code, tests, or runtime behavior affected.
Commit Reference
5da6491d3- docs: unbloat correction-ops.md