mcscatblog-review-post

# 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

1. Find the PR using `gh pr list` (filter by author if a username was given)
2. Check out the PR branch: `gh pr checkout <number>`
3. Identify the new or modified post file in `_posts/`

## Step 2: Start Local Dev Server

1. Run `./tools/run.sh` in the background
2. Wait for the server to be ready at `http://127.0.0.1:4000/mcscatblog/`
3. 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

### 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
- 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

1. Commit all changes with a descriptive message listing what was fixed
2. Push to the PR branch
3. 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

1. Merge the PR with `gh pr merge --squash --delete-branch`
2. Wait ~90 seconds for GitHub Actions to run
3. Check the build status with `gh run list --limit 3`
4. If the build fails, investigate immediately

## Step 7: Verify Production

1. Fetch the production page using WebFetch at `https://microsoft.github.io/mcscatblog/posts/<slug>/`
2. Confirm the page loads with correct title, author, date, images, and code blocks
3. Report the live URL to the user