kivo360/oip-proposal

OIP Proposal Skill

Create OmoiOS Improvement Proposals (OIPs) through an interactive, question-driven workflow. This skill gathers context from the user, researches the codebase for accurate file references, and writes a complete proposal following the project's OIP template.

Workflow

Follow these three phases in order. Do not skip the clarification phase — proposals written without understanding the user's intent produce vague specifications that require rewrites.

---

Phase 1: Clarify the Proposal

Goal: Understand what the user wants to propose and why, before writing anything.

Step 1: Determine the next OIP number

Read docs/proposals/README.md and check which OIP numbers are taken:

ls docs/proposals/oip-*.md

The next number is one above the highest existing number, zero-padded to 4 digits.

Step 2: Ask clarifying questions

Use the AskUserQuestion tool to gather essential context. Ask questions based on what the user has provided so far. Not all questions will be needed for every proposal — use judgment.

Always ask:

• What problem does this solve? (The "motivation" — should be concrete, not vague)
• Who benefits? (Users, developers, ops, everyone?)
• What's the proposed solution at a high level?

Ask if unclear:

• What type of proposal is this? (Standards Track for product/code changes, Informational for guidelines, Process for workflow changes)
• Are there constraints or non-goals? (Things this proposal deliberately does NOT do)
• Are there alternatives you considered and rejected?
• Does this depend on or conflict with other OIPs?
• What's the security surface? (New endpoints, auth changes, public-facing features)
• What infrastructure is needed? (New services, databases, external APIs)

Ask if the proposal involves frontend work:

• Which routes or pages are affected?
• Are new components needed, or can existing ones be reused?
• How does this interact with the navigation/sidebar?

Ask if the proposal involves backend work:

• Which services are affected?
• Are database migrations needed?
• Does this require new API endpoints?

Step 3: Confirm understanding

Summarize what you've gathered in 3-4 sentences and ask the user to confirm before proceeding. Use AskUserQuestion with options like "Yes, that's right" / "Close but let me clarify" / "No, let me re-explain".

---

Phase 2: Research the Codebase

Goal: Find the real files, components, and patterns that the proposal will reference. Proposals that reference actual codebase paths are far more useful than ones that speak abstractly.

What to research

Based on the proposal's scope, read the relevant files:

• Frontend changes: Check frontend/app/ for route structure, frontend/components/ for existing components, frontend/hooks/ for data patterns, frontend/lib/api/ for API client functions
• Backend changes: Check backend/omoi_os/api/routes/ for existing endpoints, backend/omoi_os/services/ for business logic, backend/omoi_os/models/ for database schema
• Configuration: Check backend/config/base.yaml for settings patterns
• Existing proposals: Read related OIPs in docs/proposals/ to avoid conflicts or duplication

Key reference documents

| Document | When to read | |----------|-------------| | ARCHITECTURE.md | Any backend or system-wide proposal | | UI.md | Any frontend proposal | | docs/proposals/README.md | Always — check status table for conflicts | | backend/CLAUDE.md | Backend conventions (structured_output, datetime, reserved words) |

Record your findings

Note the exact file paths (relative from repo root) for every component, service, hook, or route you'll reference. The Specification section must use real paths, not hypothetical ones.

---

Phase 3: Write the Proposal

Goal: Write the complete OIP file following the template exactly.

File location

docs/proposals/oip-{NNNN}-{short-title}.md

Where {NNNN} is the zero-padded number and {short-title} is a kebab-case slug (2-4 words).

Required structure

Every OIP must contain these sections in this order:

```
OIP: {NNNN}
Title: {Descriptive Title}
Description: {One-line summary, max 140 characters}
Author: {Name or handle}
Status: Draft
Type: {Standards Track | Informational | Process}
Created: {YYYY-MM-DD}
Requires: (optional, other OIP numbers)
Replaces: (optional)
Superseded-By: (optional)
```

## Abstract

2-3 sentences. A reader should understand the proposal in 30 seconds.

## Motivation

Why this change is needed. Include data, user research, or metrics.
Reference the problem concretely — link to specific code that demonstrates the issue.

## Specification

Concrete technical details. This is the longest section.

For each change, specify:
- **Modified file**: `path/to/file.ts` — what changes and why
- **New file**: `path/to/new/file.ts` — what it does, key interfaces/types

Include code snippets for interfaces, types, API endpoints, config changes.
Be specific enough that another engineer could implement without asking questions.

## Rationale

Why this approach over alternatives. Name the alternatives explicitly
and explain why they were not chosen. Discuss trade-offs.

## Backwards Compatibility

How existing users and behavior are affected.
If none: "No backwards compatibility concerns."

## Security Considerations

Authentication, rate limiting, abuse vectors, data exposure.
Every proposal MUST address this, even if the answer is "no new attack surface."

## Impact Assessment

Effort estimate (small/medium/large), infrastructure costs, expected user impact.
Include metrics for measuring success.

## Open Issues

Unresolved questions. Number them for easy reference in discussions.

Writing guidelines

• Reference real files: Use path/to/file.ts format for every file mentioned. Readers should be able to cat the file and see what you're talking about.
• Show interfaces: For new components, APIs, or data structures, include the TypeScript interface or Python class definition.
• Be opinionated: State the recommended approach clearly. Don't present 3 options without recommending one.
• Quantify where possible: "~200 lines of new code", "$0.05 per session", "reduces onboarding from 6 steps to 2".
• Address security proactively: Don't wait to be asked. If the feature has a public surface, discuss rate limiting, auth, and abuse vectors.

After writing

1. Update docs/proposals/README.md — add the new OIP to the status table
2. Show the user the completed file path and a brief summary
3. Ask if they want to adjust anything before committing

---

Example Trigger Conversations

User: "I want to propose adding WebSocket support to the sandbox page" Action: Ask clarifying questions about scope (which events? replace polling? backwards compatible?), research frontend/app/(app)/sandbox/[sandboxId]/page.tsx and frontend/hooks/useSandbox.ts, then write the OIP.

User: "Write an OIP for rate limiting the public API" Action: Ask about which endpoints, what limits, whether it's IP-based or token-based, research backend/omoi_os/api/main.py and existing auth middleware, then write the OIP.

User: "New proposal" Action: Ask what they want to propose — don't assume. Start with "What problem are you looking to solve?"

---

Related Resources

• OIP README — Status table, lifecycle, types
• OIP Template — Raw template structure
• ARCHITECTURE.md — System design reference
• UI.md — Frontend architecture reference