[docs] docs: unbloat SpecOps pattern page#23204
Conversation
Remove 32 lines of redundant content: merged the "Use SpecOps when" list into the intro, condensed the 5-step overview, collapsed repeated "Specification Structure" bullets into prose, converted the semver list to a table, combined the MCP Gateway example into one sentence, and removed the "References" section (links already appear inline). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
github-actions
bot
added
automation
documentation
There was a problem hiding this comment.
Pull request overview
Reduces and streamlines the SpecOps pattern documentation to remove redundancy while keeping the overall page structure intact.
Changes:
- Condenses the introduction and “How SpecOps Works” section for brevity.
- Removes duplicative explanatory sentences/sections and consolidates “Specification Structure” into inline prose.
- Reformats the semantic versioning guidance from bullets into a compact table and trims the MCP Gateway example section.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - Maintain formal technical specifications | ||
| - Keep specifications synchronized across multiple repositories | ||
| - Ensure implementations stay compliant with specification updates | ||
| SpecOps is a pattern for maintaining formal specifications using agentic workflows. It leverages the [`w3c-specification-writer` agent](https://github.com/github/gh-aw/blob/main/.github/agents/w3c-specification-writer.agent.md) to create W3C-style specifications with RFC 2119 keywords (MUST, SHALL, SHOULD, MAY) and automatically propagates changes to consuming implementations across repositories. |
There was a problem hiding this comment.
The PR description says the removed “References” section was duplicative because all three links were already present inline, but this page no longer links to RFC 2119 anywhere (only mentions “RFC 2119 keywords”). Consider adding a single inline link to RFC 2119 on first mention (or keeping a minimal references block) so readers can navigate to the normative definition.
| ## Specification Structure | ||
|
|
||
| W3C-style specifications follow a formal structure: | ||
| W3C-style specifications require: Abstract, Status, Introduction, Conformance, numbered technical sections with RFC 2119 keywords, Compliance testing, References, and a Change log. |
There was a problem hiding this comment.
Inconsistent capitalization for the section name: earlier the doc refers to a “Change Log” section, but here it says “Change log”. Consider standardizing the casing (e.g., “Change Log”) to match the rest of the page.
Removes ~19% of content from
docs/src/content/docs/patterns/spec-ops.md(173 → 141 lines, 48 deletions / 15 insertions).What was removed
Screenshot
References: