writing-specs-designs_skill

Overview

This skill helps you write practical, usable specs and design documents that drive engineering and design work forward. It guides you to pick the right fidelity, prioritize prototypes over polish, and highlight the moving pieces that matter. The goal is clear alignment and faster learning rather than perfect artifacts.

How this skill works

I start by clarifying the intended fidelity: low‑fi for alignment or high‑fi for implementation. I then surface the 8–10 moving parts, recommend prototyping approaches (code vs mock), and call out long‑term implications of temporary shortcuts. Finally, I produce a focused spec or sketch template that your team can act on or iterate from.

When to use it

• Align cross‑functional teams quickly before development starts
• Translate product ideas into actionable implementation guidance
• Decide whether to prototype or write a detailed spec
• Prepare feature handoffs to engineering and design
• Avoid long‑lived temporary shortcuts in early launches

Best practices

• Pick fidelity based on outcome: use fat‑marker sketches for alignment, code prototypes for interaction validation
• Limit the spec to 8–10 moving pieces so engineers see the system without over‑prescribing UI
• Prototype with real data and flows rather than relying on static screenshots
• Call out which decisions are permanent vs temporary and plan migration paths
• Measure every tap: ensure each interaction delivers immediate user value

Example use cases

• Create a low‑fi sketch to align PM, design, and engineering on a new onboarding flow
• Draft a high‑fi implementation spec listing APIs, data models, and error cases for a payments feature
• Decide whether to build a throwaway code prototype to validate complex interactions
• Transform a stakeholder pitch into a concise design doc with clear acceptance criteria
• Audit an existing feature to find temporary shortcuts that should be refactored