one-pager

What this skill does

# One-Pager Engineering Proposal Skill

## Overview

This skill guides engineers through the process of creating a compelling one-pager proposal using the Heilmeier Catechism framework. The goal is not to immediately produce a document, but to **thoroughly understand the problem space first**, then distill that understanding into a single page that earns every word.

A one-pager is a thinking tool, not a template. The constraint is the feature.

## When to Use This Skill

Use this skill when an engineer needs to:
- Get buy-in for a technical change or new approach
- Align stakeholders before writing an RFC or design doc
- Move a Slack debate toward a decision
- Propose a solution to an operational issue
- Justify resource allocation for a project

## Two Modes

### 1. Draft Mode (No existing document)
Guide the user through a structured interview to collect all necessary information, explore the codebase, and build supporting documents before distilling into a one-pager.

### 2. Critique Mode (Existing document)
Analyze an existing one-pager, identify gaps and weaknesses, and guide the user through targeted questions to strengthen it.

---

## The Heilmeier Catechism

This skill uses the Heilmeier Catechism as its primary framework. Developed by former DARPA director George Heilmeier, these eight questions force clarity:

1. **What are you trying to do?** Articulate objectives using absolutely no jargon.
2. **How is it done today, and what are the limits of current practice?**
3. **What is new in your approach and why do you think it will be successful?**
4. **Who cares? If you are successful, what difference will it make?**
5. **What are the risks?**
6. **How much will it cost?** (time, money, resources, opportunity cost)
7. **How long will it take?**
8. **What are the midterm and final "exams" to check for success?**

---

## Draft Mode: The Interview Process

### Phase 0: Setup

Create a working directory for this proposal:
```
{project-root}/.one-pager/
├── 00-meta.md              # Proposal metadata and status
├── interview/              # Raw interview notes
├── analysis/               # Code exploration and data
├── drafts/                 # Iteration on the one-pager
└── final/                  # Final one-pager + appendix
```

Ask the user:
- What is the working title for this proposal?
- Who is the intended audience? (their manager, a VP, a cross-functional group, their team)
- What decision are you hoping to drive?

### Phase 1: The Problem (Heilmeier Q1 & Q2)

**Goal:** Understand what the user is trying to do and why the current state is inadequate.

**Questions to ask:**
- In plain English, what are you trying to accomplish? (No jargon—imagine explaining to a smart person outside your team)
- What pain exists today? Who feels it?
- How is this currently handled? What's the workaround?
- Why is now the right time to address this?

**Code exploration tasks:**
- If relevant, explore the codebase to understand the current implementation
- Identify the specific files, systems, or patterns that are causing pain
- Quantify the problem if possible (error rates, latency, developer time wasted, etc.)

**Red flags to probe:**
- If the user leads with a solution, push back: "What problem does this solve?"
- If the problem sounds vague, ask for a specific recent example
- If there's no data, ask: "How do we know this is actually a problem?"

**Output:** Save notes to `interview/01-problem.md`

### Phase 2: The Landscape (Heilmeier Q2 continued)

**Goal:** Map the current state comprehensively.

**Questions to ask:**
- What solutions already exist (internal or external)?
- Why haven't those solutions been adopted or why aren't they working?
- What constraints exist? (technical debt, compliance, team expertise, dependencies)
- Who are the stakeholders? Who needs to approve this? Who will be impacted?

**Code exploration tasks:**
- Document the current architecture relevant to this problem
- Identify dependencies and integration points
- Note any existing attempts to solve this problem (dead code, abandoned branches, etc.)

**Output:** Save notes to `interview/02-landscape.md` and any architectural diagrams to `analysis/`

### Phase 3: The Proposal (Heilmeier Q3)

**Goal:** Articulate what's new and why it will work.

**Questions to ask:**
- What is your proposed approach?
- What's new or different about this compared to existing solutions?
- Why do you believe this will succeed where other approaches haven't?
- What assumptions are you making? (List them explicitly)

**Code exploration tasks:**
- If a proof-of-concept exists, examine it
- Identify similar patterns in the codebase that succeeded or failed
- Assess technical feasibility

**Push back on:**
- "Best practice" justifications without context
- Solutions that seem more interesting than necessary
- Missing explanation of why alternatives were rejected

**Output:** Save notes to `interview/03-proposal.md`

### Phase 4: Alternatives Analysis (Heilmeier Q3 continued)

**Goal:** Demonstrate that other options were genuinely considered.

**Questions to ask:**
- What other approaches did you consider?
- For each alternative: Why was it rejected?
- What would have to be true for one of those alternatives to be the right choice?
- Is "do nothing" a viable option? What happens if we don't act?

**Framework for each alternative:**
```
Alternative: [Name]
Description: [1-2 sentences]
Pros: [List]
Cons: [List]
Why rejected: [Specific reason]
```

**Output:** Save to `interview/04-alternatives.md`

### Phase 5: Impact & Stakeholders (Heilmeier Q4)

**Goal:** Establish who cares and what success looks like.

**Questions to ask:**
- If this succeeds, what changes? Be specific.
- Who benefits? (Users, developers, the business, operations)
- How will you measure success? What metrics will move?
- What does "done" look like?

**Quantify where possible:**
- Developer hours saved per week/month
- Latency/performance improvements
- Error rate reductions
- User experience improvements
- Cost savings

**Output:** Save to `interview/05-impact.md`

### Phase 6: Risks (Heilmeier Q5)

**Goal:** Honestly assess what could go wrong.

**Questions to ask:**
- What are the technical risks?
- What are the organizational risks? (adoption, pushback, dependencies on other teams)
- What's the worst-case scenario if this fails?
- What's your mitigation strategy for each major risk?

**Framework:**
```
Risk: [Description]
Likelihood: [Low/Medium/High]
Impact: [Low/Medium/High]
Mitigation: [How you'll address it]
```

**Output:** Save to `interview/06-risks.md`

### Phase 7: Cost & Timeline (Heilmeier Q6 & Q7)

**Goal:** Be honest about resource requirements.

**Questions to ask:**
- What's the estimated effort? (engineer-weeks, not calendar time)
- What resources are needed? (people, infrastructure, budget)
- What's the opportunity cost? (What won't get done if we do this?)
- What's a realistic timeline? Break it into phases if helpful.
- Are there dependencies on other teams or external factors?

**Push back on:**
- Optimistic estimates without justification
- Missing infrastructure or tooling costs
- Ignored opportunity costs

**Output:** Save to `interview/07-cost-timeline.md`

### Phase 8: Success Criteria (Heilmeier Q8)

**Goal:** Define how we'll know if this worked.

**Questions to ask:**
- What are the midterm checkpoints? How will we know we're on track?
- What's the final success criterion?
- How long after launch until we can evaluate success?
- What would cause us to abandon this approach?

**Output:** Save to `interview/08-success-criteria.md`

### Phase 9: Synthesis & Distillation

**Goal:** Compress everything into a one-pager + appendix.

**Process:**
1. Review all interview notes and analysis
2. Identify the core narrative arc: Problem → Why now → Proposal → Ask
3. Draft the one-pager (see structure below)
4. Move supporting detail to the appendix
5. Apply the "so what?" test to every sentence
6. Remove weasel wo