| name | mcscatblog-review-post |
| description | End-to-end review, fix, publish, and verify a blog post PR from another author |
Review and Publish a Blog Post PR
You are reviewing and publishing a blog post PR for the Microsoft Copilot Studio CAT team blog.
The argument is either a PR number, a branch name, or an author's GitHub username. If not provided, ask.
Step 1: Pull the PR Branch
- Find the PR using
gh pr list (filter by author if a username was given)
- Check out the PR branch:
gh pr checkout <number>
- Identify the new or modified post file in
_posts/
Step 2: Start Local Dev Server
- Run
./tools/run.sh in the background
- Wait for the server to be ready at
http://127.0.0.1:4000/mcscatblog/
- Open the post in the browser so the user can see it
Step 3: Review the Post
Read the review instructions at .github/instructions/posts.instructions.md. Review the post against priorities 1-5 defined there.
Read as a Reader First
Before checking anything technical, read the post top to bottom as a reader would. Ask yourself:
- Do I understand the problem being solved by the end of the intro?
- At any point, did I feel lost, bored, or overwhelmed?
- Could I follow the instructions and get a working result?
- Were there sections I wanted to skip?
Narrative and Structure (highest impact)
- Does the intro state the problem clearly before showing the solution?
- Progressive disclosure: does the post build from basic to advanced, or dump everything at once?
- Does every section earn its place? Flag tangential sections for removal.
- No redundant content (same concept in two tables, glossary restating callouts, etc.)
- Flag posts over 5,000 words or posts that try to cover too many things shallowly.
Technical Accuracy
- Flag authoritative-sounding claims that aren't linked to documentation.
- Verify technical claims if possible (e.g., if the post says "the API returns fragments," test it).
- All code examples should be complete and working.
- YAML/JSON blocks over 20 lines should be in collapsible
<details> sections (use <pre><code> inside, not markdown fences).
- Links to MS docs for every product feature or configuration step.
- 2-3 internal links using
post_url to related blog posts.
Front Matter and Images
- Filename date matches front matter date
- Required: title, date, categories (lowercase, max 2), tags (lowercase, 5-8), description, author (matches
_data/authors.yml), image with alt text
- All referenced images exist in
assets/posts/ and have alt text + italic caption
- Screenshots appear after their explanation, not before
- Tall/narrow images (height > 2x width) need resizing to ~300px width
- No manual "Further Reading" section (Chirpy auto-generates from tags)
- Callouts use Chirpy prompt boxes, not emoji
- Tags maximize Chirpy "Further Reading" overlap with existing posts
Naming and Terminology (canonical)
Copilot Studio is one product. It offers three harnesses (build experiences), not three separate products. Flag any framing that treats a harness as its own product. Prose should lead with "Copilot Studio" and introduce a harness name only when precision requires it.
Flag and correct non-canonical harness names to these canonical ones:
| Canonical harness | What it is | Reject these terms |
|---|
| Copilot Chat harness | Customize Microsoft 365 Copilot with your organization's knowledge. | "Chat agent", "DA", "classic/old Copilot Studio" |
| Standard harness | Rule-based conversational agents with predefined topics and flows. | "Basic orchestration", "Advanced", "Samba", "classic/old Copilot Studio" |
| GitHub Copilot harness | Optimize your business processes with an agentic build experience. | "New Copilot Studio", "Dracarys" |
Additional checks:
- Harnesses are build choices, not separate products.
- Use the term "harness" consistently; avoid alternates such as "orchestrator".
- Avoid scale labels such as Basic, Advanced, Premium, or Ultimate; they don't scale as new harnesses are added.
- Context note (keep any cost/licensing phrasing factual and brief): as of 8/3, Copilot Studio supports building agents with a new GitHub Copilot harness (GA); agents built with it are billed on a usage basis and are not eligible for inclusion in Microsoft 365 Copilot licensing.
Front-matter agent_edition taxonomy (established by PR #352, "Retire classic/modern edition naming"). This field drives the under-title pill rendered in _layouts/post.html and validated by _plugins/validate-agent-edition.rb. Canonical values and what they render:
standard → "Standard harness" pillgithub-copilot → "GHCP harness" pillboth → "Both harnesses" pill
Deprecated aliases classic → standard and modern → github-copilot are still accepted but should be migrated. Review check: every post sets a valid agent_edition, and posts using classic/modern should be updated to the canonical value.
Output the Review
- List the top 5-7 issues ranked by impact.
- For each: quote the text, explain the problem, suggest a fix.
- Do NOT score 14 categories or provide percentage scores.
- State: ready to publish, needs minor fixes, or needs structural revision.
Step 4: Apply Fixes
After presenting the review, ask the user which fixes to apply. Common fixes include:
- Restructuring sections for progressive disclosure
- Adding MS docs links and internal post links
- Cutting tangential sections
- Making YAML blocks collapsible
- Grammar, spelling, terminology corrections
- Correcting Copilot Studio product/harness terminology to canonical names (see Naming and Terminology)
- Front matter corrections (dates, tags, categories)
- Image resizing (use Python PIL)
- Replacing emoji callouts with Chirpy prompt boxes
Apply only the fixes the user approves.
Step 5: Commit, Push, and Comment
- Commit all changes with a descriptive message listing what was fixed
- Push to the PR branch
- Add a PR comment summarizing all changes made, organized by category, so the original author can see what was changed and why
Step 6: Merge
- Merge the PR with
gh pr merge --squash --delete-branch
- Wait ~90 seconds for GitHub Actions to run
- Check the build status with
gh run list --limit 3
- If the build fails, investigate immediately
Step 7: Verify Production
- Fetch the production page using WebFetch at
https://microsoft.github.io/mcscatblog/posts/<slug>/
- Confirm the page loads with correct title, author, date, images, and code blocks
- Report the live URL to the user
