Prompt Design

# Prompt Design Rationale

This document explains *why* the prompts in the Idea Architect skill pack are shaped the way they are. If you're contributing a new skill or modifying an existing one, read this first to understand the design constraints.

---

## Table of Contents

1. [Design Goals](#design-goals)
2. [Structural Patterns](#structural-patterns)
3. [Tone and Voice](#tone-and-voice)
4. [Constraint Patterns](#constraint-patterns)
5. [Anti-Patterns](#anti-patterns)
6. [Per-Skill Design Notes](#per-skill-design-notes)

---

## Design Goals

The prompts in this pack pursue four goals, in priority order:

### 1. Determinism over creativity

The pipeline must produce the same structure of output for the same input, every time. Creativity is welcome *within* a section (e.g., generating 10 name candidates), but the section structure is fixed.

**Why**: Downstream skills parse the artifacts. If `brief.md` has a different structure each run, `spec.json` cannot be reliably produced.

**How**: Every skill specifies its output format with a template. The template is mandatory, not advisory.

### 2. Friction over speed

The pipeline deliberately adds friction. It would be faster to skip the 52-category audit, faster to skip the 15-persona debate, faster to skip the confirmation gate. We don't, because friction is the value.

**Why**: AI agents optimize for "be helpful and produce output fast". Without deliberate friction, they will skip discovery and jump to code. The pipeline's friction forces depth.

**How**: Numbered workflows, mandatory fields, quality checklists, decision points that halt the pipeline.

### 3. Specificity over abstraction

Every prompt asks for concrete outputs (specific names, specific hex codes, specific endpoints, specific folder paths). Generic abstractions are forbidden.

**Why**: "We use a relational database" is useless. "Postgres 16 on Neon, with row-level security for multi-tenancy, Drizzle ORM for migrations, and pgbouncer for connection pooling" is useful.

**How**: Every section requires specifics. Quality checklists reject vague answers.

### 4. Honesty over confidence

The pipeline is designed to surface unknowns, not paper over them. `[NEEDS CLARIFICATION]` is a first-class output. "I don't know yet" is a valid answer.

**Why**: An agent that guesses silently produces a spec that looks complete but isn't. The user trusts the spec, builds from it, and discovers the gaps in production.

**How**: Confidence scores, explicit assumption lists, escalation paths to Phase 11.

---

## Structural Patterns

### Pattern 1: Front-matter contract

Every skill file starts with YAML front-matter declaring the skill's contract: