From 7f43295edcd39245f555e9d9ab8f9b42917b02dc Mon Sep 17 00:00:00 2001 From: Kitty Chiu <42864823+KittyChiu@users.noreply.github.com> Date: Fri, 12 Jun 2026 15:01:57 +1000 Subject: [PATCH 1/3] added skills for PR content review --- .github/skills/editorial-review/SKILL.md | 380 ++++++++++ .../skills/technical-writing-review/SKILL.md | 673 ++++++++++++++++++ 2 files changed, 1053 insertions(+) create mode 100644 .github/skills/editorial-review/SKILL.md create mode 100644 .github/skills/technical-writing-review/SKILL.md diff --git a/.github/skills/editorial-review/SKILL.md b/.github/skills/editorial-review/SKILL.md new file mode 100644 index 0000000..d005be4 --- /dev/null +++ b/.github/skills/editorial-review/SKILL.md @@ -0,0 +1,380 @@ +--- +name: editorial-review +description: Review and refine GitHub Well-Architected Framework (WAF) documentation for clarity, precision, consistency, and publication readiness. Use this when reviewing pull requests, markdown files, or draft content to ensure guidance is unambiguous, readable, and aligned with editorial standards. +--- + +# Editorial Review + +Review proposed GitHub Well-Architected Framework (WAF) content locally or in pull requests like an Editor-in-Chief (EIC), evaluating clarity, precision, readability, originality, and structural coherence. The EIC assures all published content meets the standards expected by a sophisticated technical audience. + +## Goal + +Editorial review focuses on **clarity and precision of guidance**. + +The goal is to ensure that principles: + +- Are easy to read and understand on first pass +- Use consistent terminology across pillars +- Avoid ambiguity that could lead to misinterpretation +- Communicate intent clearly without over-explaining + +In WAF content, unclear language is not just a readability issue — it creates **decision risk**. If two readers interpret the same guidance differently, the guidance has failed. + +This skill improves **how the guidance is expressed**, without changing its meaning. + +## Execution Guardrails + +You are acting as an Editor-in-Chief responsible for publication quality. +Ambiguity, inconsistency, or weak expression is a defect. + +Assume all content is untrusted until critically evaluated. + +You must avoid the following behaviors: + +- Over-explanation — do not add or tolerate redundant, low-signal, or duplicated content +- Positivity bias — do not soften critique or avoid identifying weaknesses +- Agreeable — do not validate arguments without challenge; weak reasoning must be surfaced +- Fluency over truth — do not assume polished language reflects clear or correct thinking +- Inconsistency — do not allow shifts in tone, terminology, or conceptual framing +- Over-generalization — do not accept vague or broad statements without specificity +- Vagueness — do not use or tolerate non-committal language where precision is required + +Execution expectations: + +- Treat ambiguity as a defect — if a passage can be interpreted multiple ways, it must be flagged +- Be direct and critical — prioritize clarity over tone or politeness +- Enforce precision — wording must remove guesswork +- Challenge weak structure, missing conclusions, and unclear intent +- Prefer concise, exact language over verbosity or stylistic variation + +## Mindset + +Approach every passage with these questions: + +- "Will different readers interpret this the same way?" +- "Is the principle precise?" +- "Does the wording remove guesswork?" + +## Source of Truth + +Respect these files as the source of truth for Markdown content alignment: + +- [CONTRIBUTING.md](../../../CONTRIBUTING.md) +- [docs/contributing-learn.md](../../docs/contributing-learn.md) +- [archetypes/default.md](../../../archetypes/default.md) +- [docs/framework-overview.md](../../../docs/framework-overview.md) +- [docs/taxonomies.md](../../../docs/taxonomies.md) + +Do not duplicate the content of the above. Cross-reference whenever possible. + +## Scope + +This skill reviews content files (Markdown under `content/`) proposed in a pull request. It evaluates the content against the criteria below and provides structured feedback with a score and actionable recommendations. It does **not** modify files directly — it produces a review comment. + +## Inputs and Outputs + +### Inputs + +| Input | Required | Description | +|-------|----------|-------------| +| Pull request diff or local files | Yes | The changed content files in the PR or local files being reviewed | +| Source of truth files | Yes | CONTRIBUTING.md, archetypes/default.md, docs/framework-overview.md, docs/taxonomies.md | + +### Outputs + +| Output | Description | +|--------|-------------| +| Structured review comment | Evaluation against each dimension with scores, findings, and recommendations | + +## Evaluation Criteria + +| Dimension | What the EIC Evaluates | Key Questions | +|---|---|---| +| Content Quality | Clarity, structure, argument, terminology | Is it coherent, unambiguous, and readable on first pass? | +| Precision & Sourcing | Fact-checking, citations, terminology correctness | Are claims sourced, terms used consistently, and language precise? | +| Audience Relevance | Value, level, engagement | Does it inform the audience at the right depth? | +| Originality | Insight, perspective | Does it add knowledge not available elsewhere in the WAF? | +| Visual/Structural Coherence | Diagrams, layout, readability | Do visuals and structure enhance comprehension? | + +## Procedure + +Follow these steps in order when reviewing a content PR or local content files: + +### Step 1 — Identify content changes + +Examine the diff (if review runs in pull request) or local content files to identify new or modified content files under `content/`. Focus the review on substantive content changes — skip trivial formatting-only edits. + +### Step 2 — Load source of truth context + +If not already done, read and internalize: + +1. `CONTRIBUTING.md` — for submission guidelines, writing style, and structural expectations +2. `archetypes/default.md` — for required front matter fields and article structure +3. `docs/framework-overview.md` — for WAF mission, vision, and identity +4. `docs/taxonomies.md` — for valid taxonomy values and their purpose + +### Step 3 — Evaluate Content Quality (Structure, Clarity, Argument) + +Content must demonstrate **rigorous thinking, strong structure, and editorial clarity**. + +Evaluate: + +**Argument & structure** — Does the piece hold together as a coherent whole? + +- Logical flow of ideas (clear thesis → evidence → conclusion) +- Strength of argument or narrative arc +- No "waffle" or filler — every paragraph earns its place +- Clear takeaways for the reader at each section's end +- Content alignment across sections — sibling sections cover comparable depth and scope, don't contradict each other, and each section delivers on what its heading promises +- No duplication — content should not restate what already exists within the same article or elsewhere in the WAF; cross-reference where it reduces duplication without fragmenting the narrative + +**Clarity & expression** — Is each passage as clear and concise as it can be? + +- Conceptual intent (why) is separated from implementation detail (how) — not interleaved +- Explanations are layered: goals → actual behavior → takeaway +- Repetition is purposeful — the same control, concept, or term appears once per context, not scattered redundantly +- Verbose passages are compressed without losing meaning (two sentences saying the same thing → one precise statement) +- Sentences are short enough to parse in one pass; compound sentences carrying unrelated points are split +- Terminology is consistent — the same concept uses the same term throughout; synonyms that create ambiguity are flagged +- Tone is direct and confident — use active voice ("Configure branch protection to…") not passive ("Branch protection should be configured…"); the WAF speaks as a knowledgeable advisor, not a detached observer + +When recommending changes, **respect the author's structure and key ideas** — suggest refinements, not redesigns. + +Flag issues such as: + +- Disjointed sections lacking logical transitions +- Vague claims without supporting evidence +- Redundant or circular statements +- Missing or weak conclusions — every section needs a clear "so what" +- Inconsistent terminology that forces readers to re-map concepts +- Cross-references that use bare numbers, symbols, or generic labels (e.g. "see [1]", "link") instead of semantic anchor text (e.g. heading titles or descriptive phrases) + +**Voice & style** — Does the writing follow WAF conventions? + +- Headings use **sentence case** (capitalize only first word and proper nouns) +- Voice is **active and prescriptive** — direct imperatives ("Implement…"), not passive hedging ("It is recommended that…") +- Language is **specific and concrete** — no vague placeholders + + ```yaml + ❌ "Configure appropriate settings" + ✅ "Set required approvals to 2 for teams with more than 10 developers" + + ❌ "Use security features" + ✅ "Enable secret scanning, Dependabot alerts, and code scanning for all repositories" + ``` + +- Unnecessary qualifiers are removed — statements are direct and confident + + ```yaml + ❌ "You might want to consider possibly implementing..." + ✅ "Implement..." + + ❌ "In most cases, it's generally a good idea to..." + ✅ "Use... because..." + ``` + +- Tone is professional and inclusive + +### Step 4 — Evaluate Precision & Sourcing + +Precision in WAF content is **editorial, not just technical**. Imprecise language creates ambiguity; unsourced claims erode trust. + +Evaluate: + +- Terminology is **used consistently** — the same concept uses the same term throughout; no unexplained synonyms +- Claims are **fact-checked and sourced** with links to approved sources +- Data, statistics, and product names are **current and correctly stated** +- GitHub product references align with current documentation +- Language is **precise** — qualifiers like "should", "might", "can" are used intentionally, not as hedging +- Sources are limited to **primary sources**: + - [GitHub Docs](https://docs.github.com/) + - [GitHub Blog](https://github.blog/) + - [GitHub Support](https://support.github.com/) +- **Trusted external sources** (e.g. NIST, OWASP, CNCF, IEEE) are acceptable when the claim requires industry-standard backing that GitHub sources alone cannot provide. Flag external sources that are obscure, outdated, or promotional + +Flag issues such as: + +- Unverified claims presented as fact +- Inconsistent terminology (e.g. switching between "ruleset" and "rule set") +- Hedged language that weakens precision without adding nuance +- Missing citations for non-obvious assertions +- Outdated product names or feature references + +### Step 5 — Evaluate Audience Relevance & Engagement + +Ensure the content delivers **intellectual value** to its audience. The WAF audience spans the personas defined in `docs/taxonomies.md` — primarily **administrators and developers** making platform decisions, but also project managers, sales engineers, and end-users seeking best practices. Content should target decision-makers by default unless the article's front matter indicates a narrower persona. + +Evaluate: + +- Whether the content helps readers **understand a complex issue better** +- Whether it provides **practical, strategic, or conceptual insight** +- Whether the level is appropriate for the target personas (not too basic, not overly obscure) + +Flag issues such as: + +- Content that is too introductory for the expected audience +- Missing practical guidance or actionable recommendations +- Overly academic content without real-world application + +### Step 6 — Evaluate Originality + +Originality in WAF is about being **insightful and opinionated**, not just novel. Do not flag whether content duplicates GitHub Docs at a substance level. + +Evaluate: + +- Unique analysis or point of view that goes beyond restating known facts +- First-hand expertise or insight from practitioners +- Perspectives that aren't available elsewhere in the WAF + +Flag issues such as: + +- Lack of opinionated guidance (the WAF is intentionally prescriptive) +- Missing "so what" — the reason this content matters +- Content that reads as a summary of existing WAF articles without adding new insight + +### Step 7 — Evaluate Visual & Structural Coherence + +In WAF, visuals serve **functional clarity**, not just aesthetics. + +Evaluate: + +- Diagrams, charts, or code snippets **clarify the content** rather than decorate it +- Layout is structured for **readability and comprehension** +- Visuals are **accurate and not misleading** +- Article follows the structure defined in `archetypes/default.md` + +Flag issues such as: + +- Missing diagrams where visual explanation would significantly aid understanding +- Misleading or overly complex visuals +- Walls of text that could be broken into scannable sections +- Tables that have more than 5 rows or 3 columns without a compelling reason +- Nesting of lists more than 2 levels deep, which can be hard to follow +- Too much bold or italic text that distracts rather than emphasizes +- Too many callout boxes that fragment the narrative flow +- Structural deviations from the archetype without justification +- Heavy use of external links with no consolidated "Related Links" section +- "Related Links" section that mixes external links and GitHub documentation links without separating them into subsections + +### Step 8 — Validate Front Matter & Taxonomy Alignment + +Using `archetypes/default.md` as structural authority. Consult `docs/taxonomies.md` for taxonomy values. + +Evaluate: + +- All required front matter fields are present +- Taxonomy values are valid and appropriate for the content +- `publishDate` is set and `draft` status is intentional +- Author information is complete (both `name` and `handle`) + +Flag issues such as: + +- Missing or incomplete front matter fields +- Invalid taxonomy values not listed in `docs/taxonomies.md` +- Missing `publishDate` or unintentional `draft` status +- Incomplete author attribution + +### Step 9 — Produce the Review + +Compose a structured review comment with the following format: + +```markdown +## 📰 WAF Editorial Review + +### Summary + +**Verdict:** + + + +### Scores + +| Dimension | Score (1-5) | Summary | +|---|---|---| +| Content Quality | X | ... | +| Precision & Sourcing | X | ... | +| Audience Relevance | X | ... | +| Originality | X | ... | +| Visual/Structural Coherence | X | ... | +| **Overall** | **X** | ... | + +### Detailed Findings + +#### Content Quality + + +#### Precision & Sourcing + + +#### Audience Relevance + + +#### Originality + + +#### Visual/Structural Coherence + + +### Recommendations + + +``` + +## Scoring Guide + +| Score | Label | Description | +|---|---|---| +| 5 | Exceptional | Exceeds expectations; publishable as-is | +| 4 | Strong | Minor polish needed; fundamentally sound | +| 3 | Adequate | Meets minimum bar but has notable gaps | +| 2 | Below expectations | Significant issues requiring revision | +| 1 | Insufficient | Fundamental problems; major rework needed | + +The overall score is **not** a simple average — weight Precision & Sourcing and Audience Relevance more heavily than other dimensions. + +### Calibration Examples + +The following illustrates how to frame findings at different score levels. + +#### Content Quality + +| Score | Example Finding | +|---|---| +| 4 (Strong) | "The article is well-structured with a clear takeaway and logical progression. The 'Governance' section could use a stronger concluding takeaway — currently it ends on an implementation detail rather than a strategic design." | +| 3 (Adequate, heavy) | "The content covers the topic but reads heavy and verbose — long compound sentences, repeated references to the same controls (e.g. branch protection mentioned in four separate sections), and paragraphs that mix conceptual rationale with implementation steps. Compressing overlapping passages and separating 'why' from 'how' would improve readability." | +| 3 (Adequate, implementation-heavy) | "The article explains how to configure branch protection rules and required status checks but never articulates what security outcome these controls achieve or why they matter at an architectural level. Readers get a runbook without the reasoning — adding a framing paragraph that states the design goal each control serves would elevate from transactional to strategic." | +| 2 (Below expectations, misaligned) | "Sections vary significantly in depth — 'Access Controls' has three detailed subsections while 'Audit Logging' is a single paragraph. The heading 'Automated Compliance' promises policy-as-code guidance but the section discusses manual review workflows instead. Several passages repeat the same guidance about branch protection in different words." | + +#### Precision & Sourcing + +| Score | Example Finding | +|---|---| +| 4 (Strong) | "Terminology is consistent throughout — 'repository ruleset' is used uniformly. One claim about default branch protection behavior lacks a citation; adding a link to the GitHub Docs page would close the gap." | +| 3 (Adequate) | "The article switches between 'ruleset', 'rule set', and 'branch rule' when referring to the same feature. Two statistics about Dependabot adoption are stated without sources. GitHub Advanced Security is referenced by its former name in one paragraph." | +| 2 (Below expectations) | "Multiple unsourced claims are presented as fact — e.g. 'most enterprises see a 40% reduction in vulnerabilities' with no citation. The article links to a third-party blog post instead of GitHub Docs for a core product feature. 'Code scanning' and 'CodeQL scanning' are used interchangeably without clarifying the relationship." | + +#### Audience Relevance + +| Score | Example Finding | +|---|---| +| 4 (Strong) | "The article targets administrators making governance decisions and maintains that level throughout. The section on audit log forwarding could briefly acknowledge the developer experience impact to round out the perspective." | +| 3 (Adequate) | "The article oscillates between administrator-level strategy and step-by-step UI instructions. The 'Getting Started' section reads like onboarding documentation rather than architectural guidance — readers at this level already know how to navigate repository settings." | +| 2 (Below expectations) | "The content reads like a product feature overview rather than architectural guidance. It explains what Copilot does but never addresses when to adopt it, how to evaluate readiness, or what trade-offs to consider — leaving decision-makers without actionable insight." | + +## Verdict Thresholds + +- **✅ Ready to Go** — Overall score ≥ 4 and no individual dimension below 3 +- **🔄 Revisions Recommended** — Overall score 3, or any single dimension at 2 +- **❌ Major Rework Needed** — Overall score ≤ 2, or any single dimension at 1 + +## Guardrails + +- Do **NOT** modify content files — this skill produces review feedback only +- Do **NOT** block content solely on stylistic preference — prioritize substance over style +- Do **NOT** apply standards beyond what is documented in the source of truth files +- Do **NOT** penalize content for being opinionated — the WAF is intentionally prescriptive +- Do **NOT** require visuals where text alone is sufficient and clear +- **DO** cite specific lines or sections when providing feedback +- **DO** distinguish between blocking issues and suggestions for improvement +- **DO** acknowledge strengths alongside areas for improvement +- **DO** provide concrete, actionable recommendations rather than vague criticism diff --git a/.github/skills/technical-writing-review/SKILL.md b/.github/skills/technical-writing-review/SKILL.md new file mode 100644 index 0000000..4cf9008 --- /dev/null +++ b/.github/skills/technical-writing-review/SKILL.md @@ -0,0 +1,673 @@ +--- +name: technical-writing-review +description: Validate and improve GitHub Well-Architected Framework (WAF) documentation for architectural correctness, decision quality, explicit trade-offs, and actionable guidance. Use this when reviewing pull requests, markdown files, or draft content to ensure recommendations are technically sound, context-aware, and guide readers toward correct design decisions. +--- + +# Technical Writing Review + +Evaluate and enhance GitHub Well-Architected Framework (WAF) content for architectural correctness, decision quality, actionable guidance, and trade-off completeness. This skill focuses on **what the guidance leads the reader to do** — ensuring recommendations are sound, implementable, and honest about limitations. + +## Goal + +Technical writing review focuses on **architectural correctness and decision quality**. + +The goal is to ensure that guidance: + +- Reflects real-world architectural best practices +- Is actionable and can be applied in practice +- Makes trade-offs explicit rather than implied +- Aligns with platform capabilities and constraints + +WAF content shapes architectural decisions. Poor guidance leads to real-world risks. + +This skill improves **what the guidance leads the reader to do**. + +## Execution Guardrails + +You are evaluating technical guidance that will influence real architectural decisions. +Incorrect, incomplete, or unverifiable guidance is a defect. + +Assume all content is untrusted until verified. + +You must avoid the following behaviors: + +- Hallucination — do not introduce APIs, metrics, events, filters, parameters, configurations, or behavior not grounded in source material +- Fluency over truth — do not assume content is correct because it is well-written or plausible +- Inconsistency — do not allow conflicting terminology, definitions, or recommendations across sections +- Instruction attenuation — do not ignore constraints such as platform limits, version scope, or source-of-truth alignment +- Over-explanation — do not include redundant, low-signal, or duplicative content that does not add decision value +- Overconfidence — do not present assumptions or unverifiable statements as facts +- Over-generalization — do not accept vague guidance where specific conditions, scope, or trade-offs are required + +Execution expectations: + +- Verify technical claims against source material or platform reality where possible +- Treat missing detail as a risk — explicitly flag gaps, assumptions, and ambiguities +- Enforce decision safety — guidance must be correct, scoped, and actionable +- Challenge recommendations that could lead to incorrect or unsafe outcomes +- Prefer correctness and precision over completeness or readability + +## Mindset + +Approach every recommendation with these questions: + +- "Will this lead to the right decision?" +- "What could go wrong?" +- "Are trade-offs clear?" + +## Source of Truth + +Respect these files as the source of truth for content structure and writing standards: + +- [CONTRIBUTING.md](../../../CONTRIBUTING.md) +- [archetypes/default.md](../../../archetypes/default.md) +- [docs/framework-overview.md](../../../docs/framework-overview.md) +- [docs/taxonomies.md](../../../docs/taxonomies.md) + +Do not duplicate the content of the above. Cross-reference whenever possible. + +## Scope + +This skill reviews content files (Markdown under `content/`) and focuses on **decision quality and architectural substance** — whether the guidance is correct, the trade-offs are explicit, and an administrator can confidently act on it. It answers: **"Will this guidance lead to the right decision?"** + +**Output mode:** By default, this skill produces an enhancement report (structured review comment). When the caller explicitly requests edits (e.g., "improve this article" or "fix the trade-offs section"), apply changes directly to the content files instead. Do not mix modes — either produce a report or edit files, not both. + +## Inputs and Outputs + +### Inputs + +| Input | Required | Description | +|-------|----------|-------------| +| Content files | Yes | The Markdown content files to review and enhance | +| Source of truth files | Yes | CONTRIBUTING.md, archetypes/default.md, docs/framework-overview.md, docs/taxonomies.md | + +### Outputs + +| Output | When | Description | +|--------|------|-------------| +| Enhancement report | Default | Diagnosis of writing issues, specific recommendations, and before/after examples | +| File edits | Caller requests changes | Direct improvements to content files | + +## Evaluation Criteria + +| Dimension | What the Reviewer Evaluates | Key Questions | +|---|---|---| +| Architectural Correctness | Platform alignment, configuration accuracy, scoping | Is the guidance technically sound for real-world implementation? | +| Decision Quality | Recommendations, reasoning, alternatives | Will this lead the reader to the right decision? | +| Trade-off Completeness | Benefits, drawbacks, conditions, exceptions | Are trade-offs explicit rather than implied? | +| Actionability | Implementation detail, specificity, prerequisites | Can an administrator act on this without guesswork? | +| Design Thinking | Reasoning, constraints, architectural principles, decision frameworks | Does the article teach readers how to think about the problem, not just what to do? | +| Section Substance | Depth and quality per section | Does each section meet the quality bar for its role? | + +## Procedure + +Follow these steps in order when reviewing content for technical writing quality: + +### Step 1 — Load source of truth context + +Before reviewing content, read and internalize these files to establish the quality baseline: + +1. `CONTRIBUTING.md` — submission guidelines, writing style, and structural expectations +2. `archetypes/default.md` — required front matter fields and article structure +3. `docs/framework-overview.md` — WAF mission, vision, and identity +4. `docs/taxonomies.md` — valid taxonomy values and their purpose + +Do not proceed to diagnosis without loading these files first. + +### Step 2 — Diagnose content substance issues + +Read the full article and classify it against these common problem patterns. An article may exhibit more than one. For each pattern found, assess the **decision risk** — what could go wrong if a reader follows this guidance as written? + +#### Pattern A: Too generic or descriptive + +**Indicators:** + +- Lists multiple options without recommending one +- Describes what features do without prescribing when/how to use them +- Doesn't explain decision-making rationale +- Missing scoping conditions (e.g., org size, team structure, platform) +- Content that merely restates official documentation + +**Enhancement approach:** + +1. Add a clear recommendation — choose the best approach and explicitly recommend it +2. Explain the reasoning — why is this the recommended approach? +3. Provide specifics — add configuration examples, CLI commands, API calls +4. Address alternatives — briefly mention other approaches and why they're not recommended (or when they might be) + +**Example transformation — Branch protection:** + +```yaml +❌ BEFORE: 'Organizations can use branch protection rules or repository rulesets to enforce code review requirements.' + +✅ AFTER: 'For organizations with 50+ repositories, use repository rulesets instead of branch protection rules. Rulesets provide centralized management and consistent enforcement across multiple repositories with significantly less administrative overhead. While branch protection rules offer more repository-specific flexibility, the maintenance burden becomes prohibitive at scale.' +``` + +**Example transformation — Secret scanning:** + +```yaml +❌ BEFORE: "Enable secret scanning to detect exposed credentials in repositories." + +✅ AFTER: "Enable secret scanning and push protection at the organization level to prevent secrets from being committed. Unlike secret scanning alerts (which detect secrets after they're committed), push protection blocks commits containing secrets in real-time, reducing the exposure window from hours/days to zero. + +Recommended Organization configuration: +- Enable push protection by default for all repositories +- Allow bypass with justification (audit trail maintained) + +Trade-off: push protection for custom patterns may be more prone to false positives. Teams need clear guidance on when bypass is appropriate (e.g., test fixtures with dummy secrets, which should use environment variables instead)." +``` + +**Example transformation — GitHub Actions workflow security:** + +````yaml +❌ BEFORE: "Use GITHUB_TOKEN for authentication in workflows." + +✅ AFTER: "Configure GITHUB_TOKEN permissions using the principle of least privilege. In your workflow file or organization settings, explicitly define minimum required permissions rather than using default read/write access. + +Best practice configuration: +```yaml +permissions: + contents: read # Read repository contents + pull-requests: write # Comment on PRs + issues: write # Create issues +``` + +For organizations running 100+ workflows monthly: Set organization default to `permissions: read-all` and require workflows to explicitly request write permissions. This prevents over-privileged workflows and reduces attack surface if a workflow is compromised. + +Trade-off: Workflows fail if permissions are insufficient. Initial migration may require 2-4 weeks to identify and update all workflows, but significantly reduces security risk." +```` + +#### Pattern B: Lacking technical depth + +**Indicators:** + +- High-level concepts without implementation details +- Missing configuration examples or code snippets +- Vague instructions like "configure the settings" +- Insufficient detail for someone to actually implement + +**Enhancement approach:** + +1. Add step-by-step guidance — specific UI paths, API endpoints, or CLI commands +2. Include configuration examples — YAML, JSON, or code snippets with actual values +3. Provide context — when to use each setting, what values are appropriate +4. Add implementation notes — common pitfalls, troubleshooting tips + +#### Pattern C: Missing trade-off analysis + +**Indicators:** + +- Presents one solution as universally best +- Doesn't discuss alternatives or their contexts +- Missing "when not to use this approach" guidance +- No discussion of pros/cons + +**Enhancement approach:** + +1. Identify alternatives — what other approaches exist? +2. Compare approaches — create a clear comparison with pros/cons +3. Define contexts — when is each approach appropriate? +4. Address edge cases — when should readers NOT use the recommended approach? + +**Example structure to add:** + +```markdown +## Trade-offs and alternatives + +### Recommended approach: [Approach name] + +**When to use:** + +- [Specific context/scenario] +- [Organization size/type] +- [Technical requirement] + +**Benefits:** + +- [Specific benefit with quantification if possible] +- [Another benefit] + +**Drawbacks:** + +- [Specific limitation or cost] +- [Another limitation] + +### Alternative: [Alternative approach name] + +**When to use:** + +- [Different context where this makes sense] + +**Why not recommended for most cases:** + +- [Specific reason] +- [Another reason] + +**Exception:** Consider this approach if [specific condition]. +``` + +#### Pattern D: Duplicating GitHub Docs + +**Indicators:** + +- Focuses heavily on implementation mechanics +- Reads like a how-to guide or tutorial +- Doesn't add design thinking or decision guidance +- Could be replaced by linking to GitHub Docs + +**Enhancement approach:** + +1. Shift to design thinking — focus on WHY and WHEN, not detailed HOW +2. Add decision framework — help readers decide which approach to use +3. Emphasize trade-offs — what are the consequences of different choices? +4. Link to docs — reference GitHub Docs for implementation details +5. Add value — field experiences, lessons learned, common mistakes + +**Example transformation — Team topology:** + +````yaml +❌ BEFORE: "Use CODEOWNERS to assign reviewers automatically." + +✅ AFTER: "Design CODEOWNERS files based on your team's ownership model and review capacity constraints. + +**Recommended approach for most organizations** (platform teams supporting product teams): + +```text +## CODEOWNERS +## Platform team owns infrastructure +/infrastructure/ @org/platform-team +/.github/workflows/ @org/platform-team @org/security-team +/terraform/ @org/platform-team + +## Product teams own their domains +/services/auth/ @org/auth-team +/services/payments/ @org/payments-team + +## Security team required for security-critical paths +/src/authentication/ @org/security-team +``` + +**Key design decisions:** + +1. **Joint ownership for critical paths** (`@org/platform-team @org/security-team`): Both teams must approve changes to CI/CD, increasing review time by 1-2 days but preventing production incidents +2. **Granular paths over wildcards**: `/services/auth/` instead of `/services/*` gives teams clear ownership boundaries +3. **2-4 people per team in CODEOWNERS**: Avoids single points of failure while preventing diffusion of responsibility + +**Alternative for federated organizations**: Define CODEOWNERS at repository level rather than centralized files. Trades consistency for team autonomy. Use when product teams operate independently with minimal shared infrastructure. + +**Trade-off**: CODEOWNERS creates mandatory reviews, increasing PR merge time. For high-velocity environments, consider `CODEOWNERS` as documentation only (without required reviews) and rely on automated team mentions instead." +```` + +--- + +### Step 3 — Review each section for substance quality + +Evaluate each section's **substance** — whether the content is architecturally sound, actionable, and honest about trade-offs. Focus on whether each section delivers the depth and quality its role demands. + +#### 3.1 Front matter (taxonomy accuracy) + +Verify that taxonomy values accurately reflect the article's **technical scope**. Do not review formatting, field completeness, or structural compliance — those are editorial concerns. + +**Check:** + +- **Pillars**: Does the article truly deliver guidance for the selected pillars? +- **Platform**: Does the guidance apply to GHEC, GHES, or hybrid as tagged? Are platform-specific constraints addressed? +- **Features/Components**: Are the tagged features actually covered in the article's recommendations? +- **Personas**: Does the depth match the tagged audience (e.g., admin-level guidance tagged for admins)? + +#### 3.2 Scenario overview + +**What it should accomplish:** + +- State the problem or use case clearly +- Explain business/technical impact (why this matters) +- Provide context about when/where this applies +- Preview the recommended approach + +**Quality bar:** + +- First paragraph: Clear problem statement +- Second paragraph: Business value and impact +- Third paragraph: Context and applicability +- Fourth paragraph (optional): Brief preview of recommendation + +**Common issues:** Too vague or generic, missing business value explanation, no context about when this applies, starts with solution instead of problem. + +#### 3.3 Key design strategies + +**What it should include:** + +- 3-5 fundamental design principles for this solution +- Each principle explained in 2-3 sentences +- Connection to framework pillars +- Technical specificity, not just concepts + +**Quality bar:** + +- Strategies are specific, not generic platitudes +- Each strategy has clear reasoning +- Technical considerations are included +- Connects to broader architecture/design + +**Example enhancement:** + +```yaml +❌ BEFORE: 'Use automation to improve efficiency' + +✅ AFTER: '**Automate approval workflows for low-risk changes**: Implement GitHub Actions workflows that automatically approve and merge dependabot updates for patch versions after CI passes. This reduces manual review burden by 60-80% for typical teams while maintaining security through automated checks.' +``` + +#### 3.4 Checklist + +**What it should include:** + +- Actionable items (start with verbs) +- Specific enough to verify completion +- Ordered logically (often sequential) +- Technical details where needed + +**Example enhancement:** + +```yaml +❌ BEFORE: +- Branch protection +- Code review +- Status checks + +✅ AFTER: +- ✅ Enable branch protection on `main` and all `release/*` branches +- ✅ Require at least 1 pull request approval before merging +- ✅ Configure required status checks: `build`, `test`, `security-scan` +- ✅ Enable "Require conversation resolution before merging" +- ✅ Restrict push access to repository administrators only +- ✅ Document the approval process in CONTRIBUTING.md +``` + +#### 3.5 Recommended deployment + +**What it should include:** + +- Step-by-step technical guidance +- Specific UI paths OR API calls OR CLI commands +- Configuration examples (YAML/JSON/code) +- Implementation notes and tips + +Include enough implementation detail to act on the recommendation, but link to GitHub Docs for full procedural walkthroughs. + +**Quality bar:** + +- Includes specific technical instructions +- Provides configuration examples with actual values +- Addresses common implementation challenges +- Links to relevant GitHub Docs for details +- Suitable for a newer admin to follow and implement + +**Example enhancement:** + +```yaml +❌ BEFORE: "Configure repository rulesets to enforce your policies." + +✅ AFTER: "Create an organization-level ruleset to enforce policies across all repositories: + +1. Navigate to Organization Settings > Rules > Rulesets > New ruleset +2. Select 'New branch ruleset' +3. Configure basic settings: + - Name: `default-branch-protection` + - Enforcement status: Active + - Bypass list: Add organization owners only + +4. Set target criteria: + - Target: All repositories + - Include: `default` branch + +5. Configure protection rules: + - ✅ Restrict deletions + - ✅ Require a pull request before merging (2 approvals) + - ✅ Require status checks to pass (add: `ci`, `security-scan`) + - ✅ Block force pushes + +6. Click 'Create' + +**Implementation note**: Start with a subset of critical repositories before applying organization-wide. Test with a pilot team for 2 weeks to identify issues. + +See [GitHub Docs: Rulesets](https://docs.github.com/enterprise-cloud@latest/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets) for additional configuration options." +``` + +#### 3.6 Trade-offs section + +**What it should include:** + +- Clear recommendation with reasoning +- Benefits of recommended approach +- Drawbacks or limitations +- Alternative approaches with context +- When NOT to use the recommendation + +**Quality bar:** + +- States the recommendation explicitly +- Explains WHY it's recommended (not just WHAT) +- Discusses specific benefits with quantification if possible +- Acknowledges limitations honestly +- Presents alternatives fairly with context +- Defines when alternatives might be better + +**Example structure:** + +```markdown +## Additional solution detail and trade-offs to consider + +### Why we recommend repository rulesets over branch protection rules + +For organizations managing 50+ repositories, repository rulesets provide superior administrative efficiency and consistency compared to branch protection rules. + +**Key benefits:** + +- **Centralized management**: Apply policies across hundreds of repositories with one ruleset instead of configuring each individually +- **Reduced drift**: Eliminate configuration inconsistencies that occur when using repository-level settings +- **Better visibility**: Organization admins can audit all protection rules from a single location +- **Faster onboarding**: New repositories automatically inherit protection policies + +**Trade-offs to consider:** + +- **Less flexibility**: Cannot customize rules per repository without creating additional rulesets +- **GHEC requirement**: Only available on GitHub Enterprise Cloud (not GHES) +- **Migration effort**: Requires planning to migrate from existing branch protection rules +- **Learning curve**: Teams accustomed to branch protection rules need to adjust + +### When to use branch protection rules instead + +Use repository-level branch protection rules if: + +- You have fewer than 50 repositories +- You need significant per-repository customization +- You're on GitHub Enterprise Server (where rulesets aren't available) +- Your repositories have fundamentally different protection requirements + +### Hybrid approach + +Some organizations use both: + +- **Rulesets** for baseline organizational policies (e.g., "all production branches require 1 approval") +- **Branch protection rules** for repository-specific additions (e.g., "this critical repo requires 3 approvals") + +**Note**: Branch protection rules can add restrictions beyond rulesets but cannot relax them. +``` + +--- + +### Step 4 — Validate architectural correctness and decision quality + +This is the core of the technical writing review. For each recommendation in the article, evaluate whether it will lead the reader to the **right decision**. + +#### 4.1 Architectural correctness + +Verify that guidance reflects real-world best practices: + +- Recommendations align with **current platform capabilities** — not deprecated features or unavailable options +- Configuration examples are **correct and complete** — a reader can implement them without guesswork +- Scope and scale are appropriate — guidance specifies what organization sizes, repository counts, or team structures it applies to +- Dependencies and prerequisites are **explicitly stated** — not assumed + +Flag issues such as: + +- Guidance that works in theory but fails in common production scenarios +- Missing prerequisites that would cause implementation to fail +- Recommendations that don't account for platform-specific constraints (GHEC vs. GHES vs. hybrid) +- Overgeneralized best practices presented without scoping conditions + +#### 4.2 Decision quality + +Verify that guidance helps readers make informed choices: + +- Each recommendation explains **why** it is the recommended approach, not just what to do +- Alternatives are presented **with context** for when they are more appropriate +- Trade-offs are **explicit** — benefits, drawbacks, and conditions are stated, not implied +- Guidance distinguishes between **strong recommendations** (do this) and **conditional recommendations** (do this if X) + +Flag issues such as: + +- Recommendations without reasoning ("Enable X" with no explanation of why) +- Missing trade-off analysis — presenting one approach as universally correct +- Absent or incomplete "when not to use this" guidance +- Misleading confidence — stating something as a best practice without acknowledging limitations + +#### 4.3 Actionability + +Verify that guidance can be implemented in practice: + +- Steps are **specific enough to follow** — UI paths, API endpoints, CLI commands, or configuration examples +- Implementation guidance includes **realistic values**, not just placeholders +- Common pitfalls and failure modes are addressed +- Guidance links to GitHub Docs for detailed mechanics rather than duplicating them + +Flag issues such as: + +- Vague instructions ("configure the settings", "follow best practices") +- Missing implementation details that force the reader to research elsewhere +- Guidance that reads as a tutorial or how-to instead of architectural recommendation + +#### 4.4 Design thinking + +The WAF exists to add design thinking on top of GitHub Docs. Verify that the article doesn't just tell readers **what to do**, but equips them to **reason about architectural choices**. + +Verify: + +- The article explains the **constraints, goals, and trade-offs** that shape the recommendation — not just the recommendation itself +- Readers can adapt the guidance to their context because the **reasoning is visible**, not hidden behind a prescriptive answer +- The article connects specific recommendations to **broader architectural principles** (scalability, security posture, team autonomy, operational overhead) +- Decision frameworks or evaluation criteria are provided where readers face a **choice between valid approaches** + +Flag issues such as: + +- Prescriptive guidance with no visible reasoning ("Do X" without explaining what problem X solves or what constraints make X the right choice) +- Missing connection between recommendations and architectural outcomes +- Content that is correct and actionable but doesn't teach the reader *how to think about the problem* — only how to execute a solution + +--- + +### Step 5 — Verify against quality checklists + +Before finalizing, verify the article against these framework-specific quality bars: + +#### Framework alignment + +- [ ] **Mission alignment**: Provides opinionated, community-driven guidance +- [ ] **Not duplicating docs**: Focuses on design thinking, not just implementation +- [ ] **Design principles**: Connects to framework pillars +- [ ] **Field experience**: Incorporates lessons learned and real-world insights +- [ ] **Decision support**: Helps readers make informed choices + +#### Architectural correctness + +- [ ] **Platform-aware**: Guidance accounts for GHEC, GHES, and hybrid constraints +- [ ] **Technically sound**: Configuration examples are correct and complete +- [ ] **Scoped**: Recommendations specify when they apply (org size, team structure, maturity) +- [ ] **Current**: References align with current GitHub product capabilities + +#### Decision quality + +- [ ] **Opinionated**: Makes clear recommendations with reasoning +- [ ] **Trade-offs explicit**: Discusses benefits, drawbacks, and alternatives +- [ ] **Actionable**: Administrators can implement based on this guidance +- [ ] **Failure-aware**: Addresses what could go wrong and when not to use the approach + +#### Section completeness + +- [ ] Front matter: Complete and accurate taxonomies +- [ ] Scenario overview: Problem, impact, context +- [ ] Design strategies: Specific and concrete +- [ ] Checklist: Actionable, ordered, specific +- [ ] Assumptions: Explicitly stated +- [ ] Recommended deployment: Step-by-step, technical, detailed +- [ ] Trade-offs: Compares approaches, honest about limitations +- [ ] Related links: Relevant and current + +--- + +### Step 6 — Produce the review + +Compose a structured enhancement report: + +```markdown +## ✏️ WAF Technical Writing Review + +### Summary + + + +### Diagnosis + +**Patterns identified:** + +### Section-by-section findings + +#### Front matter + + +#### Scenario overview + + +#### Key design strategies + + +#### Checklist + + +#### Recommended deployment + + +#### Trade-offs + + +### Architectural correctness and decision quality + + + +### Quality checklist results + +| Dimension | Status | Notes | +|------|--------|-------| +| Architectural correctness | ✅ / ⚠️ / ❌ | ... | +| Decision quality | ✅ / ⚠️ / ❌ | ... | +| Trade-off completeness | ✅ / ⚠️ / ❌ | ... | +| Actionability | ✅ / ⚠️ / ❌ | ... | +| Design thinking | ✅ / ⚠️ / ❌ | ... | +| Section substance | ✅ / ⚠️ / ❌ | ... | + +### Priority recommendations + + +``` + +## Guardrails + +- **Maintain author intent** — improve substance while preserving the core message +- **Be constructive** — provide concrete alternatives for every issue flagged +- **Be opinionated** — transform options into recommendations; the WAF is intentionally prescriptive +- **Emphasize trade-offs** — always discuss alternatives and their contexts +- **Focus on decision quality** — ensure guidance leads to the right architectural decision +- **Flag risk** — identify what could go wrong if a reader follows the guidance as written +- **Link to docs, don't duplicate** — reference GitHub Docs for implementation mechanics; add design thinking +- **Respect the archetype** — content must follow the structure in `archetypes/default.md` +- **Do NOT evaluate editorial dimensions** (clarity scores, readability, terminology precision, audience relevance) — those are out of scope for this skill From 0571f2bd09c466247547a9ec60b201d05fcf2c33 Mon Sep 17 00:00:00 2001 From: Kitty Chiu <42864823+KittyChiu@users.noreply.github.com> Date: Fri, 12 Jun 2026 15:05:51 +1000 Subject: [PATCH 2/3] updated trigger path --- .github/skills/editorial-review/SKILL.md | 2 +- .github/skills/technical-writing-review/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/skills/editorial-review/SKILL.md b/.github/skills/editorial-review/SKILL.md index d005be4..4086eca 100644 --- a/.github/skills/editorial-review/SKILL.md +++ b/.github/skills/editorial-review/SKILL.md @@ -1,6 +1,6 @@ --- name: editorial-review -description: Review and refine GitHub Well-Architected Framework (WAF) documentation for clarity, precision, consistency, and publication readiness. Use this when reviewing pull requests, markdown files, or draft content to ensure guidance is unambiguous, readable, and aligned with editorial standards. +description: Review and refine GitHub Well-Architected Framework (WAF) documentation under the content/ folder for clarity, precision, consistency, and publication readiness. Use this when reviewing pull requests, markdown files, or draft content in content/ to ensure guidance is unambiguous, readable, and aligned with editorial standards. --- # Editorial Review diff --git a/.github/skills/technical-writing-review/SKILL.md b/.github/skills/technical-writing-review/SKILL.md index 4cf9008..b7eb437 100644 --- a/.github/skills/technical-writing-review/SKILL.md +++ b/.github/skills/technical-writing-review/SKILL.md @@ -1,6 +1,6 @@ --- name: technical-writing-review -description: Validate and improve GitHub Well-Architected Framework (WAF) documentation for architectural correctness, decision quality, explicit trade-offs, and actionable guidance. Use this when reviewing pull requests, markdown files, or draft content to ensure recommendations are technically sound, context-aware, and guide readers toward correct design decisions. +description: Validate and improve GitHub Well-Architected Framework (WAF) documentation under the content/ folder for architectural correctness, decision quality, explicit trade-offs, and actionable guidance. Use this when reviewing pull requests, markdown files, or draft content in content/ to ensure recommendations are technically sound, context-aware, and guide readers toward correct architecture and design decisions. --- # Technical Writing Review From 361523020a4baa8b8a286b6dc43f7b85680b7ee9 Mon Sep 17 00:00:00 2001 From: Kitty Chiu <42864823+KittyChiu@users.noreply.github.com> Date: Fri, 12 Jun 2026 15:13:43 +1000 Subject: [PATCH 3/3] Added PR template --- .github/pull_request_template.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..0fa4fd6 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,32 @@ + + +### What changed + + + +### Why + + + + +### Type of change + + + +- [ ] Content Library article +- [ ] Website code change +- [ ] Documentation update +- [ ] Other: + +### Contributors checklist + + + +- [ ] For Content Library changes: file name, directory, front matter, and writing style are appropriate +- [ ] For website code changes: code standards, tests, dependencies, logging/debugging, and LICENSE impact were considered +- [ ] For documentation updates: content is clear, accurate, consistent, and proofread +- [ ] Related issue, discussion, or Content Request is linked, if applicable + +### Notes for reviewers + +