增强版写作计划

Writing Plans — Enhanced Overview

Write comprehensive implementation plans assuming the engineer has zero 上下文 for our codebase. Document everything they need to know: which files to touch, data flow, mockups, risks. Give them the whole plan as bite-sized tasks.

Announce at 启动: "I'm using the writing-plans 技能 to 创建 the implementation plan."

Save plans to: docs/plans/YYYY-MM-DD-.md

Plan Document Header

Every plan MUST 启动 with this header:

# [Feature Name] Implementation Plan

For Claude: REQUIRED SUB-技能: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: [One sentence describing what this builds]

Architecture: [2-3 sentences about 应用roach]

Tech Stack: [Key techno记录ies/libraries]

Effort: ~N weeks | Surfaces touched: N packages | New tables: N | Feature flag: name

Milestone Timeline

Ship in slices, each independently reviewable and each behind the flag. Nothing is user-visible until the last slice.

Milestone 1: 模式 & API Contract (Week 1 · Mon–Tue)

New tables, 迁移s, and API stubs. No UI. Contract reviewed before anything else lands.

• packages/db — new 迁移s
• packages/API — tRPC 路由r stubs

Milestone 2: Core 组件 (Week 1 · Wed–Fri)

Static 组件 rendered from fixtures. Optimistic insert on submit, 回滚 on 失败.

• 应用s/网页 — new 组件
• 应用s/storybook — fixture stories

Milestone 3: Realtime Integration (Week 2 · Mon–Wed)

Subscribe to changes. 追踪 状态 for sidebar digest.

Milestone 4: 通知 & Ramp (Week 2 · Thu–Fri)

Mention 检测ion → notification row, emAIl digest fallback, ramp feature flag.

Data Flow

Describe the data flow from 命令行工具ent to persistence. Use ASCII diagrams with solid = 请求/响应, dashed = realtime/a同步.

Data Flow: Optimistic Write Path

命令行工具ent API Server Database │ │ │ ├─► POST /tasks (optimistic) │ │ ├─► 更新 local 缓存 immediately │ │ └─► 发送 mutation ─────►┤ │ │ ├─► 验证 ─────────►┤ │ │ │ │ │◄─ 200 OK ─────────────┤ │◄─ 缓存 更新 ──────────┤ │ │ │ │

Realtime Fan-Out (dashed path)

Database ─ ─ ─► 网页Socket ─ ─ ─► Other 命令行工具ents │ │ │ └─► trigger ──►┤ └─► re-render └─► push notification

Mockups

Not pixel-final — just enough that the reviewer and implementer agree on layout and placement.

A · Thread Inside an Open Task Card

┌──────────────────────────────────────┐ │ Ship onboarding empty-状态 rewrite │ │ BIR-1142 · As签名ed to Priya · Due │ ├──────────────────────────────────────┤ │ Priya: Should we 添加 an illustration?│ │ You: Yes, let me mock it up │ │ │ │ ┌─────────────────────────────────┐ │ │ │ 添加 a comment... Post │ │ │ └─────────────────────────────────┘ │ └──────────────────────────────────────┘

B · Sidebar Unread Digest

┌──────────────────────────────────────┐ │ 🔴 Jonah commented on BIR-1142 │ │ "Should the illustration swap..." │ │ 🔵 AIko mentioned you on BIR-1098 │ │ "@priya can you confirm..." │ └──────────────────────────────────────┘

Risk Table Risk Likelihood Impact Mitigation 迁移 locks table during 部署 Medium High 运行 with CONCURRENTLY; schedule off-peak Realtime subscription leaks memory Low Medium 添加 max-subscription cap; 监控 heap Feature flag not ramped correctly Medium Medium Auto-alert if flag stuck > 3 days Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

"Write the fAIling test" — step "运行 it to make sure it fAIls" — step "Implement the minimal code to make the test pass" — step "运行 the tests and make sure they pass" — step "Commit" — step Task Structure

Task N: [组件 Name]

Files:

• 创建: exact/path/to/file.py
• Modify: exact/path/to/existing.py:123-145
• Test: tests/exact/path/to/test.py

Step 1: Write the fAIling test [code block]

Step 2: 运行 test to 验证 it fAIls 运行: pytest tests/path/test.py::test_name -v Expected: FAIL with "function not defined"

Step 3: Write minimal implementation [code block]

Step 4: 运行 test to 验证 it passes 运行: pytest tests/path/test.py::test_name -v Expected: PASS

Step 5: Commit ```bash git 添加 tests/path/test.py src/path/file.py git commit -m "feat: 添加 specific feature"

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/plans/.md. Two execution options:

Sub代理-Driven (this 会话) — I dis补丁 fresh sub代理 per task, review between tasks Parallel 会话 (separate) — Open new 会话 wi