one-pager

What this skill does

# One-Pager Skill

Create concise proposal documents (1-3 pages) for getting stakeholder sign-off before investing in detailed technical design. One-pagers focus on the **what** and **why** — not implementation details.

**Key principle**: All information comes from the user. Do NOT scan the codebase to discover the problem. The `Read` tool is only for reading user-provided context files (existing docs, ADRs, RFCs) that the user explicitly shares.

## When to Use a One-Pager

- Proposing a new feature or capability
- Suggesting a process or workflow change
- Recommending a technology decision
- Requesting resources or budget approval
- Any decision needing stakeholder buy-in that doesn't require full TSD/RFC depth

## Workflow

### Phase 1: Gather Context

Parse what the user already provided in their initial request. Extract:
- **Problem**: What's broken or missing?
- **Proposed solution**: What do they want to do?
- **Stakeholders**: Who needs to approve?
- **Context**: Technologies, constraints, related work

**Only ask for what's genuinely missing.** If the user said "write a one-pager for adding SSO to our internal tools", the problem and solution are already known — don't ask them to re-explain.

**Essential questions** (use `references/question-bank.md` patterns, ask only if not already provided):

1. **Problem & current state**: "Walk me through what's happening now and what's broken."
2. **Evidence**: "How do we know this is a problem? Any metrics, complaints, or incidents?"
3. **Desired outcome**: "What does success look like after this is solved?"
4. **Sign-offs needed**: "Who needs to approve this? Any cross-functional stakeholders?"
5. **Risks** (optional): "What could go wrong? Any technical or business risks?"
6. **Related context** (optional): "Any existing docs, tickets, or previous attempts I should know about?"

**If user seems uncertain or exploratory**: Offer research assistance via `agent:web-research-specialist` before drafting.

**Rich context** (accept at any point):
- File paths → use `Read` tool to load
- Pasted content → incorporate directly
- Verbal description → capture key points

### Phase 2: Generate & Iterate

Once sufficient context is gathered, generate the **complete one-pager draft** using the template structure from `assets/templates/template.md`.

**Content generation rules:**
- Use section headings from `template.md` exactly
- Fill sections with user-provided content
- Use italicized placeholders for missing info: *Describe the problem*
- Do NOT include checkboxes, HTML comments, guidance questions, or quality criteria in output
- Tables and lists are encouraged for readability

**After presenting the full draft:**
1. Internally validate against `assets/templates/quality-checklist.md` — never show this to the user
2. Identify any gaps and ask targeted follow-up questions (e.g., "Would you like to add success metrics to the Goal section?")
3. Iterate based on user feedback
4. Save in requested format (`document-skills:docx`, `document-skills:pdf`, or markdown)

## Document Structure

Sections (from `assets/templates/template.md`):

| Section | Purpose |
|---------|---------|
| About this doc | Metadata: deadline, status, authors |
| Sign offs | List of approvers |
| Problem | Current state, evidence, who's affected |
| High level goal | Desired outcome and success metrics |
| What happens if we don't solve this | Cost of inaction |
| Proposed solution | Recommended approach and rationale |
| Alternatives | Other options considered and why rejected |
| Risks | Technical and business risks with mitigations |
| Open questions | (Optional) Unresolved uncertainties |

## Quality Principles

- Lead with the problem — readers need to understand **why** before they care about **what**
- Quantify impact wherever possible ("50 errors/day", "2-hour weekly manual effort")
- Be honest about trade-offs and weaknesses
- Keep it scannable: bullet points, short paragraphs
- Include at least 1 alternative with clear trade-off reasoning

## Visual Aids

Only generate diagrams if the user explicitly requests them. When requested:
1. Ask what the diagram should show
2. Invoke `common-engineering:mermaid` skill
3. Integrate into document

## Integration Points

| Capability | When to Use |
|-----------|-------------|
| `agent:web-research-specialist` | User needs research on industry context, best practices |
| `common-engineering:mermaid` | User explicitly requests diagrams |
| `document-skills:docx` | Export to Word format |
| `document-skills:pdf` | Export to PDF format |

## Reference Files

| File | Purpose |
|------|---------|
| `references/writing-guidelines.md` | Technical writing best practices |
| `references/question-bank.md` | AskUserQuestion patterns for this skill |
| `assets/templates/template.md` | Document structure (use for output) |
| `assets/templates/guidance.md` | Section-by-section guidance (read, never copy to output) |
| `assets/templates/quality-checklist.md` | Internal validation (never show to user) |
| `assets/templates/examples.md` | Completed examples for quality reference |