---
title: "PR Comment & Preview Enhancements"
status: draft
owner: ng
team: specwright
ticket_project: Gerner-Ventures/gv-exp-specwright
created: 2026-02-26
updated: 2026-02-26
tags: [pr-comments, preview, web-app, developer-experience]
---

# PR Comment & Preview Enhancements

Add Specwright web app deep links to GitHub PR comments and enable preview deployments for the Spec Explorer web UI.

## 1. Background

<!-- specwright:system:1 status:done -->

When the Specwright agent posts comments on PRs (spec coverage, analysis results), the comments don't link back to the Specwright web app. Users have no easy way to navigate from a PR comment to the relevant spec in the editor. Additionally, the Spec Explorer web UI has no preview deployment capability — reviewers can't see UI changes before merging.

**Related:** [#94](https://github.com/Gerner-Ventures/gv-exp-specwright/issues/94), [#41](https://github.com/Gerner-Ventures/gv-exp-specwright/issues/41)

## 2. Web App Links in PR Comments

<!-- specwright:system:2 status:done -->
<!-- specwright:ticket:github:94 -->

Update the GitHub comment templates in the agent/analyzer to include deep links to the Specwright web app for each referenced spec.

### 2.1 Link Format

For each spec mentioned in a PR comment, include a link like:
`[View in Specwright](https://specwright.gernerventures.com/app/{org}/{repo}/specs/{spec-slug})`

### 2.2 Comment Sections to Update

- Spec coverage summary → link to org dashboard
- Per-spec analysis → link to individual spec view
- Acceptance criteria checklist → link to spec section

### Acceptance Criteria

- [ ] PR comments include deep links to the Specwright web app
<!-- specwright:realized-in:PR#117 file:src/specwright/agent/analyzer.py -->
- [ ] Links point to the correct spec/section in the web app
<!-- specwright:realized-in:PR#117 file:tests/test_agent/test_analyzer.py -->
- [ ] Links use the configured Specwright domain (not hardcoded)
<!-- specwright:realized-in:PR#117 file:src/specwright/settings.py -->
<!-- specwright:realized-in:PR#117 file:src/specwright/github/handlers/on_pull_request.py -->
- [ ] Comments degrade gracefully if web app URL is not configured (omit links, don't error)
- [ ] Existing PR comment formatting is preserved

## 3. Preview Deployments for Spec Explorer

<!-- specwright:system:3 status:draft -->
<!-- specwright:ticket:github:41 -->

Enable preview deployments for the Spec Explorer web UI so reviewers can see UI changes before merging. The main webhook handler cannot be previewed (single webhook URL), but the read-only web UI can.

### 3.1 Approach

- Build and deploy the web UI (Jinja2 templates + static assets) as a standalone preview
- Preview connects to the production GitHub App for data (read-only)
- Preview URL posted as a PR comment or GitHub deployment status

### Acceptance Criteria

- [ ] PRs that modify `templates/` or `static/` files trigger a preview deployment
- [ ] Preview URL is accessible and shows the updated UI
- [ ] Preview connects to production data source (read-only)
- [ ] Preview deployments are cleaned up after PR merge/close
- [ ] Preview URL is posted as a GitHub deployment status or PR comment

## 4. Open Questions

- What hosting for preview deployments? (Vercel, Fly.io preview apps, K8s ephemeral namespace?)
- Should preview deployments use a separate GitHub App installation or the production one?
- How to handle preview auth? (Same Auth0 tenant, or skip auth for previews?)
