pr

What this skill does

## Agent & Tool Reference

| Agent | Subagent Type | When Used |
|-------|--------------|-----------|
| Code Review Dispatcher | `pr:code-review-dispatcher` | Phase 2.5 — plans fan-out |
| Code Reviewer | `pr:code-reviewer` | Phase 3 — parallel quality review |
| Security Reviewer | `pr:security-reviewer` | Phase 3 — if security-relevant files |
| UI/UX Reviewer | `pr:uiux-reviewer` | Phase 3 — if frontend files |
| Code Simplifier | `code-simplifier:code-simplifier` | Step 8 — simplification pass |

**Important:** Always use the exact `subagent_type` values from this table. If an agent type is unavailable at runtime, report the error to the user — do not substitute alternative names or skills.

## Full PR Workflow

Execute all steps sequentially. Stop and report on failure unless noted otherwise.

### Step 1: Branch Confirmation

1. Run `git branch --show-current` to identify the current branch.
2. Ask the user which branch to target as base (default: `main`).
3. If on `main`, prompt to create/switch to a feature branch — never PR main→main.

### Step 2: Pre-flight Check

1. Run `git status` (never `-uall`) to assess working tree state.
2. If zero changes AND no unpushed commits (`git log <base>..HEAD` is empty) → abort, inform user "nothing to submit".
3. If only unpushed commits exist (no uncommitted changes) → skip to Step 4.

### Step 3: Commit All Changes

1. Run `git status` to enumerate modified, deleted, and untracked files.
2. Exclude sensitive files (`.env*`, `credentials*`, `*.key`, `*.pem`, secrets). Warn user if any are found.
3. Stage files explicitly by name: `git add file1 file2 ...` — **never** `git add .` or `-A`.
4. Check `git log --oneline -5` for commit message style.
5. Create a conventional commit (`feat:`, `fix:`, `chore:`) using HEREDOC format.
6. Include `Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>`.

### Step 4: Quality Gates (best-effort fixes)

Run sequentially. For each gate: run check → on failure, analyze errors and attempt fix → re-run → if fixed, stage and commit (`fix: resolve <gate> errors`) → after max attempts, stop and report.

| Gate | Command | Max Fix Attempts | Condition |
|------|---------|-----------------|-----------|
| Typecheck | `bun run typecheck` | 2 | Always |
| Build | `bun run build` | 2 | Always |
| Lint | `bun run lint` | 2 | Always |
| Cargo check | `cd apps/cli && cargo check` | 1 | Only if `apps/cli/` has changes |

After all gates, if any still failing:
- Report remaining failures clearly with error output.
- Ask user: "Proceed despite failures, or abort?"

> **Note on worktrees**: Quality gates may fail in worktrees due to missing `node_modules` or generated files (Prisma client). If all errors are in files unrelated to the diff and trace back to missing dependencies, report this clearly and proceed — these are environment gaps, not regressions introduced by the PR.

### Step 5: Push & Create PR

1. Push: `git push -u origin <branch-name>`.
2. Analyze all commits since base: `git log <base>..HEAD` and `git diff <base>...HEAD`.
3. Generate PR title: under 70 chars, conventional commit prefix.
4. Create PR with `gh pr create` using HEREDOC body containing all sections below.
5. Share the PR URL with user.

**PR body template** (populate from actual diff analysis):

```markdown
## Summary
- (2-4 bullets: what changed and why)

## Root Cause / Motivation
(Why this work was needed)

## What Changed
| File | Change |
|------|--------|
| `path/file` | Brief explanation |

## Design Decisions
(Non-obvious choices and rejected alternatives — omit section if none)

## Testing
- [ ] Typecheck: PASS/FAIL
- [ ] Build: PASS/FAIL
- [ ] Lint: PASS/FAIL
- [ ] Cargo check: PASS/FAIL/N/A

## QA Checklist
(Generated in Step 6)

<details>
<summary>Implementation Plan</summary>
(Attach if a plan exists in current session, otherwise omit)
</details>
```

### Step 6: Manual QA Checklist

Generate QA items based on the **actual diff**, not a generic template. Use markdown checkboxes. Include in the PR body under `## QA Checklist`.

| Changed area | QA items to generate |
|-------------|---------------------|
| Webapp pages/components | "Navigate to [page], verify [behavior], check responsive layout" |
| API routes | "Call [endpoint] with [payload], verify response shape" |
| CLI (`apps/cli/`) | "Run `ck [command]`, verify output" + note: **CLI release needed after merge** |
| DB migrations | "Run `bun run db:migrate` locally, verify schema in Prisma Studio" |
| Extension | "Load unpacked extension, test on [specific site]" |
| UI/styling | "Visual check Chrome + Safari, dark/light mode" |
| Cross-component | Add integration verification steps between affected components |

### Step 7: PR Environment Seeding

After PR creation, check if the repo has Railway PR deploy environments configured.

1. Check for `[environments.pr.deploy]` in `railway.toml`. If absent → skip this step.
2. Review the diff to determine what seed data would help a QA tester verify the changes. Consider:
   - New DB models/fields → seed rows that exercise them
   - New UI pages/features → seed data that makes the page non-empty
   - New API endpoints → seed entities the endpoints will operate on
3. Check existing seed scripts in `apps/webapp/prisma/seed*.ts` and `package.json` (`db:seed*` scripts).
4. If an existing seed script covers the need → add a note in the PR body under `## PR Environment` with the command to run (e.g., `bun run db:seed-gifting`).
5. If no existing script fits and the changes warrant test data:
   - Create or update a seed script in `apps/webapp/prisma/` targeting the changed models.
   - Add a `db:seed-<name>` script to `apps/webapp/package.json` if new.
   - Stage, commit (`chore: add seed data for PR environment`), and push.
6. Add a `## PR Environment` section to the PR body:

```markdown
## PR Environment
Once the PR environment deploys, run:
\`\`\`bash
DATABASE_URL=<pr-env-db-url> bun run db:seed-<name>
\`\`\`
Test data created: (describe what entities/records are seeded and why)
```

7. If the changes are purely cosmetic, config-only, or don't touch data models → skip seeding and note "No seed data needed" in the PR body.

### Step 8: Launch Code Simplifier

After PR creation succeeds, launch in background:

```
Agent tool (run_in_background: true):
  subagent_type: "code-simplifier:code-simplifier"
  prompt: "Review and simplify the code changes on the current branch.
    Run git diff <base-branch>...HEAD to identify changed files.
    Apply simplifications that improve clarity and maintainability
    without changing behavior. If improvements are made, commit with
    message 'refactor: code simplification pass' including
    Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>,
    then git push."
```

Inform user: "Code-simplifier is running in background — any improvements will appear as additional commits on the PR."

### Step 9: CandleKeep Code Review + Fix All Findings

After the code-simplifier is launched, run a structured code review using CandleKeep's specialized review agents, then **fix ALL findings**.

#### Phase 1: Verify CandleKeep Availability (synchronous)

1. Check that CandleKeep CLI is installed and authenticated:
   ```bash
   ck auth whoami
   ```
2. If the command fails (not found, not authenticated, or errors) → skip the code review (Phases 2–6) and inform the user:
   > "CandleKeep CLI is not available or not authenticated. Skipping book-guided code review. Run `ck auth login` to enable it."
3. If successful → proceed to Phase 2. The review agents reference specific book IDs and will access them directly.

#### Phase 2: Prepare Diff & Select Adjunct Agents

1. Run `git diff <base-branch>...HEAD > /tmp/pr-review-diff.txt` and `git diff <base-branch>...HEAD --name-only > /tmp/pr-review-files.txt`.
2. Read `/tmp/pr-review-files.txt` and decide which adjunct (non-code-quality) agents to launch:
   - **If** files match `api/*, route.*, middleware/*