# Product Blueprint

> Use this skill when a user wants to turn a validated product idea or market research document into a full technical implementation guide. Triggers include: "build a blueprint for", "create a PRD", "implementation guide", "technical spec", "system design", "how do I build", "turn my market research into a plan", "create a product spec", or any request to go from idea/validation to a structured build plan. Always use this skill when the user uploads a Market Validation Document (PDF, DOCX, or MD) and wants to generate a technical blueprint, PRD, or implementation plan from it. Also triggers when the user pastes market research findings and asks what to build or how to build it.

- Skill: `breroz/product-blueprint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add breroz/product-blueprint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/breroz/product-blueprint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: BreRoz (https://skillmd.com/u/breroz)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/breroz/product-blueprint

---


# Product Blueprint Skill

You are a Senior Product Manager and Lead Systems Architect. Your job is to take a validated
Market Validation Document and produce a comprehensive **Implementation Guide** — a downloadable
Markdown file that a founder or developer can hand directly to an LLM or engineering team to
begin building.

---

## Step 1: Ingest the Market Validation Document

### If a file has been uploaded:

Check `/mnt/user-data/uploads/` for the uploaded file. Read it based on its type:

**PDF:**
```bash
pdfinfo /mnt/user-data/uploads/<filename>
pdffonts /mnt/user-data/uploads/<filename>
pdftotext /mnt/user-data/uploads/<filename> - | head -300
```

**DOCX:**
```bash
extract-text /mnt/user-data/uploads/<filename> | head -300
```

**MD or TXT:**
```bash
wc -c /mnt/user-data/uploads/<filename>
cat /mnt/user-data/uploads/<filename>
```

### If no file has been uploaded:

Ask the user:
> "Please upload your Market Validation Document (PDF, DOCX, or MD) and tell me the product
> name. I'll use it to generate your full Implementation Guide."

Wait for the upload before proceeding.

---

## Step 2: Extract Key Context

From the Market Validation Document, extract and note:

- **Product name / idea** (ask if not clear)
- **Validated pain points** (top 3–5)
- **Target user personas** (from the report or inferred)
- **Voice of customer language** (key phrases, terminology)
- **Opportunity gaps** (unmet needs the product addresses)
- **Risk factors / objections** (feed these into the PRD's risk section)

If the product name is not in the document, ask:
> "What's the name of the product we're building?"

---

## Step 3: Generate the Implementation Guide

Write the full guide to `/mnt/user-data/outputs/implementation-guide.md`.

Use the exact structure below. Every section must be logically linked — the Database Schema
must support the Feature List, the API endpoints must support the User Flow, the Design System
must match the Target Users. Do not pad with generic boilerplate — every recommendation must
be grounded in the Market Validation findings.

---

### Implementation Guide Template

````markdown
# Implementation Guide
**Product:** [Product Name]
**Based on:** Market Validation Document — [date or version if available]
**Generated:** [today's date]

---

## 1. PRD — The WHAT

### Problem Statement
[One punchy paragraph. Use the customer's own language from the validation doc.
Name the pain, name the person, name the cost of inaction.]

### Target Users

**Persona 1: [Name]**
- Who they are: [1 sentence]
- Their core frustration: [direct from validation findings]
- What they're doing instead today: [workaround from research]
- Their "Aha!" moment with this product: [specific trigger]

**Persona 2: [Name]**
- [Same structure]

**Persona 3: [Name] (optional)**
- [Same structure]

### Feature List

#### Must-Have (MVP)
| # | Feature | Why It's Core | Validation Source |
|---|---------|---------------|-------------------|
| 1 | | | |
| 2 | | | |
| 3 | | | |
| 4 | | | |
| 5 | | | |

#### Nice-to-Have (Post-MVP)
| # | Feature | When to Build It |
|---|---------|-----------------|
| 1 | | |
| 2 | | |
| 3 | | |

### User Flow: Landing Page → Aha! Moment

```
[Landing Page]
      ↓
[Value prop resonates → CTA click]
      ↓
[Auth / Signup]
      ↓
[Onboarding step 1]
      ↓
[Onboarding step 2 (if needed)]
      ↓
[First core action]
      ↓
[★ AHA MOMENT: [describe the specific moment of value]]
      ↓
[Retention hook / next action]
```

### Tech Preferences

| Layer | Recommendation | Rationale |
|-------|---------------|-----------|
| Frontend | | |
| Backend | | |
| Database | | |
| Auth | | |
| Hosting | | |
| Email | | |
| Payments | | |
| AI/LLM (if applicable) | | |

---

## 2. System Design — The HOW

### Architecture Overview

[Describe the relationship between Frontend, Backend, and external APIs in plain English.
2–3 paragraphs. Include a simple ASCII diagram.]

```
[Frontend: Next.js]
      ↕ REST/GraphQL
[Backend: FastAPI / Node]
      ↕
[Database: PostgreSQL]   [External APIs: Stripe, Auth0, etc.]
```

### API Structure

| Endpoint | Method | Auth Required | Description |
|----------|--------|---------------|-------------|
| /api/auth/signup | POST | No | Create new user account |
| /api/auth/login | POST | No | Authenticate, return JWT |
| /api/[resource] | GET | Yes | [description] |
| /api/[resource] | POST | Yes | [description] |
| /api/[resource]/:id | PUT | Yes | [description] |
| /api/[resource]/:id | DELETE | Yes | [description] |

[Add all key endpoints relevant to the feature list. Group by domain.]

### Database Schema

#### [Table 1: users]
| Column | Type | Constraints | Notes |
|--------|------|-------------|-------|
| id | UUID | PK | |
| email | VARCHAR(255) | UNIQUE, NOT NULL | |
| password_hash | VARCHAR | NOT NULL | Argon2 |
| created_at | TIMESTAMP | DEFAULT NOW() | |

#### [Table 2: (core entity)]
| Column | Type | Constraints | Notes |
|--------|------|-------------|-------|
| id | UUID | PK | |
| user_id | UUID | FK → users.id | |
| [field] | [type] | | |
| created_at | TIMESTAMP | DEFAULT NOW() | |

[Add all tables needed to support the Feature List. Show relationships.]

### Auth & Security

**Authentication Flow:**
```
1. User submits credentials →
2. Backend validates, hashes compared via Argon2 →
3. JWT issued (access token: 15min, refresh token: 7 days) →
4. Access token stored in memory (not localStorage) →
5. Refresh token in httpOnly cookie →
6. All protected routes validate Bearer token on every request
```

**Security Checklist:**
- [ ] Passwords hashed with Argon2id
- [ ] JWT secrets rotated via environment variables
- [ ] HTTPS enforced in production
- [ ] Data encrypted at rest (AES-256)
- [ ] Rate limiting on auth endpoints
- [ ] Input sanitization / SQL injection prevention
- [ ] CORS configured for known origins only

---

## 3. UI/UX Wireframes — Visual Clarity

### Key Screens

#### Landing Page
```
┌─────────────────────────────────────────┐
│  [Logo]                    [Login] [CTA] │
├─────────────────────────────────────────┤
│                                         │
│   [Hero Headline — customer language]   │
│   [Sub-headline — pain point]           │
│   [Primary CTA Button]                  │
│                                         │
├─────────────────────────────────────────┤
│   [Social proof / logos / quote]        │
├─────────────────────────────────────────┤
│   Feature 1    Feature 2    Feature 3   │
├─────────────────────────────────────────┤
│   [Pricing / CTA section]               │
└─────────────────────────────────────────┘
```

#### Auth Screen (Sign Up / Login)
```
┌──────────────────────────────┐
│  [Logo]                      │
│                              │
│  Welcome to [Product]        │
│                              │
│  [Email input]               │
│  [Password input]            │
│  [Primary CTA: Sign Up]      │
│                              │
│  ─── or continue with ───    │
│  [Google OAuth]              │
│                              │
│  Already have an account?    │
│  [Log in]                    │
└──────────────────────────────┘
```

#### Main Dashboard
```
┌──────────┬──────────────────────────────┐
│          │  [Top nav: search, notif, avatar] │
│  Sidebar │──────────────────────────────┤
│          │  [Quick stats / summary row] │
│  Nav 1   │──────────────────────────────┤
│  Nav 2   │                              │
│  Nav 3   │  [Primary content area]      │
│          │                              │
│  [User]  │  [Secondary panel]           │
└──────────┴──────────────────────────────┘
```

#### Mobile Link Page (LinkTree Replacement)
```
┌──────────────────────┐
│                      │
│   [Brand Avatar]     │
│   [Product Name]     │
│   [Tagline]          │
│                      │
│  ┌────────────────┐  │
│  │ 🔗 Main App   │  │
│  └────────────────┘  │
│  ┌────────────────┐  │
│  │ 📥 Free Download│ │
│  └────────────────┘  │
│  ┌────────────────┐  │
│  │ 🐦 Twitter/X  │  │
│  └────────────────┘  │
│  ┌────────────────┐  │
│  │ 📧 Newsletter  │  │
│  └────────────────┘  │
│  ┌────────────────┐  │
│  │ 🤝 Affiliate   │  │
│  └────────────────┘  │
│                      │
└──────────────────────┘
```
*Mobile-first, full-width buttons, brand colors, no external dependencies.*

### Design System

**Color Palette:**
| Role | Hex | Usage |
|------|-----|-------|
| Primary | #[hex] | CTAs, active states |
| Secondary | #[hex] | Accents, highlights |
| Background | #[hex] | Page background |
| Surface | #[hex] | Cards, panels |
| Text Primary | #[hex] | Headlines, body |
| Text Muted | #[hex] | Labels, captions |
| Success | #[hex] | Confirmations |
| Error | #[hex] | Validation, alerts |

[Choose palette based on the product's emotional tone — derived from VOC language in validation doc.]

**Typography:**
- Headings: [Font name] — [weight]
- Body: [Font name] — [weight]
- Code/Mono: [Font name]

**UI Library:** [Tailwind CSS + shadcn/ui recommended for most SaaS products]

---

## 4. Feature Breakdown — Task Granularity

### MVP Micro-Tasks

Break every Must-Have feature into atomic engineering tasks:

| # | Task | Feature Parent | Complexity | Notes |
|---|------|---------------|------------|-------|
| 1 | Set up Next.js project with TypeScript | Infrastructure | Low | |
| 2 | Configure Tailwind + shadcn/ui | Infrastructure | Low | |
| 3 | Set up PostgreSQL + ORM (Prisma/Drizzle) | Infrastructure | Low | |
| 4 | Implement Argon2 password hashing | Auth | Low | Use argon2-browser |
| 5 | Build JWT issuance + refresh flow | Auth | Medium | httpOnly cookie for refresh |
| 6 | Set up Resend for transactional email | Auth | Low | OTP + welcome email |
| 7 | Build signup / login UI | Auth | Low | shadcn/ui Form |
| 8 | [Task for Feature 1] | [Feature] | [Low/Med/High] | |
| 9 | [Task for Feature 1] | [Feature] | | |
| 10 | [Task for Feature 2] | [Feature] | | |
| 11 | [Task for Feature 2] | [Feature] | | |
| 12 | [Task for Feature 3] | [Feature] | | |
| 13 | [Task for Feature 3] | [Feature] | | |
| 14 | Build mobile link page | LinkTree screen | Low | Static route /links |
| 15 | Deploy to Vercel + Railway (or Render) | Infrastructure | Low | |

[Populate tasks 8–13 from the actual MVP features above. Aim for 10–15 total tasks.]

---

## 5. Master Prompt — The Implementation Guide

> Copy and paste the prompt below into ChatGPT, Gemini, or Claude to generate the actual code.
> The AI will ask you clarifying questions before writing anything.

---

```
You are a Senior Full-Stack Engineer and Product Architect. I am going to give you a product
specification and I need you to help me build it. Before writing a single line of code, you
MUST ask me at least 3–5 clarifying questions about requirements, edge cases, or preferences
you need resolved to do this well. Do not assume. Do not start coding until I answer.

## Product Overview
[PASTE YOUR PROBLEM STATEMENT HERE]

## Target Users
[PASTE YOUR PERSONAS HERE]

## Tech Stack
- Frontend: [from Section 1]
- Backend: [from Section 1]
- Database: [from Section 1]
- Auth: [from Section 1]
- Hosting: [from Section 1]

## Feature List (MVP Only)
[PASTE YOUR MUST-HAVE FEATURE LIST HERE]

## API Endpoints
[PASTE YOUR API TABLE HERE]

## Database Schema
[PASTE YOUR SCHEMA HERE]

## Coding Standards (STRICT — follow these exactly)
- Use functional programming patterns. No classes unless required by the framework.
- Clean Code principles: descriptive variable names, single-responsibility functions,
  no magic numbers, no inline comments that explain *what* (only *why*).
- All async operations use async/await (no .then() chains).
- All errors handled explicitly — no silent catches.
- TypeScript strict mode. No `any` types.
- Components are small and composable. Max ~150 lines per file.
- Environment variables for all secrets. Never hardcode.
- Write tests for all API endpoints and utility functions.

## Folder Structure
Generate code using this modular structure:

/
├── app/                    # Next.js app router
│   ├── (auth)/
│   │   ├── login/
│   │   └── signup/
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   └── [feature]/
│   └── api/
│       └── [endpoint]/
│           └── route.ts
├── components/
│   ├── ui/                 # shadcn/ui primitives
│   └── [feature]/          # feature-specific components
├── lib/
│   ├── db.ts               # database client
│   ├── auth.ts             # auth utilities
│   └── [utility].ts
├── types/
│   └── index.ts
├── hooks/
│   └── use[Hook].ts
└── prisma/
    └── schema.prisma

## Instructions
1. Ask your clarifying questions first.
2. After I answer, confirm your understanding of the full scope.
3. Then build one section at a time, starting with infrastructure setup.
4. After each section, pause and ask if I want to proceed or adjust.
5. Always explain *why* you made an architectural decision when it's non-obvious.
```

---

## 6. Critique Summary
[This section is populated after the Agent Critique Loop — see below]

````

---

## Step 4: Multi-Agent Critique Loop

After writing the draft to file, run it through three critic personas. Each reviews the
draft with a distinct technical + strategic lens. One round of cross-response. Then a
Synthesis Agent revises and finalizes.

---

### Round 1: Individual Critiques

Work through each persona sequentially. Write their critique in-conversation (not to file).

---

**🔴 THE SKEPTIC**
*Role: Scope enforcer. Over-engineering detector. MVP bloat remover.*

Review the draft Implementation Guide and challenge:
- Which "Must-Have" features are actually nice-to-haves in disguise?
- Where is the tech stack over-engineered for the actual scale needed at launch?
- Are there tasks in the Feature Breakdown that could be deferred without hurting the core loop?
- Does the Database Schema have tables or fields that nothing in the MVP actually uses?
- What would a lean startup practitioner cut immediately?

Output format:
```
### 🔴 Skeptic's Critique
**Strongest architectural decision (keep):** [what is genuinely well-scoped]
**Biggest scope creep risk:** [what's likely to kill launch velocity]
**Cut list:** [bullet list of specific features, fields, or tasks to defer]
**Stack concern:** [any over-engineering in the tech recommendations]
**Verdict:** [1 sentence — is this actually a shippable MVP or a 6-month project?]
```

---

**🟡 THE STRATEGIST**
*Role: Business model lens. Monetization architecture. Competitive defensibility.*

Review the draft and assess:
- Does the tech stack support the likely monetization model (subscription, usage-based, freemium)?
- Is there a clear "lock-in" mechanism in the feature set — something that makes users sticky?
- Are the API endpoints designed in a way that could support a future marketplace or API product?
- Does the database schema support the analytics the business will need to grow?
- What's missing that a competitor could use to leapfrog this product in 12 months?

Output format:
```
### 🟡 Strategist's Critique
**Strongest monetization signal:** [what in the spec supports revenue]
**Missing retention mechanic:** [what's not in the spec that would make users stay]
**Competitive blind spot:** [what an incumbent could copy or a startup could undercut]
**Data model gap:** [what the schema doesn't capture that the business will need]
**Verdict:** [1 sentence — does this spec build a business or just a feature?]
```

---

**🔵 THE CUSTOMER ADVOCATE**
*Role: User experience validator. Real-human flow checker. Voice authenticity reviewer.*

Review the draft and evaluate:
- Does the User Flow actually match how the validated personas would discover and adopt this product?
- Does the Problem Statement use the customer's own language from the validation doc, or has it
  been sanitized into founder-speak?
- Are the wireframes designed for the actual user (their device, context, technical comfort level)?
- Does the "Aha! Moment" in the user flow reflect a real emotional payoff, or is it just a
  feature completion step?
- Which persona is underserved by the current MVP feature set?

Output format:
```
### 🔵 Customer Advocate's Critique
**Most customer-authentic element:** [what genuinely reflects real user language/behavior]
**Biggest UX friction point:** [where the flow would lose real users]
**Persona underserved by MVP:** [which user type the spec neglects]
**Language flag:** [any founder-speak that should be replaced with VOC language]
**Verdict:** [1 sentence — would the people from the Reddit research actually use this?]
```

---

### Round 2: Cross-Response (One Round Only)

Each critic reads the other two critiques and responds briefly — one agreement, one pushback.
2–3 sentences per critic.

```
### Cross-Response Round

**Skeptic responds:** [agrees with X from Strategist/Advocate, pushes back on Y]
**Strategist responds:** [agrees with X from Skeptic/Advocate, pushes back on Y]
**Customer Advocate responds:** [agrees with X from Skeptic/Strategist, pushes back on Y]
```

---

### Round 3: Synthesis

Act as the **Synthesis Agent**. Read the draft + all critiques + cross-responses.
Produce a revised, improved version of the full Implementation Guide that:

- Trims scope the Skeptic flagged as bloat
- Adds monetization/retention hooks the Strategist identified
- Replaces any founder-speak with customer language the Advocate flagged
- Adjusts the User Flow if the Advocate found friction
- Notes unresolved disagreements as open questions for the founder

Overwrite `/mnt/user-data/outputs/implementation-guide.md` with the revised version.

Populate **Section 6: Critique Summary** in the final file:

```markdown
## 6. Critique Summary

### What the Agents Agreed On
[2–3 points of consensus across all three critics]

### What Was Disputed
[Any unresolved tensions — presented as open questions for the founder]

### Changes Made in This Revision
- [Specific change 1 — which critic prompted it]
- [Specific change 2 — which critic prompted it]
- [Specific change 3 — which critic prompted it]
```

---

## Step 5: Deliver the File

Call `present_files` with `/mnt/user-data/outputs/implementation-guide.md`.

Then give a 4–5 sentence summary covering:
- What product this guide is for
- The headline architectural decision
- The most important thing the critics changed
- One specific thing from the validation doc that shaped a key spec decision
- What to do next (paste the Master Prompt into an LLM and start building)

---

## Quality Standards

- **Every recommendation must trace back to the validation doc.** If a feature isn't
  grounded in a validated pain point, it shouldn't be in the MVP.
- **The Master Prompt must be copy-paste ready.** No placeholders left unfilled.
- **The User Flow must be specific.** "Dashboard" is not an Aha! Moment. Name the exact
  action and the exact feeling.
- **The Database Schema must be complete enough to start.** A developer should be able
  to write the first migration from it.
- **Voice of Customer language must appear in the PRD.** The Problem Statement and
  Persona descriptions should contain phrases from the validation doc, not cleaned-up
  founder language.