Compound Pr

---
description: "PR description pipeline — research agents analyze changes, synthesis agents produce a review-ready docs page"
argument-hint: [base-ref] — e.g. main, develop, HEAD~5, abc123..def456
allowed-tools:
  - Bash(git diff:*)
  - Bash(git log:*)
  - Bash(git branch:*)
  - Bash(git checkout:*)
  - Bash(ls:*)
  - Bash(mkdir:*)
  - Bash(wc:*)
  - Bash(rm:*)
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
  - Skill
  - EnterPlanMode
  - ExitPlanMode
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

# PR Describe

Pre-PR pipeline: research agents build context, synthesis agents produce a docs page that doubles as the PR description. Changelog files land as flat files in `docs/changelog/` (tracked in git); ephemeral research artifacts go to `docs/changelog/.research/$BRANCH_SLUG/` (gitignored).

<progress>
- [ ] Step 1: Git analysis + output directory setup
- [ ] Step 1b: Load ADR context
- [ ] Step 2: Research phase — parallel agent spawn (7 agents)
- [ ] Step 3: Fill context gaps (AskUserQuestion)
- [ ] Step 4: Doc staleness check (CLAUDE.md, README.md, ADRs)
- [ ] Step 5: Synthesis phase — PR description + fix plan
- [ ] Step 6: Present PR description and iterate
- [ ] Step 7: Present fix plan — ask user whether to run it
- [ ] Step 8: Cleanup — optionally remove research files
</progress>

<purpose>
Pre-PR pipeline: research agents → synthesis agents → PR description + fix plan. You are the orchestrator — you spawn agents, collect their output, ask the user for context agents can't determine, check for stale docs, synthesize a clean PR description, and produce a separate fix plan from quality findings that the user can choose to run.
</purpose>

<constraints>
**Hard rules:**
- Never create a PR (`gh pr create` is forbidden)
- Never push to remote (`git push` is forbidden)
- Auto-fix build errors via `orc:build-error-resolver` agent, then ask user to review and commit themselves
- Changelog files go to `docs/changelog/` (flat), research files go to `$RESEARCH_DIR` — never scatter files elsewhere
- Git operations are read-only (diff, log, branch) except `git checkout -- <files>` for rollback
</constraints>

<antipatterns>
**Avoid:**
- Generic descriptions ("updated some files") — be specific with paths and line numbers
- Skipping agent spawn — all 7 agents must run (conditional ones check their condition)
- Creating a PR or pushing — this skill produces docs, not PRs
- Rubber-stamping readiness — if agents found blockers, triage and fix before marking READY
- Overselling — write like a sr staff engineer, not a marketer
</antipatterns>

## Input

- **`$ARGUMENTS`** — Optional base ref to diff against (e.g. `main`, `develop`, `HEAD~5`, `abc123..def456`)

**If provided:** use as `$BASE_REF` directly.

**If not provided:** AskUserQuestion:
- "What should I diff against?"
- Options: "main" / "master" / "develop" / Other (enter a ref)

Store the answer as `$BASE_REF`. All subsequent git commands use `$BASE_REF..HEAD`.

## Skip Conditions

Check these before starting. If any is true, report and exit:

1. **Already on default branch:**
   ```bash
   git branch --show-current
   ```
   If current branch equals `$BASE_REF` → "You're on `$BASE_REF`. Switch to a feature branch first."

2. **No commits vs base:**
   ```bash
   git log --oneline $BASE_REF..HEAD
   ```
   If empty → "Nothing to describe — no commits on this branch vs `$BASE_REF`."

3. **Invalid base ref:**
   ```bash
   git rev-parse --verify $BASE_REF
   ```
   If fails → "Ref `$BASE_REF` not found. Check the branch/commit name."

## Process

### Step 1: Git Analysis + Output Directory Setup

Gather branch context:

```bash
git branch --show-current
git log --oneline $BASE_REF..HEAD
git diff --stat $BASE_REF..HEAD
git diff $BASE_REF..HEAD
```

Store these values for agent prompts:
- `$BRANCH` — current branch name
- `$COMMITS` — commit list (oneline)
- `$CHANGED_FILES` — file list from `git diff --stat`
- `$FULL_DIFF` — full diff output
- `$COMMIT_COUNT` — number of commits
- `$FILE_COUNT` — number of changed files

**Diff size guard:** If `git diff --stat $BASE_REF..HEAD` shows more than 100 changed files or `git diff $BASE_REF..HEAD | wc -l` exceeds 5000 lines, warn the user: "Large diff detected ([N] files, [M] lines). Agent context may be truncated. Consider narrowing the base ref or splitting the PR." Continue after acknowledgment — agents will work with what fits.

**Large diff strategy:** For diffs over 2000 lines, pass `$CHANGED_FILES` and `$COMMITS` to agents but NOT `$FULL_DIFF`. Instruct agents to read specific files via `git diff $BASE_REF..HEAD -- <path>` for the files relevant to their analysis.

Derive output paths from branch name:

```bash
BRANCH_SLUG=$(git branch --show-current | sed 's|.*/||')
RESEARCH_DIR="docs/changelog/.research/${BRANCH_SLUG}"
```

- Changelog files (tracked): `docs/changelog/$BRANCH_SLUG.md`, `docs/changelog/$BRANCH_SLUG-fix-plan.md`
- Research files (gitignored): `$RESEARCH_DIR/`

**Collision check:** Before creating output, check if a changelog already exists for this branch:
```bash
ls "docs/changelog/${BRANCH_SLUG}.md" 2>/dev/null
```
If found, AskUserQuestion: "Existing changelog found at [path]. Overwrite or create new?" Options: "Overwrite" / "Create new (append timestamp)".

```bash
mkdir -p "$RESEARCH_DIR"
```

Store `$RESEARCH_DIR` for all subsequent steps.

### Step 1b: Load ADR Context

If `docs/adr/` exists and contains `.md` files, invoke the `adr-context` skill to load relevant architectural decisions into context:

Invoke the `adr-context` skill via the Skill tool.

This gives research agents (especially code-reviewer and type-design-analyzer) awareness of architectural decisions when analyzing changes. If no ADR directory exists, skip this step.

### Step 2: Research Phase — Parallel Agent Spawn

Launch agents in parallel. Each writes its output to `$RESEARCH_DIR/`.

**Every agent gets this base prompt:**
```
You are contributing to a PR documentation page, not blocking the PR.
Write your analysis to [output file path].
Be specific — file paths, line numbers, code snippets.
Focus on substance, not style nits.

Context:
- Branch: $BRANCH
- Commits: $COMMITS
- Changed files: $CHANGED_FILES
```

**Agent roster (7 agents):**

| # | Agent (`subagent_type`) | Output File | Condition |
|---|------------------------|-------------|-----------|
| 1 | `orc:repo-research-analyst` | `$RESEARCH_DIR/codebase-context.md` | Always |
| 2 | `orc:frontend-verifier` | `$RESEARCH_DIR/screenshots/` + `$RESEARCH_DIR/ui-verification.md` | Only if diff touches `*.tsx`, `*.jsx`, `*.css`, `*.html`, or component files |
| 3 | `orc:build-error-resolver` | `$RESEARCH_DIR/build-report.md` + fixed source files | Always |
| 4 | `orc:codemap-generator` | `$RESEARCH_DIR/codemap.md` | Always |
| 5 | `orc:test-analyzer` | `$RESEARCH_DIR/test-analysis.md` | Always |
| 6 | `orc:type-design-analyzer` | `$RESEARCH_DIR/type-analysis.md` | Always |
| 7 | `orc:code-reviewer` | `$RESEARCH_DIR/code-review.md` | Always |

**Conditional check for `orc:frontend-verifier`:**
Check if `$CHANGED_FILES` contains any `*.tsx`, `*.jsx`, `*.css`, `*.html` files. If yes, also create the screenshots directory:
```bash
mkdir -p "$RESEARCH_DIR/screenshots"
```
If not, skip agent #2.

**Build error handling:**
If `orc:build-error-resolver` fixes source files, present the fixes to the user via AskUserQuestion:
- "Build errors were auto-fixed in these files: [list]. Please review and commit them when ready."
- Options: "Got it, I'll commit" / "Show me what changed" / "Reject fixes"

If "Show me what changed" → display `git diff` of the fixed files. Do NOT stage or commit — that's the user's responsibility.

If "Reject fixes" → rollback with `git checkout -- <files>` to restore originals.

### Step 3: AskUserQuestion — Fill Gaps

After all agents complete, ask the user for context agents can't determine. Use AskUserQuestion with up to 4 questions per call. Skip any question where agent findings already provide the answer.

**Questions:**

1. **Why** — "What problem does this solve or what feature does this add?"

```
AskUserQuestion:
  question: "What problem does this solve or what feature does this add?"
  header: "Why"
  options:
    - label: "Bug fix"
      description: "This PR fixes a defect"
      preview: |
        Changes detected:

        $BRANCH → $BASE_REF
        $COMMIT_COUNT commits, $FILE_COUNT files

        ┌─ FILES CHANGED ──────────────────┐
        │ + [added files]                  │
        │ ~ [modified files]               │
        │ - [deleted files]                │
        └──────────────────────────────────┘

        Hotspots (most changed):
        │ [file1]  +N -M
        │ [file2]  +N -M
        │ [file3]  +N -M
    - label: "New feature"
      description: "This PR adds new functionality"
      preview: |
        [same change summary as above]
    - label: "Refactor"
      description: "Restructuring without behavior change"
      preview: |
        [same change summary as above]
```

Populate the preview dynamically with actual values from Step 1.

2. **User stories** — "What user-facing behavior changed?"
3. **Breaking changes** — "Any API or behavior changes consumers need to know about?"
4. **Testing** — "How was this manually tested? What should reviewers check?"

Then a second round if needed:

5. **Migration** — "Any steps needed after merge? (env vars, migrations, deploys)"

### Step 4: Doc Staleness Check

Read these files and check if the changes make them stale:

| File | Check |
|------|-------|
| `./CLAUDE.md` | Do changes add/remove/rename patterns, conventions, or file structures CLAUDE.md references? |
| `./README.md` | Do changes affect setup, usage, or API documentation? |
| `docs/adr/*.md` | Do changes represent an architectural decision that should be recorded? |

For each stale doc, AskUserQuestion:
- Show what's stale and why
- Propose the specific edit (diff-style)
- Options: "Apply this update" / "Skip" / "I'll handle it later"

If "Apply" → draft the edit, present for user confirmation via tool approval.

### Step 5: Synthesis Phase — PR Description + Fix Plan

Launch 2-3 agents in parallel to produce two separate outputs:

| Synthesis Agent | Reads | Writes |
|----------------|-------|--------|
| Agent 1: "PR Description" | `$RESEARCH_DIR/codebase-context.md`, `$RESEARCH_DIR/codemap.md`, git diff, user answers | `docs/changelog/$BRANCH_SLUG.md` |
| Agent 2: "Fix Plan" | `$RESEARCH_DIR/test-analysis.md`, `$RESEARCH_DIR/type-analysis.md`, `$RESEARCH_DIR/code-review.md`, `$RESEARCH_DIR/build-report.md` | `docs/changelog/$BRANCH_SLUG-fix-plan.md` |
| Agent 3: "UX Detail" (only if frontend-verifier ran) | `$RESEARCH_DIR/ui-verification.md`, `$RESEARCH_DIR/screenshots/` | Appends to `docs/changelog/$BRANCH_SLUG.md` User-Facing Changes section |

**Agent 1** produces the PR description directly — this is the only file the user copies into their PR. It contains what reviewers need: what changed, why, what's breaking, how it was tested.

**Agent 2** reads all quality/testing research and produces a fix plan — triaged findings with concrete fixes. This is a separate artifact the user can choose to run or ignore.

Agent 3 is additive — it enriches User-Facing Changes with screenshots. If frontend-verifier didn't run, Agent 1's section stands alone.

#### Agent 1 output: `docs/changelog/$BRANCH_SLUG.md`

```markdown
# PR ###: [Title from branch]
_Generated: YYYY-MM-DD_
_Branch: feature/xxx → $BASE_REF_
_Commits: N_

## Summary
[1-2 sentences: what this PR does and why]

## Changes
[Semantic change descriptions grouped by area]

## User-Facing Changes
[What users will see differently]
[Screenshots if applicable]

## Breaking Changes
[List or "None"]

## Testing
[Manual testing done by user]

## Docs Updated
- [x] CLAUDE.md — [what was updated, or "no changes needed"]
- [x] README.md — [what was updated, or "no changes needed"]
- [x] ADR — [link if created, or "no new ADR needed"]
```

**Tone**: Sr staff engineer — precise, no fluff, explains the "why" not just the "what".

#### Agent 2 output: `docs/changelog/$BRANCH_SLUG-fix-plan.md`

Agent 2 is a `Plan` subagent. It reads all quality research outputs and produces a structured fix plan:

```markdown
# Fix Plan

**Recommendation: [READY / NOT READY]**
**Confidence: [HIGH / MEDIUM / LOW]**
[1 sentence explaining confidence]

## Blockers

### 1. [Finding title]
- **Source:** [agent report file + severity]
- **File:** [path:line]
- **Issue:** [what's wrong]
- **Fix:** [concrete change — diff-style or description]
- **Bucket:** Fixable / User action / Out of scope

### 2. [Next finding]
...

## Suggestions
[Non-blocking improvements, listed briefly]

## Deferred
[Valid findings that belong in a separate PR, with rationale]
```

Triage rules for Agent 2:

| Bucket | Description | Examples |
|--------|-------------|---------|
| Fixable | Code issues that can be fixed directly | Hook bugs, stale references, missing newlines, broken links |
| User action | Decisions only the user can make | Delete ambiguous files, choose between approaches |
| Out of scope | Valid findings for a separate PR | Major refactors, new test infrastructure, CI setup |

### Step 6: Present PR Description and Iterate

Show `docs/changelog/$BRANCH_SLUG.md` to the user. AskUserQuestion:

```
AskUserQuestion:
  question: "How does this PR description look?"
  header: "Review"
  options:
    - label: "Use as-is"
      description: "Approve the PR description"
      preview: |
        $BRANCH → $BASE_REF

        ┌─ SUMMARY ─────────────────────────┐
        │ [1-2 sentence summary]            │
        └────────────────────────────────────┘

        Changes ($N areas):
        ├─ [area 1]: [what changed]
        ├─ [area 2]: [what changed]
        └─ [area 3]: [what changed]

        | Section            | Status    |
        |--------------------|-----------|
        | Summary            | ✓ filled  |
        | Changes            | ✓ filled  |
        | User-Facing        | ✓/— skip  |
        | Breaking Changes   | ✓ none/—  |
        | Testing            | ✓ filled  |
        | Docs Updated       | ✓/— skip  |

        Research files in $RESEARCH_DIR/
    - label: "Revise a section"
      description: "Change specific sections"
      preview: |
        Available sections to revise:

        1. Summary
        2. Changes
        3. User-Facing Changes
        4. Breaking Changes
        5. Testing
        6. Docs Updated

        Tell me which section and what to change.
    - label: "Add more detail"
      description: "Expand a section with more context"
```

Populate the preview dynamically with actual values from `$BRANCH_SLUG.md`.

If revise → ask which section + what to change → regenerate that section only.

Remind user: "Copy the content for your PR description. The changelog is saved at `docs/changelog/$BRANCH_SLUG.md`."

### Step 7: Present Fix Plan

Show the fix plan from `docs/changelog/$BRANCH_SLUG-fix-plan.md`. AskUserQuestion:

```
AskUserQuestion:
  question: "Agent findings produced a fix plan. Want to run it?"
  header: "Fix plan"
  options:
    - label: "Run fix plan"
      description: "Apply fixable items, ask about user-action items"
      preview: |
        ┌─ READINESS: [READY/NOT READY] ────┐
        │ Confidence: [HIGH/MEDIUM/LOW]     │
        └────────────────────────────────────┘

        Fixable ([N] items):
        ├─ [fix 1: file:line — what]
        ├─ [fix 2: file:line — what]
        └─ [fix 3: file:line — what]

        User action ([N] items):
        ├─ [decision 1]
        └─ [decision 2]

        Deferred ([N] items):
        └─ [item — rationale]

        ┌─ WHAT HAPPENS ───────────────────┐
        │ Fixable items applied via Edit.  │
        │ User-action items asked one by   │
        │ one via AskUserQuestion.         │
        │ Deferred items noted in plan.    │
        └──────────────────────────────────┘
    - label: "Skip — ship as-is"
      description: "Acknowledge findings but don't fix now"
      preview: |
        Fix plan saved at:
        docs/changelog/$BRANCH_SLUG-fix-plan.md

        You can run it later or address
        findings manually.
    - label: "Review details first"
      description: "Show me the full fix plan before deciding"
```

**If "Run fix plan":**
1. Apply all Fixable items via Edit tool
2. For each User-action item, present via AskUserQuestion
3. Deferred items: no action, already documented in fix plan
4. After all fixes applied, update `docs/changelog/$BRANCH_SLUG-fix-plan.md` — mark resolved items, update recommendation

**If "Skip":**
PR description is at `docs/changelog/$BRANCH_SLUG.md`, fix plan saved at `docs/changelog/$BRANCH_SLUG-fix-plan.md` for later.

### Step 8: Cleanup

After Step 7 completes (whether fixes were applied or skipped), ask the user if they want to clean up:

```
AskUserQuestion:
  question: "Clean up research files?"
  header: "Cleanup"
  options:
    - label: "Keep all"
      description: "Keep research files for reference"
      preview: |
        Tracked (docs/changelog/):
        ├─ $BRANCH_SLUG.md (PR description)
        └─ $BRANCH_SLUG-fix-plan.md

        Research ($RESEARCH_DIR/):
        ├─ codebase-context.md
        ├─ codemap.md
        ├─ test-analysis.md
        ├─ type-analysis.md
        ├─ code-review.md
        ├─ build-report.md
        └─ ui-verification.md (if applicable)
    - label: "Remove research"
      description: "Keep changelogs, delete research files"
      preview: |
        Will delete:
        └─ $RESEARCH_DIR/ (entire directory)

        Keeping:
        ├─ docs/changelog/$BRANCH_SLUG.md
        └─ docs/changelog/$BRANCH_SLUG-fix-plan.md
    - label: "Remove everything"
      description: "Delete changelogs and research files"
```

If "Remove research" → `rm -rf "$RESEARCH_DIR"`.

If "Remove everything" → delete `docs/changelog/$BRANCH_SLUG.md`, `docs/changelog/$BRANCH_SLUG-fix-plan.md`, and `rm -rf "$RESEARCH_DIR"`.

### Preview Generation Rules

Every AskUserQuestion option in Steps 3, 6, and 7 MUST include a `preview` field.

**Tree diagrams** — for change lists, file hierarchies:
```
  [root]
  ├─ [item 1]
  │  └─ [detail]
  └─ [item 2]
```

**ASCII box diagrams** — for summaries, status, boundaries:
```
  ┌─ LABEL ──────────────────────┐
  │ [content]                    │
  └──────────────────────────────┘
```

**Tables** — for section status, comparisons:
```
  | Column 1 | Column 2 |
  |----------|----------|
  | data     | data     |
```

**Status markers** — ✓ good, ✗ blocker, ~ suggestion, — skipped

Keep previews scannable. Max ~30 lines per preview. Populate all `$VARIABLE` placeholders with actual runtime values before displaying.

## File Ownership

| File | Access | Purpose |
|------|--------|---------|
| `docs/changelog/$BRANCH_SLUG.md` | Write | PR description (tracked) |
| `docs/changelog/$BRANCH_SLUG-fix-plan.md` | Write | Fix plan (tracked) |
| `docs/changelog/.research/$BRANCH_SLUG/` | Write | Research artifacts (gitignored) |
| `./CLAUDE.md` | Read (propose edits via AskUserQuestion) | Staleness check |
| `./README.md` | Read (propose edits via AskUserQuestion) | Staleness check |
| `docs/adr/*.md` | Read | ADR need check |
| Git history | Read only | Understand changes |
| Source files | Write (build fixes only) | build-error-resolver auto-fix |
| Source files | Write (fixes from Step 7) | Apply triaged fixes from fix plan |

## Completion Criteria

- [ ] Git diff analyzed
- [ ] All research agents completed and wrote output files
- [ ] Build errors auto-fixed (if any), user asked to commit
- [ ] User provided context (why, user stories, breaking changes, testing, migration)
- [ ] CLAUDE.md, README.md, ADRs checked for staleness
- [ ] Doc updates proposed where needed (user confirmed/skipped)
- [ ] PR description written to `docs/changelog/$BRANCH_SLUG.md`
- [ ] Fix plan written to `docs/changelog/$BRANCH_SLUG-fix-plan.md`
- [ ] User confirmed or iterated on PR description
- [ ] All research files saved to `$RESEARCH_DIR/`
- [ ] Fix plan presented — user chose to run, skip, or review
- [ ] Cleanup offered — user chose to keep, trim, or remove files