name: website-improvement-prd
description: Generate an approval-gated improvement PRD from a report and baseline, with evidence-backed what/why/value changes and measurable targets. Use for rebuild proposals. Don't use for task breakdown, coding, implementation, or unapproved persistence.
license: MIT
effort: high
metadata:
    version: 1.4.0
    author: "Luong NGUYEN <luongnv89@gmail.com>"

Website Improvement PRD

Turns an approved end-user report into a full improvement proposal with measurable value metrics. Writes prd.md after user approval.

When to Use

Trigger when the user asks to:

• Propose website improvements with expected impact
• Create a PRD for a site rebuild or improvement
• Plan improvements with measurable metrics

Do not use for implementation planning or coding — those are separate phases.

Prerequisites

1. Require the Phase 1 analysis (analysis.json) and the approved Phase 2 report — ask for their paths if not supplied.
2. Confirm the Write tool is available; if it is not, stop with a descriptive error.
3. Confirm the output path ($PROJECT_DIR/prd.md or the ~/workspace/clones/YYYY_MM_DD_slug/prd.md fallback) is writable before drafting.
4. If any prerequisite fails, stop with a descriptive error naming the failing input and corrective action.

Repo Sync Before Edits (mandatory)

The approved prd.md is persisted with Write. When that output path lives inside a git worktree, sync before the write to avoid clobbering remote work:

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is dirty: stash → sync → pop. If origin is missing or a conflict occurs: stop and ask the user. Skip this section only when the output path is outside any git repository.

Workflow

1. Read the approved report (Phase 2) and analysis (Phase 1)
2. Identify improvement opportunities per dimension
3. For each change: define what, why, and expected value
4. Assemble into prd.md
5. Present to user for review
6. Incorporate edits (loop until approved)
7. Persist prd.md

Output: prd.md Structure

# Improvement Proposal: <site name>
**Source URL:** <url>
**Date:** <date>
**Version:** 1.0

---

## Executive Summary

2–3 sentences summarizing the main improvement themes and expected impact.

## Current State

Brief summary of the baseline from Phase 1 analysis:
- Category and audience
- Current performance highlights
- Current SEO standing
- Current security posture

## Proposed Improvements

### Change 1: <Title>

**What:** Specific, scoped description of the change.
Example: "Replace the current hero section with a centered layout featuring a clear headline, subtext, and primary CTA button above the fold."

**Why:** Problem being solved, evidence from Phase 1 analysis.
Example: "The current hero burying the CTA below two content sections. Users must scroll past unrelated content before seeing the sign-up option (Phase 1 UI/UX friction point: 'CTA not immediately visible')."

**Expected Value:** Measurable impact.
Example: "If Phase 1 measured a primary CTA scroll distance, make the CTA visible without scrolling (scroll distance to CTA: <measured distance> → 0px). Click-through/conversion impact is not measurable from a static crawl; measure it after launch."

---

Repeat for each change. Group changes by dimension:

### UI/UX Improvements
### Performance Improvements
### SEO Improvements
### Security Improvements
### Style Enhancements

## Metrics Summary

| Metric | Current | Target | Delta |
|--------|---------|--------|-------|
| LCP | 4.3s | ≤ 2.0s | -53% |
| CLS | 0.18 | ≤ 0.05 | -72% |
| SEO Score | 62/100 | ≥ 90/100 | +45% |
| Page Weight | 2.1 MB | ≤ 800 KB | -62% |

## Next Steps

Reference Phase 4 (implementation plan) — the approved proposal feeds into `tasks.md` for phased execution.

---

*This proposal is based on analysis of a single crawl of the source site. Actual improvements may vary based on implementation decisions.*

Step 1: Read Inputs

Read the approved report and analysis:

Read file <path-to-report.md>
Read file <path-to-analysis.json>

If either is missing, ask for paths. The orchestrator should have already produced both.

Step 2: Identify Improvements

For each dimension, identify specific, actionable improvements:

• UI/UX: Layout changes, navigation fixes, CTA improvements, content restructuring
• Performance: Image optimization, lazy loading, code splitting, font optimization, caching
• SEO: Meta tag fixes, heading structure, structured data, alt text, canonical URLs
• Security: HTTPS hardening, security headers, mixed content fixes
• Style: Typography improvements, color palette refinement, spacing consistency, motion polish

Each improvement must include:

1. What — specific, scoped change description
2. Why — problem + evidence from Phase 1
3. Expected Value — measurable impact statement

Step 3: Compute Metrics Summary

Compare current metrics from Phase 1 against realistic targets:

Step 4: Write Draft prd.md

Assemble the proposal using the structure above.

Step 5: Present for Review

Present the draft to the user:

"Here is the improvement proposal. Please:

1. Approve — save as prd.md
2. Edit — specify what to change
3. Regenerate — start over with different focus"

Step 6: Incorporate Edits (loop)

If edits requested:

• Update the proposal
• Re-present
• Repeat until approved

Do not persist until explicit approval.

Step 7: Persist prd.md

Persist the assembled content using the Write tool with literal content only. If the Write tool is unavailable, stop with a descriptive error and do not use shell persistence or another output path.

Default: $PROJECT_DIR/prd.md or ~/workspace/clones/YYYY_MM_DD_slug/prd.md.

If $ARGUMENTS includes --output <path>, use that.

Confirm:

prd.md saved to: <absolute-path>
STATUS: approved

Return Contract

When invoked by the website-cloner umbrella (Phase 3 gate), the orchestrator

gates Phase 4 on this skill's outcome. The contract:

The orchestrator MUST NOT advance to Phase 4 unless the outcome is approved.

A standalone invocation may ignore the status line, but the file-existence rule

still holds: no approval, no prd.md.

Acceptance Criteria and Expected Output

Verify the complete proposal before requesting approval:

• Every proposed change contains a specific What, evidence-backed Why, and measurable Expected Value.
• Every baseline issue from the approved report or analysis maps to a proposal change or an explicit out-of-scope rationale.
• Metric targets include units, current values, realistic target logic, and correctly computed deltas; label estimates rather than presenting them as guarantees.
• prd.md contains executive summary, current state, grouped improvements, metrics summary, next steps, and source-data caveat.
• The expected result is an approved non-empty markdown file plus exactly one final STATUS: approved; pending or aborted outcomes write no file.

Step Completion Report

◆ Website Improvement PRD
··································································
  Inputs validated:     √ pass | × fail ([reason])
  Changes evidenced:   √ pass ([count])
  Targets measurable:  √ pass
  User approved:       √ pass | × pending
  prd.md saved:        √ pass ([absolute path]) | — not approved
  Result:              PASS | BLOCKED | FAIL

Report PASS only when the return contract's file and final status-line conditions both hold.

Edge Cases and Error Handling