Compound Pr

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).

• [ ] 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

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.

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 -- for rollback

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

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 $BASEREF → "You're on $BASEREF`. Switch to a feature branch first."

1. No commits vs base:

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

1. 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:

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 -- for the files relevant to their analysis.

Derive output paths from branch name:

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:

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)".

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:

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 -- 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.

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

Then a second round if needed:

1. 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

# 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:

# 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 recommendatio

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.