Charter to Code

01

Project Charter {human}

Align on the problem before writing a line of code

▸

"The charter answers WHY you're building this. It's the one-page document that aligns everyone on the problem, the customer, and the goal."

Goal: Align everyone on the problem, the customer, and the goal before writing a single line of code.

The 5 Questions a Charter Answers

Who has the problem? (Target Customer)
What's the pain? (Problem Statement)
What does success look like? (Goal + Metrics)
What's in and what's out? (Scope)
How long do we have? (Timeline)

Voice of Customer

Direct quotes from your target users reveal the underlying needs that drive every design decision. Every feature you build should trace back to a VOC quote.

"I don't want to get asked for the same thing multiple times."

Underlying Need: Streamlined document collection with persistent storage

"Why did you go dark on me?"

Underlying Need: Real-time status visibility throughout the deal lifecycle

"Why did my terms change?"

Underlying Need: Immutable, auditable term records with change tracking

"Too many cooks in the kitchen — who has the ball right now?"

Underlying Need: Clear ownership and role-based workflow progression

Target Market: Specific Avatars, Not Generic Roles

Don't build for "brokers" — build for Mike. Specific avatars drive specific design decisions.

Mike the Broker

15 years experience, 6 deals in flight simultaneously. Needs speed and transparency. His pain: chasing status updates, re-uploading the same documents, and discovering at closing that the terms changed.

David the CIO

Reviews 20+ deals per month across a diverse portfolio. Needs a standardized process and quick risk assessment. His pain: inconsistent deal presentation and time spent reading instead of deciding.

User Story Cards {human+machine}

Write a day-in-the-life narrative for each avatar. This is where VOC quotes become features.

Mike the Broker

Mike gets a link to the portal. He clicks "Submit New Deal" and sees a single form — property address, loan amount, sponsor info, deal metrics, and a document upload checklist. Everything is on one page. He fills it out in 20 minutes, uploads his documents, and hits Submit. He gets a confirmation with a reference number. The next day, he logs in and sees his deal status. Two days later, terms arrive. He acknowledges them and the deal moves forward. He never got asked for the same document twice. He never had to chase status updates. His terms didn't change.

VOC solved: #1 (asked once), #4 (never went dark), #5 (status visible), #6 (everything at once)

David the CIO

David opens the portal and sees his pipeline — 12 active deals, 3 pending review. He clicks on a deal and sees 10 completed vetting steps, KPI metrics with Pass/Warn/Flag badges, and all uploaded documents. LTV is flagged at 72%. He clicks "Pass" with a note. The deal moves forward. Later, the AI Underwriter runs and gives him a 62/100 score with a "Needs Review" recommendation and a 3-paragraph narrative explaining why. He makes his decision in 5 minutes without reading a 50-page write-up.

VOC solved: #3 (documented process), #9 (clear ownership)

Sarah the Underwriter

Sarah opens a deal that just passed terms alignment. All the borrower's documents are in the sidebar — tax returns, P&L, balance sheet, PFS, lease agreements. She clicks the AI button and the system flags the two highest-risk items and asks her 5 targeted follow-up questions. She types her answers and watches the risk score update in real time. When the session completes, she gets a narrative she can attach to the deal summary for the CIO.

VOC solved: #2 (no surprises), #6 (everything in one place)

Prompt Example

Docs to provide: Your draft notes — rough answers to the 5 questions, any VOC quotes you've collected, scope ideas

Copy this prompt → paste into Claude

I've drafted the following notes for my project. Please formalize them into a complete Project Charter in markdown format. [Paste your draft notes here — bullet points, rough answers, VOC quotes you've collected, scope ideas, anything you have] Structure the charter with these exact sections: 1. Project Purpose — why this needs to exist (2-3 sentences) 2. Target Customer — named avatars with role, experience level, and specific pain points 3. Problem Statement — what's broken today (be specific) 4. Goal Statement — one sentence defining success 5. Key Metrics — 1 primary metric, 2 secondary metrics 6. Voice of Customer — each quote on its own line, followed by the underlying need it reveals 7. Scope — explicit In/Out table for MVP 8. Timeline — milestone → target date format 9. Assumptions & Constraints Keep my original language wherever possible. If anything is missing or unclear, ask before filling it in yourself. Save this as PROJECT_CHARTER.md and add it to the project.

02

Business Requirements Document {machine}

Translate WHY into numbered, testable requirements

▸

"The BRD translates the charter's WHY into specific, numbered requirements. Each requirement is testable — you can look at it and answer: did we build this? Yes or no."

Goal: Translate the charter's WHY into numbered, testable requirements that drive every build decision.

The Requirement Writing Pattern

"The system shall [do what] [for whom] [under what conditions] [with what outcome]."

Example Requirements at Three Levels

FR-001a — Simple

The property address shall be captured as four separate fields: Street Address, City, State (dropdown), and ZIP Code — all required.

FR-018a — Workflow

The portal shall provide an 'Acknowledge Terms' action that records acceptance, updates deal status to TAP_COMPLETE, and notifies the underwriting team.

FR-062 — Complex

The scoring engine shall calculate the composite risk score using a two-tier weighted model: category-level weights (must sum to 100%) and per-input weights within each category (must sum to 100% within their category).

Prompt Example

Docs to provide: PROJECT_CHARTER.md — attach to Claude before running this prompt

Copy this prompt → paste into Claude

I am sharing my Project Charter [attached as PROJECT_CHARTER.md]. Please create a Business Requirements Document (BRD) using the charter as your primary source. Build it section by section: 1. Executive Summary — what the system does in 2 paragraphs 2. Business Context — pull the problem, users, and success metrics directly from the charter 3. User Personas — one paragraph per avatar from the charter's Target Customer section. Use the exact names and details. 4. Functional Requirements — numbered FR-001, FR-002, etc., organized by feature area. Rules: - Pattern: "The system shall [do what] [for whom] [under what conditions]." - Every requirement must trace to a specific VOC quote or user story from the charter. Note which one. - Priority: Must Have / Should Have / Nice to Have - If a requirement cannot be traced to a VOC quote or user need in the charter, do not include it. 5. Non-Functional Requirements — performance, security, access control by role 6. System Architecture — specific technologies (not categories), database models, API surface 7. Out of Scope — what is explicitly NOT in MVP Save this as BRD.md and add it to the project.

▶ Evaluation Loop

Before moving to the FFD, open a new Claude conversation, attach the Charter, BRD, and Evaluation Protocol, and run this prompt. The evaluation protocol enforces no-sugarcoat, position-first feedback.

Docs to provide in the new chat: PROJECT_CHARTER.md + BRD.md + EVALUATION-PROTOCOL.md

Eval prompt → new Claude chat

I'm providing three documents: Project Charter, Business Requirements Document, and an Evaluation Protocol. Evaluate the BRD against the charter using the Evaluation Protocol. Assess: 1. Does every functional requirement trace to a specific VOC quote or user story in the charter? Show the trace, or flag the gap. 2. Are any charter user stories or VOC quotes not covered by any requirement? 3. Are any requirements not testable as a clear yes/no? 4. Are any requirements present that don't serve a documented user need? 5. Does the system architecture match the scale implied by the charter? Follow the protocol exactly: take a position, argue in favor, argue against, provide alternatives, give a recommendation.

BRD Evaluation Checklist

Quick self-check before the eval loop.

03

Feature / Function List {machine}

Break requirements into developer-ready specifications

▸

"The FFD takes each BRD requirement and breaks it into developer-ready function specs. Where the BRD says WHAT, the FFD says HOW — specifically."

Goal: Break each requirement into developer-ready function specifications with enough detail to build without clarification.

The BRD-to-FFD Mapping

One BRD requirement often produces multiple FF entries. FR-001 (intake form) becomes five separate functions:

FF-ID	Feature	Function	BRD Ref	Priority
FF-001	Intake form	Render single-page form with property, loan, and sponsor sections	FR-001	Must Have
FF-002	Document checklist	Display required documents with upload slots and completion status	FR-001	Must Have
FF-003	Form validation	Validate all required fields on blur; show inline error on empty submit	FR-001	Must Have
FF-102	Config renderer	Fetch form field config from API; render fields dynamically from JSON schema	FR-001	Should Have
FF-103	Intake fields API	GET /api/intake/config returns field definitions, validation rules, and options	FR-001	Should Have

Prompt Example

Docs to provide: PROJECT_CHARTER.md + BRD.md — attach both before running this prompt

Copy this prompt → paste into Claude

I am sharing my Project Charter and BRD [both attached]. Read both documents before proceeding. Please create a Feature/Function List (FFD) that breaks every functional requirement from the BRD into developer-ready specifications. Output as a markdown table: | FF-ID | Feature | Function | BRD Ref | User Role | Priority | Notes | Rules: - FF-ID: sequential (FF-001, FF-002...) - Feature: short name (2-3 words) - Function: one precise sentence — specific enough that a developer can implement it without asking questions - BRD Ref: the exact FR number from the BRD (required) - User Role: the avatar name from the charter who uses this - Priority: inherit from BRD requirement - Notes: API endpoint with HTTP method, validation rules, error states, edge cases One BRD requirement may produce multiple FF entries. Flag any FR that has no corresponding FF entry. Save this as FFD.md and add it to the project.

▶ Evaluation Loop

Open a new Claude conversation, attach the BRD, FFD, and Evaluation Protocol, and run this prompt.

Docs to provide in the new chat: BRD.md + FFD.md + EVALUATION-PROTOCOL.md

Eval prompt → new Claude chat

I'm providing three documents: BRD, Feature/Function List, and an Evaluation Protocol. Evaluate the FFD against the BRD using the Evaluation Protocol. Assess: 1. Does every FR have at least one corresponding FF entry? List any FR with no FF entry. 2. Is each FF function description specific enough for a developer to implement without asking questions? Flag any that are vague. 3. Are API endpoints defined for every feature that reads or writes data? 4. Are error states and validation rules documented in Notes? 5. Is the user role clear for every FF entry? Follow the protocol: take a position, argue in favor, argue against, provide alternatives, give a recommendation.

FFD Evaluation Checklist

Quick self-check before the eval loop.

04

Process Maps {machine}

Trace the exact flow of data and decisions through the system

▸

"Process maps trace the exact flow of data and decisions through the system. They answer: when a user clicks this button, what happens on the server, what changes in the database, and what does the user see next?"

Goal: Trace the exact flow of data and decisions so developers and testers share the same mental model.

Example: Deal Intake Flow

User clicks "Submit New Deal" → Page loads, fetches config from GET /api/intake/config → Form renders with dynamic fields from config JSON → On each field blur → auto-saves draft to PATCH /api/deals/:id → On submit → validates required fields client-side → POST /api/deals/:id/submit → Server validates all required fields server-side → Server maps form values to Deal database columns → Transitions status: DRAFT → SUBMITTED → Generates reference number (UUID prefix + timestamp) → Sends confirmation email to broker → Client receives 200 with { referenceNumber, dealId } → Confirmation screen shown with reference number → Internal pipeline link hidden from broker role

State Machine

Every deal status transition must be explicit. No "orphan" statuses — every state has a defined entry condition and exit path.

DRAFT

→

SUBMITTED

→

UNDER_REVIEW

→

TERMS_SENT

→

TAP_COMPLETE

Prompt Example

Docs to provide: BRD.md + FFD.md — attach both before running this prompt

Copy this prompt → paste into Claude

I am sharing my BRD and FFD [both attached]. Read both documents before proceeding. Please create Process Maps for every major user workflow. Number them sequentially (Map 1, Map 2...). For each map: 1. Name: "Map N — [Workflow Name]" 2. Actors: which user role(s) are involved 3. FR/FF References: which requirement numbers this implements 4. Flow: indented step-by-step sequence: - User action (click, type, select) - Client request (HTTP method + endpoint + payload) - Server logic (validation, business rules, DB writes) - State transition (if status changes, name old → new) - User sees (screen, message, redirect) 5. Decision branches: every if/then path with else conditions 6. Error handling: every failure mode and what the user sees End with a complete State Machine section listing every valid status, what triggers it, and what triggers the next. Save this as PROCESS_MAPS.md and add it to the project.

Process Map Evaluation Checklist

Before moving to code, verify your maps are complete.

05

Design & Code {machine}

Build one file, test it, confirm it works, move to the next

▸

"This is where AI builds the application. The key insight: you don't ask the AI to 'build me an app.' You give it the documents you've already written and ask it to implement specific, numbered features."

Goal: Build the application incrementally, one file at a time, with precise instructions that minimize AI drift.

The Prompt Structure

Context — what already exists and is working
Specificity — exactly what file to build and what it should do
Constraints — what must not change

Without all three, the AI will make decisions you haven't made. That's how bugs appear in code you didn't touch.

Real Example: The AI Start Route Rewrite

An actual prompt from the HDF portal build. The prior version was hallucinating loan amounts because the prompt didn't pass explicit values.

PROJECT: HDF Portal STACK: Next.js 14, Prisma, PostgreSQL, OpenAI WHAT'S BUILT: - Authentication (NextAuth, working) - Deal intake form (working) - Document upload to S3 (working) - CIO dashboard and deal review (working) - Basic AI vetting stub (broken — hallucinating deal data) WHAT TO BUILD NOW: File: app/api/ai/start/route.ts - Accept dealId and sessionType in request body - Load deal data from database including borrower, property, documents, and all KPI metrics - Build structured prompt that includes all deal metrics explicitly — do NOT rely on the AI to infer values - Create a new AISession record with status ACTIVE - Return sessionId and initial questions array CRITICAL CONSTRAINTS: - Do not modify the existing AISession Prisma schema - Do not touch app/api/ai/continue/route.ts - The prompt must pass loan amount, LTV, and credit score as explicit values, not as context for inference REFERENCE: Implements FR-045, FR-046 (AI Session Management) FF-089, FF-090 (AI Start Route, Session Initialization) Build this one file. Do not modify any other files. Confirm when complete.

Sprint Plan

Sprint	What Was Built
Sprint 1	Authentication (NextAuth), database schema (Prisma + PostgreSQL), role system: Broker, CIO, Underwriter, Admin
Sprint 2	Broker intake form, document upload (S3), deal submission + reference number generation, broker status dashboard
Sprint 3	CIO pipeline dashboard, deal detail view, KPI vetting with Pass/Warn/Flag badges, terms sending + acknowledgment
Sprint 4	AI vetting engine, two-tier composite risk scoring model, scoring configuration UI for Admin
Sprint 5	Underwriting workflow, AI session (start, continue, complete), session resumability, narrative generation
Sprint 6	UAT bug fixes, role-based access hardening, email notifications, performance tuning, production deployment

The File-by-File Pattern

Build one file. Test it. Confirm it works. Move to the next. Never ask the AI to build multiple files in a single prompt — it will hallucinate connections between them and create subtle bugs that are hard to trace.

Project Kickoff Prompt

Use this prompt once — at the very start — to orient Claude to the full project before any code is written. Attach all four documents.

Docs to provide: PROJECT_CHARTER.md + BRD.md + FFD.md + PROCESS_MAPS.md — attach all four before running

Kickoff prompt → paste into Claude Code

PROJECT: [Your project name] STACK: [Your stack — e.g., Next.js 14, Prisma, PostgreSQL] CONTEXT: I have attached four planning documents. Read all of them before writing a single line of code: - PROJECT_CHARTER.md - BRD.md - FFD.md - PROCESS_MAPS.md BEFORE YOU WRITE ANYTHING, confirm you've read all four documents and tell me: 1. The 3 most critical user workflows you identified 2. Every database entity and its key relationships 3. The role model — who can access what 4. Which file you will create first, and why THEN BUILD SPRINT 1 ONLY: Authentication + database schema + base routing. No feature UI yet. Foundation only. BUILD RULES — apply for the entire project: - Every function you write must reference its FR or FF number in a comment - Build one file at a time. Stop and confirm before moving on. - Never modify a file we've already confirmed as working - If a requirement is ambiguous, ask — do not guess - State what you're about to build before you build it Start by confirming you've read all documents. State your Sprint 1 build plan. Then begin.

06

User Acceptance Testing {human}

Verify every requirement works as the actual user, not the developer

▸

"UAT is where you walk through the application as each user role and verify every requirement works."

Goal: Verify that every requirement works as the actual user, not the developer, before calling it done.

Test Cases

Test 1 — Broker Deal Submission

Login as broker → Submit deal → Verify confirmation screen shows reference number and NO internal pipeline link.

Why the last part matters: The pipeline link is CIO-only. If the broker sees it, role-based access is broken. Test what shouldn't be there, not just what should.

Test 2 — CIO Deal Review

Login as CIO → Open deal → Verify all deal data visible → Click Pass on QVP → Verify status transitions from UNDER_REVIEW to TERMS_SENT.

The status transition is the requirement. The button working is not enough — confirm the database changed.

Test 3 — AI Session Persistence

Start AI session → Answer 2 questions → Navigate away → Return to deal → Verify session restored with prior answers intact.

Session resumability was a hard requirement. Test it explicitly, not as an afterthought.

Bugs Found During HDF UAT

BUG 01

AI hallucinated the loan amount

Root cause: The AI start route wasn't passing the actual loan amount — it was asking the AI to "use the deal context." The AI invented a plausible number and used it consistently throughout the session.

Lesson: Always pass explicit values. Never ask AI to infer data you already have in the database.

BUG 02

Admin save failed silently on all screens

Root cause: The admin API routes used a different field naming convention than the frontend forms. Every save returned 200 but no data changed. Invisible until someone checked the database directly.

Lesson: Test the save, not just the display. A successful API response doesn't mean the right data was written.

BUG 03

Broker couldn't see their own documents after submission

Root cause: The document API was admin-only by default. The broker role was never added to the allowlist. The broker could upload but couldn't view — and got no error explaining why.

Lesson: Test as every role. An admin seeing it correctly means nothing about what the broker sees.

Prompt Example

Docs to provide: BRD.md + FFD.md — attach both before running this prompt

Copy this prompt → paste into Claude

I am sharing my BRD and FFD [both attached]. Read both documents before proceeding. Please generate a complete UAT test script. For each test: TEST ID: T-001, T-002... ROLE: which user role executes this test PRECONDITIONS: what data must exist, what state the system is in STEPS: numbered actions (click X, enter Y, verify Z) EXPECTED RESULT: specific, observable outcome at each step PASS CRITERIA: exactly what constitutes a pass FAIL CRITERIA: exactly what constitutes a fail Cover: - Every major workflow in the FFD (reference FF numbers) - Happy path for each user role - Role-based access: verify each role CANNOT see what they should not — not just that they CAN see what they should - Invalid input and error handling - Empty states and edge cases - Session persistence: navigate away, return, verify state Flag any FF entry that has no corresponding test case.

The 5 Questions a Charter Answers

Voice of Customer

Target Market: Specific Avatars, Not Generic Roles

User Story Cards {human+machine}

Prompt Example

The Requirement Writing Pattern

Example Requirements at Three Levels

Prompt Example

The BRD-to-FFD Mapping

Prompt Example

Example: Deal Intake Flow

State Machine

Prompt Example

The Prompt Structure

Real Example: The AI Start Route Rewrite

Sprint Plan

The File-by-File Pattern

Project Kickoff Prompt

Test Cases

Bugs Found During HDF UAT

Prompt Example

Want to work with Jeremy on a project?

Learn it by watching it