Tech Spec Writer
Tech Spec Writer
Turn a verbal description or rough idea into a structured technical specification — the kind engineers can actually build from without a follow-up meeting.
What it produces
A complete spec document with seven sections:
- Problem statement — what's broken or missing, and why it matters now
- Proposed solution — what the system should do at a high level
- In scope / Out of scope — explicit boundaries that prevent scope creep
- User stories — "As a [user], I want [action] so that [outcome]" format
- Edge cases — the failure modes, empty states, and race conditions that kill launches
- Acceptance criteria — binary, testable conditions with no weasel words ("it should feel fast" → "page load under 1.5s on 4G")
- Open questions — decisions still outstanding, with a named owner and a deadline
Who it's for
PMs, founders, and engineers who need to get alignment before a sprint starts. Also useful when you've already built something but never formally specced it — reverse-speccing is a legitimate use case.
Example input
We need a way for users to upload a profile photo. Should support JPG and PNG, crop it to a square, and show a preview before saving. Probably enforce a 5MB limit.
Example output
Problem statement: Users currently have no way to personalize their profile. Onboarding completion drops 22% at the "Add a photo" step.
Proposed solution: A photo upload flow that accepts JPEG/PNG, enforces a 5MB size limit, presents a square crop tool, shows a preview, and saves on confirm.
In scope: Upload, crop, preview, save. JPEG and PNG only.
Out of scope: Video avatars, GIF support, social login photo import (Phase 2).
User stories:
- As a new user, I want to upload a profile photo so I can personalize my account
- As a user, I want to crop my photo before saving so only the part I want is shown
- As a user, I want to see a preview before confirming so I don't save a bad photo
Edge cases: File >5MB (show error, no upload); unsupported file type; upload fails mid-transfer; user exits crop without saving; photo already exists (overwrite flow)
Acceptance criteria:
- Upload fails with error message if file exceeds 5MB
- Only JPEG and PNG are accepted; other formats show "unsupported format" error
- Crop tool enforces 1:1 aspect ratio
- Preview renders before save button is active
- Saving replaces previous photo immediately without page reload
Open questions: Should old photos be deleted from storage or soft-deleted? [Owner: backend team. Deadline: sprint planning Monday]
What makes this different
Most people write specs that describe features, not behaviors. This skill forces the spec into the shape that actually prevents build problems: binary acceptance criteria, explicit scope boundaries, and documented open questions — so the spec does its job before a line of code is written.
