# Proposal Writer

> Create properly formatted proposal documents in spec/proposals/. Use when making significant changes to requirements, design, or tasks. Triggers on "create proposal", "document change", "propose feature", or when changes need formal documentation. Use when this capability is needed.

- Skill: `tomevault-io/proposal-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/proposal-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/proposal-writer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/proposal-writer

---


# Proposal Writer

Create change proposals following project conventions.

## When to Create a Proposal

**Required for**:
- New features
- Architecture changes
- Significant design decisions
- Changes to `spec/requirements.md`, `spec/design.md`, or `spec/tasks.md`

**Not needed for**:
- Bug fixes (unless design changes)
- Minor improvements
- Documentation updates

## Proposal Location & Naming

```
spec/proposals/yyyyMMdd_{proposal_name}.md
```

**Examples**:
- `20260126_add_export_feature.md`
- `20260126_improve_performance.md`

Use snake_case, descriptive but concise names.

## Proposal Template

```markdown
# Proposal: {Title}

**Date**: YYYY-MM-DD
**Author**: {Name or "Claude Agent"}
**Status**: Proposed

## Background

{Why this change is needed. 2-3 sentences.}

## Current Behavior

{What happens now. Include code snippets if relevant.}

## Proposal

{Detailed description of the proposed changes.}

### {Sub-section if needed}

{Details, code examples, diagrams.}

## Impact

- **Requirements**: {What changes in requirements.md, or "No change"}
- **Design**: {What changes in design.md, or "No change"}
- **Tasks**: {What new tasks will be added to tasks.md}

## Alternatives Considered

1. **{Alternative 1}**: {Why not chosen}
2. **{Alternative 2}**: {Why not chosen}

## Implementation Plan

1. Step 1
2. Step 2
3. Step 3

## Testing Plan

{How to verify the changes work correctly.}

- Test case 1
- Test case 2
```

## Status Values

| Status | Meaning |
|--------|---------|
| Proposed | Initial draft, awaiting review |
| Approved | Accepted, ready for implementation |
| Implemented | Changes have been made |
| Rejected | Not accepted (keep for record) |

## After Creating Proposal

1. **Update spec files** as described in Impact section:
   - `spec/requirements.md` - Add new requirements
   - `spec/design.md` - Add architecture changes
   - `spec/tasks.md` - Add implementation tasks

2. **Reference in commits**:
   ```
   feat: Add export feature
   
   See spec/proposals/20260126_add_export_feature.md for details.
   ```

3. **Update proposal status** after implementation

## Example: Simple Feature Proposal

```markdown
# Proposal: Add Dark Mode Support

**Date**: 2026-01-26
**Author**: Claude Agent
**Status**: Proposed

## Background

Users have requested dark mode for better viewing in low-light conditions.

## Current Behavior

App only supports light theme. Colors are hardcoded in CSS.

## Proposal

Add theme toggle in settings with system preference detection.

### Implementation

1. Create CSS variables for theme colors
2. Add ThemeContext for state management
3. Add toggle in Settings page
4. Persist preference in localStorage

## Impact

- **Requirements**: Add REQ-UI-015 "Support dark mode"
- **Design**: Add theme system to design.md
- **Tasks**: Add Sprint 5 tasks for implementation

## Alternatives Considered

1. **CSS-only with prefers-color-scheme**: Less control, no user override
2. **Third-party library**: Overkill for this use case

## Implementation Plan

1. Create theme CSS variables
2. Add ThemeContext
3. Add Settings toggle
4. Test on all pages

## Testing Plan

- Toggle works in Settings
- System preference detected on first load
- Preference persists across sessions
- All pages render correctly in both themes
```

## Quick Commands

```bash
# Create new proposal file
touch spec/proposals/$(date +%Y%m%d)_proposal_name.md

# List recent proposals
ls -la spec/proposals/ | tail -10

# Check proposal status
grep "Status:" spec/proposals/*.md
```

## Linking Proposals in tasks.md

When adding tasks, link to the proposal:

```markdown
### Feature Name
**Proposal**: See [spec/proposals/20260126_feature_name.md](proposals/20260126_feature_name.md)

- ⬜ Task 1
- ⬜ Task 2
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/icoxfog417) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-15 -->