# Proposal

> [discovery-phase pack · deliverables] Generates a client-facing proposal document consolidating problem understanding, recommended approach, scope, assumptions, dependencies, team, timeline, and headline pricing guidance. Designed for pre-sale or paid-discovery conclusion. Produces proposal.md. Reads discovery-context.md and most upstream artifacts.

- Skill: `stanislavnianko/proposal` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add stanislavnianko/proposal`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stanislavnianko/proposal/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: stanislavnianko (https://skillmd.com/u/stanislavnianko)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stanislavnianko/proposal

---


# Proposal

> Part of the **discovery-phase** skill pack · `deliverables` group · reads `discovery-context.md` (run `profile-builder` first if missing).

Agency-to-client proposal document. The output the client reads, signs (or doesn't), and budgets against.

## Step 1 — Read context + prerequisites

Read `discovery-context.md` (sections **3. Engagement → Mode** — if mode is staff aug or internal, suggest `discovery-handoff` instead, but allow override; **5. Expected deliverable**).

**Prerequisite artifacts** — the proposal's substance:
- `scope-doc.md` — scope language
- `estimation.md` — effort + assumption list
- `risk-assumption-map.md` — risk register
- Recommended: `problem-canvas.md`, `opportunity-tree.md`

If `discovery-context.md` is missing, ask the BA inline: "(a) engagement mode (pre-sale / paid discovery / other); (b) client name + sector?" — tag `[ASSUMED]`. If 1–2 prerequisite artifacts are missing, ask for 3–5 stand-in bullets per artifact. If 3+ are missing, strongly recommend running the prerequisite skills first; otherwise proceed with `[ASSUMED <artifact>]` placeholders and a non-removable DRAFT-ONLY banner at the top of `proposal.md` (NOT for client send). Never block.

## Step 2 — Pick proposal style

| Style | When | Length |
|---|---|---|
| **Executive brief** | Senior client decision-maker, pre-sale, time-pressured | 2-3 pages |
| **Detailed proposal** | Procurement / RFP response, larger engagement | 8-12 pages |
| **Pitch deck** | Initial conversation; supplements verbal pitch | Doc + companion deck |

Default to **executive brief** unless context section 3 (Mode) implies RFP.

## Step 3 — Required sections (in this order)

1. **Cover** — engagement title, client name, agency name, date, version, primary contact
2. **TL;DR** — 3-4 bullets max. The client should be able to forward just this.
3. **Problem we'd solve** — one paragraph from `problem-canvas.md`, in client-language. NOT in agency-language.
4. **What we learned (if discovery happened already)** — 3-5 bullets from `insight-matrix.md` top-3 with one quote each. Supports the recommendation.
5. **Recommended approach** — what we'd build, why this and not alternatives. Pull from `opportunity-tree.md` chosen-direction. If client pre-proposed a different solution and our recommendation differs, **handle this section carefully** — see step 4.
6. **Scope** — pull "in" column from `scope-doc.md`. Include the success metrics.
7. **Out of scope** — pull "out" column + "explicitly deferred". Crucial — prevents post-contract scope wars.
8. **Approach / phases** — high-level timeline aligned to discipline matrix from `estimation.md`. Show milestones, not all tasks.
9. **Team** — who from agency works on what. Pull discipline columns from estimation.
10. **Timeline** — calendar weeks, key milestones, decision points
11. **Effort and pricing guidance** — from `estimation.md` adjusted total. **Range, not a number.** Specify whether fixed-fee, T&M, or phased.
12. **What we need from you** — the client-side assumptions and dependencies (from `scope-doc.md` outsourcing extras + `risk-assumption-map.md` `[client]`/`[shared]` rows)
13. **Risks and how we'll handle them** — from `risk-assumption-map.md` register, prioritized
14. **Assumptions** — verbatim from `estimation.md` "Assumptions that invalidate the estimate"
15. **Next steps** — concrete, signable: "we'll send a SoW within 5 business days of your verbal yes" or similar

## Step 4 — Handle "we recommend something different than client asked"

If `opportunity-tree.md` was Validate-mode and chose against client's pre-proposed solution:

- Section 5 **leads with empathy**: "You came to us with `<client's idea>`. Here's what we learned and where it took us."
- Section 5 **shows the alternatives** — including client's idea — with honest scoring.
- Don't pretend the client's idea was never on the table; that breaks trust.
- Pre-draft the BA-to-client conversation script as an appendix the BA can rehearse.

## Step 5 — Voice and tone

- Client-language, not agency-language. "We'll do X" → "We'll help you do Y for users".
- No internal jargon ("MVP", "v1", "story points"). Translate to client terms ("first release", "subsequent release", "effort estimate").
- Active voice. Short sentences. The client is busy.
- No buzzwords ("synergy", "leverage", "best-in-class"). They lower trust.

## Step 6 — Output

`./discovery/proposal.md` per `./template.md`.

Append to `_log.md`: `[proposal | YYYY-MM-DD] style: <executive/detailed/pitch>; total: <X-Y>; sent_to: <client contact>`.

## Anti-patterns

- **Buried scope.** Scope (and out-of-scope) are the two most-read sections. Don't hide them in section 11.
- **Single-number price.** Always range. Single number = commitment.
- **Hiding "what we need from you".** This is where the engagement actually lives or dies. Be explicit.
- **Including discovery's open questions** as "we'll figure this out". Either resolve them before proposal or surface them as risks.
- **Agency-internal language.** "Sprint 1, 2, 3" → "First 3 weeks". "Deliverable D1" → describe it in plain terms.
- **No alternatives in Validate-mode handling.** If you recommend differently than client asked, show your work. Hiding it = lost trust.