writing-plans

name	writing-plans
description	Use when planning implementation of a feature, refactoring, or multi-step change — creates bite-sized tasks with exact file paths, code, and verification steps

Writing Plans

Adapted from superpowers:writing-plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context. Document everything: which files to touch, exact code, how to verify. Plans are bite-sized tasks (2-5 minutes each).

Principles

• DRY — Don't Repeat Yourself
• YAGNI — You Aren't Gonna Need It
• Frequent commits — Commit after each logical step

Save Plans To

docs/plans/YYYY-MM-DD-<feature-name>.md

Plan Document Header

Every plan MUST start with:

# [Feature Name] Implementation Plan

**Goal:** [One sentence — what this builds]

**Architecture:** [2-3 sentences about approach]

**Files affected:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py`

---

Task Structure

Each task should be self-contained:

### Task N: [Component Name]

**Files:**
- Create: `backend/routers/new_router.py`
- Modify: `backend/main.py` (add router mount)
- Modify: `frontend/src/pages/new-page.js`

**Step 1: Backend — Create API endpoint**

```python
@router.get("/api/new-endpoint")
async def new_endpoint(db: AsyncSession = Depends(get_db)):
    result = await db.execute(select(Model))
    return result.scalars().all()
```

**Step 2: Frontend — Create page module**

```javascript
export async function render(container) {
    const data = await api.get('/api/new-endpoint');
    container.innerHTML = `...`;
}
```

**Verify:**
1. `python main.py` — starts without errors
2. Open `http://localhost:5174/#/new-page` — page renders
3. Check Network tab — API call succeeds

Scope Check

If the feature spans multiple independent subsystems, break into separate plans. Each plan should produce working, testable software on its own.

OAC Studio Conventions

• Backend routers go in backend/routers/ — mount in main.py
• Frontend pages go in frontend/src/pages/ — register in router.js
• API prefix: /api/ — frontend uses relative URLs via Vite proxy
• State: Global state.js object, no reactive system
• Styling: All CSS in frontend/src/style.css using Cyberpunk design tokens
• Database: Async SQLAlchemy — use db: AsyncSession = Depends(get_db)