Proposal Writing skill for Codex

A proposal succeeds when a busy decision-maker can read the first paragraph, know exactly what is being asked and why now, and find every objection they would raise already answered further down with numbers they can check. Persuasion comes from honesty about costs and alternatives, not from adjectives.

Establish the decision first

Before drafting, get answers to these (ask the user; do not invent them):

Question	Why it matters
Who decides, and who can block?	Sets vocabulary, depth, and which objections to pre-empt
What exactly is the ask? (money, people, time, permission)	The first sentence of the doc
By when is a decision needed, and what forces that date?	Creates honest urgency
What happens if nothing is done?	The baseline every option is compared against
What constraints are fixed? (budget cycle, headcount freeze, compliance)	Rules options in or out
What has already been tried or rejected?	Prevents re-proposing a known dead end

Read any existing proposal or planning template in the repo or docs folder and the company’s format conventions (often noted in AGENTS.md or a docs README). Use that format when it exists. Technical design detail belongs in $design-docs-rfcs; a short decision record for an already-agreed choice belongs in $decision-memos.

Workflow

- [ ] 1. Write the ask in one paragraph (who, what, how much, by when)
- [ ] 2. Describe the problem with evidence and the cost of doing nothing
- [ ] 3. Lay out 2-4 options including "do nothing", scored on the same criteria
- [ ] 4. Estimate costs and benefits with explicit assumptions and ranges
- [ ] 5. List risks with likelihood, impact, mitigation
- [ ] 6. Propose a staged plan with checkpoints and kill criteria
- [ ] 7. Write the executive summary last, then cut 20%
- [ ] 8. Run the objection pass

The ask

Lead with it. The reader should never reach page two wondering what you want.

We ask for approval to hire two platform engineers in Q3 (USD 410k fully loaded per
year) to move CI from self-hosted Jenkins to GitHub Actions by end of Q4. Decision
needed by 15 May to start hiring before the summer freeze.

Rules: a number, a date, a deliverable. No “explore”, “investigate options” or “begin a journey” unless the ask really is a funded discovery phase, in which case say its cost and what it will produce.

Problem and cost of doing nothing

• Use the decision-maker’s metrics: money, time, risk, customer impact, team capacity.
• Show evidence: “CI queue p50 is 22 min, p90 is 71 min (last 90 days, Jenkins metrics)”, not “CI is slow”.
• Translate into cost: 22 min x 140 runs/day x 60 engineers’ share of waiting = hours per week. Show the arithmetic so the reader can disagree with an input instead of the whole conclusion.
• Explain why now: a contract renewal, a scaling cliff, a compliance deadline, a competitor move. If nothing forces the timing, say so honestly and argue on value.

Options

Always include “do nothing / status quo” and at least one cheaper alternative. A proposal with a single option reads as a foregone conclusion and invites the reader to invent alternatives you have not costed.

| Criterion (weight) | Do nothing | Upgrade Jenkins | Move to GitHub Actions | Buy CircleCI |
|---|---|---|---|---|
| 1-yr cost | $0 + $180k waiting time | $90k | $410k + $60k runners | $240k |
| Time to benefit | - | 2 months | 5 months | 3 months |
| Queue time p90 target | 71 min | ~40 min | < 15 min | < 15 min |
| Ops burden after | High | High | Low | Low |
| Lock-in risk | - | Low | Medium | Medium |
| Recommendation | | | Yes | Close second |

State why the runner-up lost in one sentence. If the decision is close, say so; credibility is worth more than a lopsided table.

Costs and benefits

• Separate one-time and recurring costs. Include people time, licenses, migration effort, training, and the cost of running old and new in parallel.
• Give ranges with a base case: “payback in 9-16 months, base case 11”. Point estimates invite false precision.
• List assumptions in a numbered block so reviewers can attack an assumption by number:

**Assumptions**
A1. Fully loaded engineer cost USD 205k/year (finance 2026 planning rate)
A2. Queue time drops to 15 min p90 (vendor benchmark; validated in pilot, stage 1)
A3. 30% of waiting time converts to productive work (conservative; literature varies)

• Run a sensitivity check on the one or two assumptions that drive the result: “If A3 is 15% instead of 30%, payback moves to 20 months; still positive within the contract term.”
• Benefits that cannot be quantified (morale, hiring signal) go in a separate list and never get folded into the ROI number.
• Financial figures are estimates for planning. If the proposal will be used for budgeting or accounting treatment (capex vs opex), note that finance must confirm the numbers.

Risks

Risk	Likelihood	Impact	Mitigation	Owner
Hiring takes longer than 3 months	Medium	Delays Q4 date	Start with one contractor in stage 1	Eng manager
Pipeline parity gaps found late	Medium	Rework	Migrate the 3 hardest pipelines first	Platform lead

Include the risk of the proposal itself failing and what it would cost to unwind.

Plan with checkpoints

Stage the spend so the decision-maker can approve a small first step:

**Stage 1 (6 weeks, $40k):** migrate 3 hardest pipelines; measure p90 queue time.
Continue if p90 < 20 min and no blocking parity gap. Stop otherwise; cost is sunk at $40k.
**Stage 2 (Q3):** hire, migrate remaining 80 pipelines.
**Stage 3 (Q4):** decommission Jenkins; renewal not signed.

Kill criteria are what make a large ask approvable: they cap the downside.

Structure

# <Proposal title as an outcome: "Cut CI wait time by 80% by Q4">
**Ask:** <one paragraph>   **Decision by:** <date>   **Decider:** <role>
**Author:** <name>   **Status:** draft | in review | decided

## Summary (5 sentences max)
## Problem and cost of doing nothing
## Options considered
## Recommendation and why
## Costs, benefits and assumptions
## Risks
## Plan, milestones and kill criteria
## What we need from you
## Appendix: data sources, calculations, prior attempts

Target two pages before the appendix for most internal asks. Put supporting detail in the appendix rather than cutting the evidence.

Objection pass

Reread as the most skeptical stakeholder and answer each in the doc:

• Why not the cheaper option? Why not later? Why us and not another team?
• What if the key assumption is wrong? What stops the spend if it is failing?
• What else does this displace? (Name the work that will not happen.)
• Who is affected who has not been consulted?

Gotchas

• Burying the ask under background. The background is for the appendix.
• Inflated benefits. One number that a finance reviewer can disprove discredits the rest.
• Strawman alternatives costed to lose. Reviewers notice; cost them fairly.
• Vague language (“significant”, “dramatically”, “best-in-class”). Replace with numbers or delete.
• Sending the proposal to stakeholders or posting it is outward-facing: show the final text to the user and get a clear yes before sending anything.

Verification

• The first paragraph alone answers: what, how much, by when, who decides.
• Every number has a source or a numbered assumption; arithmetic is shown and rechecked.
• The options table includes “do nothing” and uses identical criteria for every column.
• There is at least one checkpoint with explicit continue/stop criteria.
• The draft is under the target length; read the summary aloud in under 60 seconds.