| name | theydo-review | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| description | TheyDo Review: quick, high-signal PR and self-review for the TheyDo monorepo. Use when reviewing a GitHub pull request, a Linear ticket's linked PR, or uncommitted changes on a feature branch. Prefers approval over nitpicking, stages findings in the reviewer's voice, and never publishes a GitHub review without explicit consent. | ||||||||
| triggers |
|
Review TheyDo pull requests and local branch changes. Optimized for a bounded first pass: correctness and risk over style. Use a fuller interactive pass only when the change is broad, high-risk, or the reviewer asks for depth.
| Mode | Inputs | Output |
|---|---|---|
pr |
Pull request number or URL, or Linear issue with a linked open PR | GitHub pending review (body and optional inline comments) |
self |
Current feature branch with uncommitted or unpushed work | Internal findings for the implementer (no GitHub publish) |
Default to pr when a PR number or URL is given. Use self only when the reviewer explicitly asks to review local work, or when no PR exists yet and the active branch has meaningful changes against the default branch.
- Establish repository context. Identify the TheyDo monorepo checkout and default base branch (typically
master). All file reads and diffs must target that checkout. - Resolve the target.
- Pull request: Fetch metadata via GitHub (title, body, state, head/base refs, author, labels, timestamps, URL) and the full diff against the base branch.
- Linear issue: Fetch the issue via Linear; locate linked open pull requests. If several open PRs exist, ask the reviewer to pick one.
- Self mode: Diff the active branch against
origin/master(or the repo default).
- Fetch referenced resources. Follow links in the PR body, issue description, and comments:
- Slack – thread or message context
- Notion – linked pages or meeting notes
- Linear – related issues
- GitHub – other PRs or issues cited in text
- Do a quick review first. Focus on meaningful correctness, scope, safety, testing, and rollout risk. Do not invent style comments or speculative refactors.
- Draft outward text in the reviewer's voice. Review bodies and inline comments should read as if written by the human reviewer, not as generic bot prose.
- Stage a pending GitHub review; do not submit it. In
prmode, use GitHub's pending-review flow so the reviewer can edit before anything is public. Never publish unless the reviewer explicitly asks to post.
Prefer approval over nitpicking:
- If the PR looks sound, stage an approval-style review with a short note.
- Small preferences belong in a private note to the reviewer, not as public GitHub comments.
- Inline comments only for: wrong behavior, unclear requirements, missing tests on risky behavior, security/permission mistakes, rollout hazards, or maintainability problems that will be costly soon.
- Skip "while we're here" suggestions, naming/style tweaks, formatting nits, and extra abstraction unless they materially reduce risk.
- Keep the pass bounded. Escalate to a deeper interactive review when risk is high, the PR is large, or the reviewer requests it.
Use GitHub's "start a review" / pending review feature for pr mode:
- Draft the review body and any inline comments in the reviewer's voice.
- Create a pending pull request review via the GitHub API: include
body,commit_id, and inlinecomments; omit theeventfield so nothing publishes yet. - Record the returned pending
review_id. - Tell the reviewer the review is pending and not visible to others yet.
- Stop. Only after explicit consent, submit the pending review with the chosen event:
APPROVE,COMMENT, orREQUEST_CHANGES.
Do not create a review with event set during staging — that publishes immediately.
Prioritize correctness and shipped behavior over style:
- Requirements alignment with the PR description, Linear ticket, and linked context.
- Behavior under edge cases, retries, failures, permissions, and stale data.
- Architecture and ADR fit, especially DDD/CQRS boundaries and generated GraphQL artifacts.
- Tests that cover behavior rather than implementation details.
- Type safety, backwards compatibility, migrations, observability, and security.
- Performance risks: N+1 queries, missing dataloaders, slow sync paths.
Lead with findings ordered by severity. If there are no meaningful findings, say so clearly and prefer a quick approval. Mention residual risk or test gaps only when relevant.
When another workflow delegates a PR review:
- Expect a brief handoff (scope, focus areas, PR number, repository path).
- Stay in the designated repository checkout for that PR.
- Treat handoff focus as scope guidance, not permission to publish comments.
- Stage output as a GitHub pending review in
prmode, not chat-only bullets, when a publishable review is useful. - Report back only if the handoff or reviewer asks for it.
This workflow expects access to:
| Service | Used for |
|---|---|
| GitHub | PR metadata, diff, comments, pending/submitted reviews (theydo/theydo) |
| Linear | Issue details, linked PRs, acceptance criteria |
| Slack | Thread context linked from tickets or PRs |
| Notion | Specs, meeting notes, RFCs linked from tickets or PRs |
| Repository filesystem | ADRs under adr/, source, and tests in the active checkout |
- Repository checkout and base branch identified
- Target PR, ticket, or self mode resolved
- PR details, diff, existing comments, linked ticket, and referenced resources gathered
- Relevant ADRs and repo patterns checked
- Findings are high-signal, not nitpicks
- Approval staged when there are no meaningful findings
- Outward-facing review text matches the reviewer's voice
- Pending GitHub review created in
prmode when useful - Pending review not submitted without explicit reviewer consent