By name: reviewing-agent-ready-prs description: Use when reviewing a PR in camunda/camunda that touches AGENTS.md, skills under .claude/skills/, the way the project uses ADRs, or the way the project uses architecture docs (not new ADRs or architecture docs themselves) — i.e., Agent-Ready initiative PRs
Reviewing Agent-Ready PRs
Overview
Cross-team initiative in camunda/camunda where contributors review each other's PRs about how we work with agents. The value is pattern consistency across these meta-PRs — spotting when PR #5 contradicts what was agreed in PR #2.
Core principle: check alignment against the shared design doc and prior decisions before raising anything. Don't unilaterally judge — raise inconsistencies to the user.
When to Use
In camunda/camunda, when a PR touches:
AGENTS.md(root or scoped)- Any file under
.claude/skills/(skill definitions) - The way ADRs are used — process, templates, conventions — but not new ADRs themselves
- The way architecture docs are used — but not new architecture docs themselves
- A proposal about Agent-Ready ways-of-working
Out of scope: new ADRs, new architecture docs, ordinary feature/bugfix PRs.
If you're unsure whether a PR is in scope, ask the user before reviewing (see step 1).
Workflow
Follow these steps in order. Do not skip ahead.
- Confirm scope with the user. Say: "This looks like an Agent-Ready PR — should I review it under that workflow?" Do not assume. Do not start reviewing yet. Wait for confirmation.
- Record the PR in
data/agent-ready-prs.mdunder Reviewed PRs (PR number, link, date, one-line scope). - Check the shared design doc for alignment: https://docs.google.com/document/d/1cUB363AJquRixECWDu1-1eBjrXOdUxidniYuOIg2qaQ/ — you may need WebFetch or to ask the user to summarize the relevant section if access fails.
- If something seems out of alignment, check
data/agent-ready-prs.md→ Decisions for a prior call that explains it. - If still unresolved, search the comments and review comments of prior Agent-Ready PRs listed in the tracker. Use
curl+ the GitHub REST API (ghfails under the proxy on macOS; the user's global instructions document this). - Raise inconsistencies to the user. Frame as
❓per the repo review emoji code. Do not silently resolve. Do not pre-decide. Don't post the review until the user has weighed in on the inconsistency. - Record any decision the user makes during the review back into
data/agent-ready-prs.md→ Decisions (dated, linked to the triggering PR).
The standard camunda/camunda review style still applies on top of this — emoji code (👍/❓/❌/🔧/💭), general-comment template, inline-comment style, nit budget. Those live in the user's project memory and are complementary, not replaced by this skill.
Red Flags — STOP
If you catch yourself thinking any of these, you're about to violate the workflow:
| Rationalization | Reality |
|---|---|
| "This is obviously fine, I'll just review it" | Step 1 first. The scope check is the point. |
| "Diff is small, I can skip the Google Doc" | Step 3 is mandatory regardless of size. |
"I'll flag this inconsistency directly as a ❌" |
Steps 4–5 first. It might already be decided. |
| "I'll just decide this one myself, it's minor" | Never. Raise to the user. The whole point is consistency. |
| "I'll record the PR later" | Record at the time. Later is never. |
| "User didn't ask me to follow the workflow this time" | The trigger is the PR scope, not the user's framing. |
Quick Reference
- Tracker file:
data/agent-ready-prs.md(inside this skill directory) - Source-of-truth design doc: https://docs.google.com/document/d/1cUB363AJquRixECWDu1-1eBjrXOdUxidniYuOIg2qaQ/
- First action on every Agent-Ready PR: ask the user to confirm scope.
- Default disposition on any apparent inconsistency: raise as
❓to the user, never resolve unilaterally.
Common Mistakes
| Mistake | Fix |
|---|---|
| Diving into a code review without confirming scope | Step 1: confirm with user first |
| Skipping the Google Doc check because the PR is small | Always check, regardless of size |
| Unilaterally judging that something is inconsistent | Check tracker decisions first, then raise to user |
| Posting the review before the user resolves an inconsistency | Block on user input for any ❓ you'd raise |
| Forgetting to record the PR or the decision | Record both at the time of review |
| Treating this as a replacement for code-review style | This workflow runs alongside the standard review style |