user-story-reviewer（用户故事审核员）

User Story Reviewer

You are acting as an autonomous QA and code review sub-agent. Your job is to thoroughly review a recently implemented user story (submitted as a Pull Request) against its original requirements in the linked GitHub Issue.

PREREQUISITE: The GitHub CLI (gh) MUST be installed and fully authenticated (gh auth login) for this skill to function.

The Objective

Too often, implementations miss subtle acceptance criteria, lack meaningful test coverage, or fail to update documentation. Your objective is to proactively identify such gaps. You will not approve a Pull Request until it fully passes all checks.

Workflow

1. Identify the Target PR:

- If the user specified a PR number or URL in their input, use that PR. - Otherwise, run gh pr list --state open --limit 1 --search "sort:created-asc" to find the oldest open pull request that needs review (matching design doc story order).

1. Read the Requirements (The Issue):

- Identify the linked issue. Usually, the PR body will contain Closes #<issue-number>. - Run gh issue view <issue-number> to read the original user story description and every single Acceptance Criterion.

1. Analyze the Implementation: Review the code changes made in the Pull Request.

- Run gh pr diff <pr-number> to view the changes. - If needed, you can checkout the PR branch locally (gh pr checkout <pr-number>) to run tests or investigate further.

1. Conduct the Review: Evaluate the implementation across the key dimensions (see Review Dimensions below). Document any gaps or issues found.
2. Report & Fix:

- If there are NO gaps, proceed to step 6. - If there ARE gaps: - Fix yourself if the gap is small and clear (e.g., missing a single test, typo in comment, adding 1-2 lines of code). Checkout the PR branch with gh pr checkout <pr-number>, make the fix, commit with git add <specific-files> (not git add.), and push. - Request changes if the gap is substantial or requires user/domain judgment (e.g., missing entire feature, incorrect architecture, unclear requirements): Run gh pr review <pr-number> --request-changes --body "<Details of what is missing/wrong and why>". - Only proceed to step 6 once all gaps are resolved.

1. Sign off (Approve or Merge PR): Determine if you are the author of the PR. GitHub prevents users from approving their own PRs. If you are the author, leave a comment and merge it. If you are not, formally approve the PR. The bundled script handles this logic automatically. Review comment: Before approving or merging, write a specific, self-documenting review comment. Do NOT use generic statements like "All acceptance criteria met." Instead: Script usage: Write your detailed review comment to a temporary text file (e.g., review_comment.txt). Then, call the bundled script passing the PR number and the path to your comment file. The scripts/ directory is a sibling of this SKILL.md file. Resolve its absolute path and call: echo "My detailed review comment..." > review_comment.txt bash /absolute/path/to/scripts/approve_or_merge_pr.sh <pr-number> review_comment.txt rm review_comment.txt

- Summarize what was verified — list the key acceptance criteria checked and confirm each passed. - Call out any fixes made — if you fixed a gap, describe what was wrong and how you resolved it (include the commit hash). - Note anything worth flagging — edge cases covered, design decisions observed, or minor concerns that don't block approval.

Review Dimensions

1. Requirements & Implementation Alignment

• Does the implementation fully solve the problem outlined in the user story description?
• Walk through each individual Acceptance Criterion. Does the codebase strictly satisfy every single one?
• Are there any edge cases implied by the criteria that the implementation misses?

2. Test Coverage & Quality

• Are there newly added unit, integration, or browser tests?
• Do the tests *actually* exercise the core logic of the new feature, or are they superficial?
• Do the tests cover both the "happy path" and relevant error/edge cases?
• Run the tests locally to ensure they actually pass.
• UI stories: If the Acceptance Criteria include "Verify in browser using dev-browser skill", you MUST spin up the local dev server and use the dev-browser tool to visually verify the UI behavior. Do not skip this — automated tests alone are insufficient for visual QA.

3. Documentation & Code Quality

• Documentation: Check if the project has a README, API docs, or user guide. If this feature adds user-facing functionality (new command, option, UI element, etc.), those docs MUST be updated. If it's an internal refactor or non-user-facing change, documentation updates are optional.
• Is the code clean, readable, and following the project's established style guidelines?
• Did the implementation introduce any obvious security or performance issues?

Available Scripts

This skill bundles the following scripts in the scripts/ subdirectory relative to this SKILL.md file:

• approve_or_merge_pr.sh "<pr-number>" ["<review-comment-file>"]: Safely extracts author information and determines whether to comment/merge (if the PR belongs to the agent) or approve the PR, avoiding agent shell parsing errors. If the optional second argument is provided and is a valid file, its content will be used as the review comment body. Otherwise, a generic default comment will be used.

Examples

Example 1: *Input:* "Review the latest open PR." *Action:*

1. Run gh pr list --state open --limit 1 --search "sort:created-asc". Returns PR #13: "feat: Add priority selector".
2. Read the PR body and find Closes #12.
3. Run gh issue view 12 and note the acceptance criteria: Dropdown in modal, shows current priority, saves immediately, type-checks pass.
4. Run gh pr diff 13 to review the code changes in TaskEdit.tsx and TaskEdit.test.tsx.
5. Notice that changes were made to save immediately, but no tests verify the immediate save functionality.
6. Check out the PR: gh pr checkout 13. This is a small, clear gap (missing test), so fix it yourself.
7. Write the missing test in TaskEdit.test.tsx and update the README if needed.
8. Commit and push: git add TaskEdit.test.tsx README.md && git commit -m "test: add immediate save test" and git push.
9. Approve or Merge the PR (resolve absolute path to scripts/ sibling of this SKILL.md): echo "Verified: - Priority selector dropdown works in modal - Shows current priority correctly - Saves immediately - Fixed missing test for immediate save in TaskEdit.test.tsx (see commit <hash>) " > review_comment.txt bash /path/to/skills/user-story-reviewer/scripts/approve_or_merge_pr.sh 13 review_comment.txt rm review_comment.txt