technical_proposal_writing v1.0.0

name: technical_proposal_writing description: Write technical proposals and decision documents that get approved, with problem framing, costed options, risks, and rollout plans. Use when drafting, reviewing, or revising an internal proposal, design doc, RFC-style document, or decision record. metadata: { "includeInPrompt": true }

Technical Proposal Writing

Purpose

This skill produces internal technical proposals and decision documents that a reviewer can approve, reject, or send back with specific comments in one reading. A good proposal states the decision requested up front, grounds the problem in evidence, compares real options with real costs, names the risks, and says how the work rolls out, how it rolls back, and when the decision gets revisited.

Use it for design proposals, migration plans, tool or vendor selections, architecture changes, process changes with technical consequences, and any document where a team must pick one option and live with the result.

Related formats exist in the wild, including RFC-style comment rounds and architecture decision records that log a choice after it is made. This skill stays general: it covers the proposal before and during the decision, and it treats the final decision note as part of the same document. Adapt section names to local convention where a local convention exists.

Not this skill:

• grant-writing-basics covers funding applications to external grantmakers, not internal technical decisions.
• sop-writing covers procedures for repeated work, not one-off proposals.
• runbook-authoring covers operational runbooks for running and fixing live systems, not decision documents.
• op-ed-writing covers public persuasion for outside readers, not internal decision documents.
• press-release-writing covers public announcements to media and customers, not internal decision documents.

Workflow

1. Pin the decision before drafting. Write one sentence that names the decision, the decider or deciding group, and the date a decision is needed by. If no one can name the decider, stop and resolve that first. A proposal without a decider is a discussion paper, and it should be labeled as one.
2. Frame the problem with evidence. State what is wrong or missing, who or what it affects, and how often or how badly. Use measured evidence where it exists: incident counts, latency or error numbers, support tickets, cost figures, time spent on manual work. Label estimates as estimates and name their source. Separate observed facts from interpretation, and keep interpretation in its own short paragraph.
3. State constraints and non-goals. List the hard limits the solution must respect, such as budget caps, deadlines, compliance duties, supported platforms, and team capacity. List what the proposal does not try to solve. Non-goals prevent scope arguments during review.
4. Present at least two real options plus the status quo. The status quo is always an option, and its cost must be stated, even when that cost is continued pain rather than money. Each option gets the same treatment: what changes, what it costs to build, what it costs to run, what it costs to leave later, and which constraints it strains. An option no one would choose is padding; cut it.
5. Cost each option in the same units. Use ranges when exact figures are not known, and say what would narrow the range. Include build effort, ongoing operational effort, licence or service fees if any, migration effort, and the cost of delay. If a cost is unknown, write unknown and name who can supply it. Do not hide a weak spot inside a total.
6. Write the recommendation and the reason. Recommend one option and tie the reason to the evidence from step 2 and the costs from step 5. Name the strongest argument against the recommendation and answer it directly. Reviewers trust a proposal that states its own weak point.
7. Add a risk section. For each material risk, give the likelihood in plain words, the impact if it happens, the early signal that shows it is happening, and the mitigation planned. Cover technical risk, rollout risk, data risk, and dependency risk where they apply. A risk with no signal and no mitigation is a worry, not a plan; either complete it or move it to open questions.
8. Write the rollout plan. Give stages in order, with what ships at each stage, who does the work, how success is checked at each stage, and the point at which the rollout can still be stopped cheaply. Include any feature flag, canary, pilot group, or phased migration steps by name if the team already uses them. Avoid promising tooling the team does not have.
9. Write the rollback plan. State the trigger that causes a rollback, the exact steps in plain language, how long rollback takes, and what state data or users are left in after rollback. If rollback is not possible past a certain stage, say so plainly and name that stage. A proposal that claims rollback is easy without steps will be challenged, usually correctly.
10. Set the review and revisit terms. Name the reviewers whose comments are required, the comment window, and how comments are resolved: author revises, decider rules, or the point is logged as accepted disagreement. Add an expiry or revisit date on the decision itself. Conditions change, prices change, and a decision with a revisit date can be reopened without anyone losing face.
11. Handle comments by revision, not by argument in the margin. Group comments into accepted, rejected with reason, and needs a decision. Apply accepted changes, record rejected ones with a one-line reason in the document change log, and put unresolved points in front of the decider as a short list. Publish a revised version with a version note rather than editing silently.
12. Close the document when the decision lands. Record the decision, the date, who decided, and any conditions attached. If the decision is deferred, record what information is missing and the date it will be supplied. A closed proposal becomes the record the team checks later; keep it where the team keeps its other records, following local convention.
13. Run the completeness checker below on the draft before sending it for review. Fix every FAIL line. Treat WARN lines as prompts to check, not as automatic blocks.

Proposal template skeleton

Copy this skeleton and fill every section. Write "none" or "unknown, owner: role" where a section genuinely has nothing yet, rather than deleting the section.

markdown
# Proposal: [short title]
Status: draft / in review / approved / rejected / deferred
Decider: [role or group]
Decision needed by: [YYYY-MM-DD]
Revisit date: [YYYY-MM-DD]
Author: [role]
Version: [n, with date]

## Decision requested
[One or two sentences. The exact choice the decider is asked to make.]

## Problem
[What is wrong or missing. Who or what it affects. How often, how badly.]

## Evidence
- [Measured fact, with source and date.]
- [Measured fact, with source and date.]
- [Estimate, labeled as an estimate, with its basis.]

## Constraints and non-goals
- Constraint: [...]
- Non-goal: [...]

## Options
### Option A: Status quo
[What stays the same. Cost of staying, in money, time, or continued impact.]

### Option B: [name]
[What changes. Build cost. Run cost. Cost to leave later. Constraints strained.]

### Option C: [name]
[Same fields as Option B.]

## Recommendation
[Recommended option, the reason tied to evidence and costs, and the strongest
argument against it with a direct answer.]

## Risks
| Risk | Likelihood | Impact | Early signal | Mitigation |
| --- | --- | --- | --- | --- |
| [...] | [...] | [...] | [...] | [...] |

## Rollout plan
1. [Stage, what ships, who does it, how success is checked.]
2. [Stage, with the last cheap stopping point marked.]

## Rollback plan
- Trigger: [...]
- Steps: [...]
- Time to roll back: [...]
- State after rollback: [...]
- Point of no return, if any: [...]

## Open questions
- [Question, owner by role, date needed by.]

## Decision record
Decision: [pending]
Decided by: [...]
Date: [...]
Conditions: [...]

Completeness checker

Save the code below as check.py, then run it against a draft saved as a Markdown file:

bash
python3 check.py proposal.md

The checker looks for required sections, a revisit date in YYYY-MM-DD form, a decision record, and leftover placeholder markers. It prints one line per check and exits with code 1 when any required item is missing. It checks structure only. It cannot judge whether the evidence is sound or the costs are honest.

python
#!/usr/bin/env python3
"""Check a technical proposal draft for required sections.

Usage: python3 check.py proposal.md
Exit code 0 when all required checks pass, 1 otherwise.
Standard library only.
"""
import re
import sys

REQUIRED = [
    ("Decision requested", r"decision requested|decision required"),
    ("Problem", r"^#{1,4}\s+problem\b"),
    ("Evidence", r"evidence"),
    ("Constraints or non-goals", r"constraints|non-goals|non goals"),
    ("Options", r"^#{1,4}\s+options\b"),
    ("Status quo option", r"status quo|do nothing|current state"),
    ("Recommendation", r"recommendation|recommended"),
    ("Risks", r"^#{1,4}\s+risks?\b"),
    ("Rollout plan", r"rollout|roll-out|implementation plan"),
    ("Rollback plan", r"rollback|roll back|revert plan"),
    ("Open questions", r"open questions|unresolved"),
    ("Decision record", r"decision record|decision:"),
]

PLACEHOLDERS = ["TODO", "TBD", "FIXME", "XXX", "[...]"]


def main():
    if len(sys.argv) != 2:
        print("usage: python3 check.py proposal.md")
        return 2
    with open(sys.argv[1], "r", encoding="utf-8") as handle:
        text = handle.read()
    lowered = text.lower()
    failures = 0

    for label, pattern in REQUIRED:
        found = re.search(pattern, lowered, re.MULTILINE)
        status = "PASS" if found else "FAIL"
        if not found:
            failures += 1
        print(f"{status}: section present: {label}")

    date_match = re.search(r"revisit date:\s*(\d{4}-\d{2}-\d{2})", lowered)
    if date_match:
        print(f"PASS: revisit date found: {date_match.group(1)}")
    else:
        failures += 1
        print("FAIL: revisit date missing or not in YYYY-MM-DD form")

    needed_match = re.search(r"decision needed by:\s*(\d{4}-\d{2}-\d{2})", lowered)
    if needed_match:
        print(f"PASS: decision needed by date found: {needed_match.group(1)}")
    else:
        print("WARN: no 'Decision needed by' date in YYYY-MM-DD form")

    words = len(text.split())
    print(f"INFO: word count: {words}")
    if words < 150:
        print("WARN: draft is very short; evidence and costs are likely thin")

    for marker in PLACEHOLDERS:
        count = text.count(marker)
        if count:
            print(f"WARN: placeholder {marker!r} appears {count} time(s)")

    if failures:
        print(f"RESULT: {failures} required check(s) failed")
        return 1
    print("RESULT: all required checks passed")
    return 0


if __name__ == "__main__":
    sys.exit(main())

Worked example: save the template skeleton above as proposal.md, replace the two date placeholders with real dates in YYYY-MM-DD form, and run the checker. Verified on that filled skeleton: all 12 section checks pass, both date checks pass, and the checker exits with code 0. On a bare one-paragraph draft with no sections, all section checks fail and the checker exits with code 1. Structure can be checked early, while the writing is still cheap to change. Cost figures, risk quality, and evidence quality still need a human reader.

Output Contract

A finished run of this skill delivers:

• The proposal document itself, following the template skeleton, with every section present and placeholders either filled or marked unknown with an owner by role.
• A checker report: the PASS, FAIL, and WARN lines from check.py, plus a note of how each FAIL was fixed or why it was left.
• A decision summary of three to five lines for use in a message or meeting note: decision requested, recommendation, cost range of the recommended option, largest risk, and revisit date.
• A comment disposition list once review has happened: accepted changes, rejected comments with one-line reasons, and points put to the decider.
• After the decision, a completed decision record inside the proposal: decision, decider, date, conditions, and revisit date.

Length follows the decision. A small reversible choice can be one or two pages. A costly or hard to reverse choice needs the full treatment, and the document should say plainly which kind it is near the top.

Operating Rules

1. Lead with the decision. A reviewer who reads only the first section should know what is being asked, by when, and what the author recommends.
2. Evidence before opinion. Every problem claim carries a number, a dated observation, or a label that marks it as an estimate or an impression.
3. Always price the status quo. Doing nothing has a cost, and hiding that cost makes every other option look worse than it is.
4. Compare options in the same units and the same time horizon. Mixed units hide the tradeoff the decider is being asked to make.
5. State the strongest counterargument yourself. If the author will not name it, a reviewer will, and the proposal loses standing.
6. Never invent figures, incidents, benchmarks, or approval history to strengthen a case. Mark unknowns as unknown and name who can close them.
7. Rollback is a plan, not a reassurance. It needs a trigger, steps, a time estimate, and the state left behind. If there is a point of no return, name it.
8. Every decision carries a revisit date. Set it when conditions are likely to change, when a cost was estimated rather than measured, or when the decision was close.
9. Resolve comments in the document, not only in chat or in a meeting. The change log and disposition list are part of the record.
10. Write in plain, direct sentences. Short sections, clear headings, no padded introductions. A proposal earns approval on evidence and clarity, not on length.
11. Keep the document self-contained. A reader should not need a separate thread, ticket, or chat history to understand the problem, the options, or the decision.
12. Do not name individual people as blockers or as the cause of a problem. Refer to roles, teams, and systems. The document will outlive the current discussion and should stay fair to reread later.