# Phase 4.5: Founder Signal Synthesis

Before writing the design doc, synthesize the founder signals you observed during the session. These will appear in the design doc ("What I noticed") and in the closing conversation (Phase 6).

## Contents

- [Startup mode design doc template:](#startup-mode-design-doc-template)
- [Problem Statement](#problem-statement)
- [Demand Evidence](#demand-evidence)
- [Status Quo](#status-quo)
- [Target User & Narrowest Wedge](#target-user-narrowest-wedge)
- [Constraints](#constraints)
- [Premises](#premises)
- [Adversarial Perspective](#adversarial-perspective)
- [Approaches Considered](#approaches-considered)
  - [Approach A: {name}](#approach-a-name)
  - [Approach B: {name}](#approach-b-name)
- [Recommended Approach](#recommended-approach)
- [Open Questions](#open-questions)
- [Success Criteria](#success-criteria)
- [Distribution Plan](#distribution-plan)
- [Dependencies](#dependencies)
- [The Assignment](#the-assignment)
- [What I noticed about how you think](#what-i-noticed-about-how-you-think)
- [Builder mode design doc template:](#builder-mode-design-doc-template)
- [Problem Statement](#problem-statement)
- [What Makes This Cool](#what-makes-this-cool)
- [Constraints](#constraints)
- [Premises](#premises)
- [Adversarial Perspective](#adversarial-perspective)
- [Approaches Considered](#approaches-considered)
  - [Approach A: {name}](#approach-a-name)
  - [Approach B: {name}](#approach-b-name)
- [Recommended Approach](#recommended-approach)
- [Open Questions](#open-questions)
- [Success Criteria](#success-criteria)
- [Distribution Plan](#distribution-plan)
- [Next Steps](#next-steps)
- [What I noticed about how you think](#what-i-noticed-about-how-you-think)
- [Spec Review Loop](#spec-review-loop)


Track which of these signals appeared during the session:
- Articulated a **real problem** someone actually has (not hypothetical)
- Named **specific users** (people, not categories — "Sarah at Acme Corp" not "enterprises")
- **Pushed back** on premises (conviction, not compliance)
- Their project solves a problem **other people need**
- Has **domain expertise** — knows this space from the inside
- Showed **taste** — cared about getting the details right
- Showed **agency** — actually building, not just planning
- **Defended premise with reasoning** against the second-opinion challenge (kept original premise when the subagent disagreed AND articulated specific reasoning for why — dismissal without reasoning does not count)

Count the signals. You'll use this count in Phase 6 to determine which tier of closing message to use.

---

# Phase 5: Design Doc

Write the design document to the project directory.

```bash
eval "$(.claude/scripts/bin/workflow-slug 2>/dev/null)" && mkdir -p .claude/memory/projects
USER=$(whoami)
DATETIME=$(date +%Y%m%d-%H%M%S)
```

**Design lineage:** Before writing, check for existing design docs on this branch:
```bash
PRIOR=$(ls -t .claude/memory/projects/*-$BRANCH-design-*.md 2>/dev/null | head -1)
```
If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across office hours sessions.

Write to `.claude/memory/projects/{slug}/{user}-{branch}-design-{datetime}.md`:

## Startup mode design doc template:

```markdown
# Design: {title}

Generated by /mk:office-hours on {date}
Branch: {branch}
Repo: {owner/repo}
Status: DRAFT
Mode: Startup
Supersedes: {prior filename — omit this line if first design on this branch}

## Problem Statement
{from Phase 2A}

## Demand Evidence
{from Q1 — specific quotes, numbers, behaviors demonstrating real demand}

## Status Quo
{from Q2 — concrete current workflow users live with today}

## Target User & Narrowest Wedge
{from Q3 + Q4 — the specific human and the smallest version worth paying for}

## Constraints
{from Phase 2A}

## Premises
{from Phase 3}

## Adversarial Perspective
{If the second-opinion subagent ran in Phase 3.5: its independent cold read — steelman, key insight, challenged premise, prototype suggestion. Verbatim or close paraphrase. If it did NOT run (user skipped): omit this section entirely.}

## Approaches Considered
### Approach A: {name}
{from Phase 4}
### Approach B: {name}
{from Phase 4}

## Recommended Approach
{chosen approach with rationale}

## Open Questions
{any unresolved questions from the office hours}

## Success Criteria
{measurable criteria from Phase 2A}

## Distribution Plan
{how users get the deliverable — binary download, package manager, container image, web service, etc.}
{CI/CD pipeline for building and publishing — GitHub Actions, manual release, auto-deploy on merge?}
{omit this section if the deliverable is a web service with existing deployment pipeline}

## Dependencies
{blockers, prerequisites, related work}

## The Assignment
{one concrete real-world action the founder should take next — not "go build it"}

## What I noticed about how you think
{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
```

## Builder mode design doc template:

```markdown
# Design: {title}

Generated by /mk:office-hours on {date}
Branch: {branch}
Repo: {owner/repo}
Status: DRAFT
Mode: Builder
Supersedes: {prior filename — omit this line if first design on this branch}

## Problem Statement
{from Phase 2B}

## What Makes This Cool
{the core delight, novelty, or "whoa" factor}

## Constraints
{from Phase 2B}

## Premises
{from Phase 3}

## Adversarial Perspective
{If the second-opinion subagent ran in Phase 3.5: its independent cold read — coolest version, key insight, existing tools, prototype suggestion. Verbatim or close paraphrase. If it did NOT run (user skipped): omit this section entirely.}

## Approaches Considered
### Approach A: {name}
{from Phase 4}
### Approach B: {name}
{from Phase 4}

## Recommended Approach
{chosen approach with rationale}

## Open Questions
{any unresolved questions from the office hours}

## Success Criteria
{what "done" looks like}

## Distribution Plan
{how users get the deliverable — binary download, package manager, container image, web service, etc.}
{CI/CD pipeline for building and publishing — or "existing deployment pipeline covers this"}

## Next Steps
{concrete build tasks — what to implement first, second, third}

## What I noticed about how you think
{observational, mentor-like reflections referencing specific things the user said during the session. Quote their words back to them — don't characterize their behavior. 2-4 bullets.}
```

---

## Spec Review Loop

Before presenting the document to the user for approval, run an adversarial review.

**Step 1: Dispatch reviewer subagent**

Use the Agent tool to dispatch an independent reviewer. The reviewer has fresh context
and cannot see the brainstorming conversation — only the document. This ensures genuine
adversarial independence.

Prompt the subagent with:
- The file path of the document just written
- "Read this document and review it on 5 dimensions. For each dimension, note PASS or
  list specific issues with suggested fixes. At the end, output a quality score (1-10)
  across all dimensions."

**Dimensions:**
1. **Completeness** — Are all requirements addressed? Missing edge cases?
2. **Consistency** — Do parts of the document agree with each other? Contradictions?
3. **Clarity** — Could an engineer implement this without asking questions? Ambiguous language?
4. **Scope** — Does the document creep beyond the original problem? YAGNI violations?
5. **Feasibility** — Can this actually be built with the stated approach? Hidden complexity?

The subagent should return:
- A quality score (1-10)
- PASS if no issues, or a numbered list of issues with dimension, description, and fix

**Step 2: Fix and re-dispatch**

If the reviewer returns issues:
1. Fix each issue in the document on disk (use Edit tool)
2. Re-dispatch the reviewer subagent with the updated document
3. Maximum 3 iterations total

**Convergence guard:** If the reviewer returns the same issues on consecutive iterations
(the fix didn't resolve them or the reviewer disagrees with the fix), stop the loop
and persist those issues as "Reviewer Concerns" in the document rather than looping
further.

If the subagent fails, times out, or is unavailable — skip the review loop entirely.
Tell the user: "Spec review unavailable — presenting unreviewed doc." The document is
already written to disk; the review is a quality bonus, not a gate.

**Step 3: Report and persist metrics**

After the loop completes (PASS, max iterations, or convergence guard):

1. Tell the user the result — summary by default:
   "Your doc survived N rounds of adversarial review. M issues caught and fixed.
   Quality score: X/10."
   If they ask "what did the reviewer find?", show the full reviewer output.

2. If issues remain after max iterations or convergence, add a "## Reviewer Concerns"
   section to the document listing each unresolved issue. Downstream skills will see this.

3. Append metrics:
```bash
mkdir -p .claude/memory
echo '{"skill":"office-hours","ts":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'","iterations":ITERATIONS,"issues_found":FOUND,"issues_fixed":FIXED,"remaining":REMAINING,"quality_score":SCORE}' >> .claude/memory/spec-review.jsonl 2>/dev/null || true
```
Replace ITERATIONS, FOUND, FIXED, REMAINING, SCORE with actual values from the review.

---

Present the reviewed design doc to the user via AskUserQuestion:
- A) Approve — mark Status: APPROVED and proceed to handoff
- B) Revise — specify which sections need changes (loop back to revise those sections)
- C) Start over — return to Phase 2