gastown/internal/formula/formulas/mol-polecat-review-pr.formula.toml

description = """
Review an external PR and decide on merge/reject/revise.

This molecule guides a polecat through reviewing a pull request from an external
contributor. The polecat reviews code quality, tests, and alignment with project
standards, then approves, requests changes, or files followup beads.

## Polecat Contract (Self-Cleaning Model)

You are a self-cleaning worker. You:
1. Receive work via your hook (pinned molecule + PR reference)
2. Work through molecule steps using `bd ready` / `bd close <step>`
3. Complete and self-clean via `gt done` (submit findings + nuke yourself)
4. You are GONE - your review is recorded in beads

**Self-cleaning:** When you run `gt done`, you submit your findings, nuke your
sandbox, and exit. There is no idle state. Done means gone.

**Important:** This formula defines the template. Your molecule already has step
beads created from it. Use `bd ready` to find them - do NOT read this file directly.

**You do NOT:**
- Merge the PR yourself (maintainer or Refinery does that)
- Push to the PR branch (it's external)
- Wait for contributor response (you're done after review)

## Variables

| Variable | Source | Description |
|----------|--------|-------------|
| pr_url | hook_bead | The PR URL to review |
| issue | hook_bead | The tracking issue for this review task |

## Failure Modes

| Situation | Action |
|-----------|--------|
| PR is stale/unmergeable | Note in review, request rebase |
| Tests fail | Note in review, request fixes |
| Major issues found | File followup beads, request changes |
| Unclear requirements | Mail Witness for guidance |"""
formula = "mol-polecat-review-pr"
version = 1

[[steps]]
id = "load-context"
title = "Load context and understand the PR"
description = """
Initialize your session and understand the PR you're reviewing.

**1. Prime your environment:**
```bash
gt prime                    # Load role context
bd prime                    # Load beads context
```

**2. Check your hook:**
```bash
gt hook               # Shows your pinned molecule and hook_bead
```

The hook_bead references the PR to review. Read the tracking issue:
```bash
bd show {{issue}}           # Full issue details including PR URL
```

**3. Fetch the PR:**
```bash
gh pr view {{pr_url}} --json title,body,author,files,commits
gh pr diff {{pr_url}}       # See the actual changes
```

**4. Understand the PR:**
- What is the PR trying to accomplish?
- What files are changed?
- Is there a linked issue?
- Does the PR description explain the "why"?

**5. Check PR status:**
```bash
gh pr checks {{pr_url}}     # CI status
gh pr view {{pr_url}} --json mergeable,reviewDecision
```

**Exit criteria:** You understand the PR's purpose and scope."""

[[steps]]
id = "review-code"
title = "Review the code changes"
needs = ["load-context"]
description = """
Perform a thorough code review of the PR.

**1. Review the diff systematically:**
```bash
gh pr diff {{pr_url}}
```

**2. Check for common issues:**

| Category | Look For |
|----------|----------|
| Correctness | Logic errors, edge cases, null handling |
| Security | Injection, auth bypass, exposed secrets |
| Style | Naming, formatting, consistency with codebase |
| Tests | Are changes tested? Do tests cover edge cases? |
| Docs | Are docs updated if needed? |
| Scope | Does PR stay focused? Any scope creep? |

**3. For each file changed:**
- Does the change make sense?
- Is it consistent with existing patterns?
- Are there any red flags?

**4. Note issues found:**
Keep a running list of:
- Blocking issues (must fix before merge)
- Suggestions (nice to have)
- Questions (need clarification)

**Exit criteria:** You have reviewed all changes and noted issues."""

[[steps]]
id = "check-tests"
title = "Verify tests and CI"
needs = ["review-code"]
description = """
Ensure tests pass and coverage is adequate.

**1. Check CI status:**
```bash
gh pr checks {{pr_url}}
```

All required checks should pass. If not, note which are failing.

**2. Review test changes:**
- Are there new tests for new functionality?
- Do tests cover edge cases?
- Are tests readable and maintainable?

**3. If tests are missing:**
Note this as a blocking issue - new code should have tests.

**4. Check for test-only changes:**
If PR is test-only, ensure tests are meaningful and not just
padding coverage numbers.

**Exit criteria:** You've verified test status and coverage."""

[[steps]]
id = "make-decision"
title = "Decide: approve, request changes, or needs discussion"
needs = ["check-tests"]
description = """
Make your review decision.

**Decision matrix:**

| Situation | Decision |
|-----------|----------|
| Clean code, tests pass, good scope | APPROVE |
| Minor issues, easily fixed | REQUEST_CHANGES (with specific feedback) |
| Major issues, needs rework | REQUEST_CHANGES (with detailed explanation) |
| Unclear requirements or scope | NEEDS_DISCUSSION (mail Witness) |
| Security concern | BLOCK (mail Witness immediately) |

**1. If APPROVE:**
The PR is ready to merge. Note any minor suggestions as comments
but don't block on them.

**2. If REQUEST_CHANGES:**
Be specific about what needs to change. Provide examples if helpful.
The contributor should be able to act on your feedback.

**3. If NEEDS_DISCUSSION:**
```bash
gt mail send {{rig}}/witness -s "PR review needs discussion" -m "PR: {{pr_url}}
Issue: {{issue}}
Question: <what needs clarification>"
```

**4. If BLOCK (security):**
```bash
gt mail send {{rig}}/witness -s "SECURITY: PR blocked" -m "PR: {{pr_url}}
Issue: {{issue}}
Concern: <security issue found>"
```

**Exit criteria:** You've made a clear decision with rationale."""

[[steps]]
id = "submit-review"
title = "Submit the review on GitHub"
needs = ["make-decision"]
description = """
Submit your review via GitHub.

**1. Submit the review:**
```bash
# For APPROVE:
gh pr review {{pr_url}} --approve --body "LGTM. <brief summary of what's good>"

# For REQUEST_CHANGES:
gh pr review {{pr_url}} --request-changes --body "<detailed feedback>"

# For COMMENT (needs discussion):
gh pr review {{pr_url}} --comment --body "<questions or discussion points>"
```

**2. Add inline comments if needed:**
If you have specific line-by-line feedback, add those via GitHub UI
or additional `gh pr comment` calls.

**Exit criteria:** Review submitted on GitHub."""

[[steps]]
id = "file-followups"
title = "File beads for any followup work"
needs = ["submit-review"]
description = """
Create beads for any followup work discovered during review.

**1. For issues found that are outside PR scope:**
```bash
bd create --type=bug --title="Found during PR review: <description>" \
  --description="Discovered while reviewing {{pr_url}}.

  <details of the issue>"
```

**2. For improvements suggested but not required:**
```bash
bd create --type=task --title="Improvement: <description>" \
  --description="Suggested during review of {{pr_url}}.

  <details of the improvement>"
```

**3. Update the tracking issue:**
```bash
bd update {{issue}} --notes "Review complete. Decision: <APPROVE|REQUEST_CHANGES|etc>
Followups filed: <list of bead IDs if any>"
```

**Exit criteria:** All followup work captured as beads."""

[[steps]]
id = "complete-and-exit"
title = "Complete review and self-clean"
needs = ["file-followups"]
description = """
Signal completion and clean up. You cease to exist after this step.

**Self-Cleaning Model:**
Once you run `gt done`, you're gone. The command:
1. Nukes your sandbox
2. Exits your session immediately

**Run gt done:**
```bash
gt done
```

**What happens next (not your concern):**
- Maintainer or Refinery acts on your review
- Contributor responds to feedback
- PR gets merged, revised, or closed

You are NOT involved in any of that. You're gone. Done means gone.

**Exit criteria:** Sandbox nuked, session exited."""

[vars]
[vars.pr_url]
description = "The PR URL to review"
required = true

[vars.issue]
description = "The tracking issue for this review task"
required = true