# Fix & Regenerate Feature Spec

**Created:** 2026-02-24 (Xian)
**Status:** Approved — ready to build
**Priority:** High

---

## Scope

For generated images with QA status `Warning` or `Failed`, add a **Fix** button that:
1. Regenerates a new corrected image version
2. Preserves the original
3. Links old ↔ new
4. Auto-runs QA on the new image
5. Keeps both visible in Content Review

---

## Fix Button — Show Conditions

| Status | Show Fix? |
|--------|-----------|
| Warning | ✅ Yes |
| Failed / Failed QA | ✅ Yes |
| Pass / Approved | ❌ No |
| Pending QA / Scanning | ❌ No |
| Generation Failed (no image) | ❌ No |

---

## Core Behavior

### 1. Do NOT overwrite original
- Original image file stays as-is
- Original qa-reports.json record stays as-is
- New image = new file, new Asset ID, new record

### 2. Use QA reasons as fix constraints
Convert QA issues into structured regeneration constraints:
- Wrong ratio → specify correct ratio in generation prompt
- Brand color mismatch → include correct palette
- Logo missing/wrong → specify correct logo placement
- Text in safe zone → constrain text placement
- Low readability → increase contrast in prompt
- Platform mismatch → target correct platform specs

### 3. Link original ↔ fixed
New asset record must include:
```json
{
  "assetId": "new-uuid",
  "version": 2,
  "previousVersionId": "original-asset-id",
  "fixSource": "original-asset-id",
  "fixTrigger": "manual_fix_button",
  "fixIssuesUsed": ["issue 1", "issue 2"],
  "fixTriggeredBy": "xian",
  "fixTriggeredAt": "ISO8601",
  "fixQAVerdict": null
}
```

Original record gets a `fixedBy` pointer:
```json
{
  "fixedBy": "new-uuid",
  "fixedAt": "ISO8601"
}
```

### 4. Auto-QA new image
- Immediately after generation, run QA on new image
- Do NOT copy old verdict
- Return fresh verdict for new asset

### 5. Both visible in Content Review
- Original: labeled `Original (Warning)` or `Original (Failed)`
- Fixed: labeled `Fixed v1`, `Fixed v2`, etc.
- Show `Derived from: {original-asset-id-short}` on fixed version

---

## UX Buttons (per-image, Warning/Failed only)

```
[ Review ] [ Approve ] [ Fix ]
```

### Fix status flow (new image):
```
Fix Requested → Regenerating → Queued for QA → QA Scanning → Verdict Ready
```

### User messaging after Fix:
1. "Fix requested for {filename} — regenerating now..."
2. "New version generated — queued for QA"
3. "QA Verdict for fixed version: {Pass/Warning/Fail} — {reason}"
4. Content Review link

---

## Data Requirements (per fixed asset)

| Field | Value |
|-------|-------|
| `assetId` | New UUID |
| `previousVersionId` | Original asset ID |
| `fixSource` | Original asset ID (same as previousVersionId) |
| `fixTrigger` | `"manual_fix_button"` |
| `fixIssuesUsed` | Array of QA issue strings from original |
| `fixTriggeredBy` | User who clicked Fix |
| `fixTriggeredAt` | ISO timestamp |
| `fixQAVerdict` | Set after auto-QA runs |
| `product` | Same as original (inherit) |
| `targetPlatform` | Same as original (inherit) |

---

## Guardrails

- ❌ Never delete/overwrite original image
- ❌ Never copy old QA verdict to new image
- ❌ Never break product association
- ✅ Fixed image inherits same product context
- ✅ Log who triggered + when + which issues triggered it
- ✅ Version chain is traceable (v1 → v2 → v3)

---

## Generation Strategy

For AI-generated assets: use nano-banana-pro or OpenAI DALL-E with fix-constrained prompt
For manually created assets: cannot auto-fix — create a structured fix task/brief for the team

Fix prompt construction:
```
Original prompt context: {product}, {platform}, {placement}
Brand: {product colors}, {logo requirements}
Platform specs: {ratio}, {safe zones}
Fix constraints: {each QA issue converted to a constraint}
```

---

## Implementation Plan

### Backend
- `/api/marketing/fix-asset` POST endpoint
  - Accepts: `{ slug, assetId, triggeredBy? }`
  - Creates new asset record with all fix fields
  - Builds fix-constrained generation prompt from QA issues
  - Calls image generation (nano-banana-pro)
  - Saves new image to `marketing/` with timestamp prefix
  - Triggers auto-QA on new image
  - Returns new asset ID + status

### Frontend (SocialQA.tsx)
- Fix button in detail panel (warning/fail only)
- Fix status flow UI (5 steps)
- Version history display
- Link between original and fixed
- Labels: Original (Warning) / Fixed v1 / Fixed v2

### Notification
- Discord notification when fix is requested
- Discord notification when fix QA verdict is ready
