diff --git a/workshop/14b-pr-reviewer-workflow.md b/workshop/14b-pr-reviewer-workflow.md index 0c3480ab..22f46cd4 100644 --- a/workshop/14b-pr-reviewer-workflow.md +++ b/workshop/14b-pr-reviewer-workflow.md @@ -30,6 +30,14 @@ The parent workflow should coordinate the run, not contain every review rule. It | `pr-reviewer` agent | Read the diff and return prioritized, evidence-backed findings | | `pr-review-standards` skill | Define what counts as a useful finding and how to format it | +The diagram below shows how the three parts connect at runtime. + + + + + PR reviewer agent and skill split: a pull request event triggers the parent brief, which calls the pr-reviewer agent; the agent applies the pr-review-standards skill, returns findings to the parent, and the parent submits a safe-output review + + The agent can change how it investigates a pull request without changing the stable standards in the skill. You can also improve the skill without making the parent brief longer. The same split makes it straightforward to extend the reviewer to apply labels based on which files changed (see [Pattern: Auto-Label PRs by Content](side-quest-13-01-pr-labeler-pattern.md)) or to post a structured summary that doubles as a release note draft (see [Pattern: Generate a PR Summary Comment](side-quest-13-02-pr-summary-pattern.md)). > :thinking: **Predict:** Which instruction belongs in the skill: “review pull request 42” or “cite a changed file and line for every finding”? The first is run-specific orchestration; the second is reusable review guidance. diff --git a/workshop/images/14b-agent-skill-split-dark.svg b/workshop/images/14b-agent-skill-split-dark.svg new file mode 100644 index 00000000..729bcb15 --- /dev/null +++ b/workshop/images/14b-agent-skill-split-dark.svg @@ -0,0 +1,127 @@ + + + + + + + + + + + + + + + + + + + PR Reviewer: Agent and Skill Split + Each layer has one responsibility — coordinate, investigate, or define quality + + + + + + + + + + PR Event + ready_for_review + or /review + slash command + + + + + + + + + + + + Parent Brief + Identifies the PR + Calls pr-reviewer + Submits result + + + orchestrates + + + + + calls + + + + inline agent + + + + + + + + pr-reviewer agent + Reads the diff + Applies review skill + + + investigates + + + + + applies + + + + + + + pr-review-standards skill + Defines quality criteria + Cite file + line for every finding + + + + + findings + + + + + + + Safe Output + submit-pull-request- + review + + + max: 1 · controlled write + + + + + + + + + + + Review + posted + + + + 1 — Coordinate + 2 — Investigate (reusable) + 3 — Controlled Write + + + Update the skill to change review quality. Update the agent to change how it investigates. Update the parent to change orchestration. + Each layer changes independently without breaking the others. + diff --git a/workshop/images/14b-agent-skill-split-light.svg b/workshop/images/14b-agent-skill-split-light.svg new file mode 100644 index 00000000..1cde3d97 --- /dev/null +++ b/workshop/images/14b-agent-skill-split-light.svg @@ -0,0 +1,127 @@ + + + + + + + + + + + + + + + + + + + PR Reviewer: Agent and Skill Split + Each layer has one responsibility — coordinate, investigate, or define quality + + + + + + + + + PR Event + ready_for_review + or /review + slash command + + + + + + + + + + + Parent Brief + Identifies the PR + Calls pr-reviewer + Submits result + + + orchestrates + + + + + calls + + + + inline agent + + + + + + + pr-reviewer agent + Reads the diff + Applies review skill + + + investigates + + + + + applies + + + + + + + pr-review-standards skill + Defines quality criteria + Cite file + line for every finding + + + + + findings + + + + + + + Safe Output + submit-pull-request- + review + + + max: 1 · controlled write + + + + + + + + + + + Review + posted + + + + + 1 — Coordinate + + 2 — Investigate (reusable) + + 3 — Controlled Write + + + Update the skill to change review quality. Update the agent to change how it investigates. Update the parent to change orchestration. + Each layer changes independently without breaking the others. +