Menu
Write a technical specification for a feature, API, or system component. Use when asked to spec out, design, or document a feature before it is built.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Review code changes for bugs, security vulnerabilities, performance issues, and maintainability. Use when asked to review code, a PR, a diff, or recent changes.
Systematically diagnose and fix bugs, unexpected behavior, or failing tests. Use when something is broken and the cause is not immediately obvious.
Explore a codebase and produce a detailed implementation plan before writing any code. Use when asked to plan a feature, think through an approach, or figure out how to implement something.
Safely restructure code to improve clarity, reduce duplication, or simplify design without changing observable behavior. Use when asked to clean up, simplify, or restructure code.
Write tests for existing code or new features. Use when asked to add tests, improve test coverage, or write tests for a specific function or module.
| name | spec |
| description | Write a technical specification for a feature, API, or system component. Use when asked to spec out, design, or document a feature before it is built. |
A spec exists to align everyone on what is being built before any code is written. It should be precise enough that two engineers would build the same thing after reading it.
Work through each section. Skip a section only if it genuinely does not apply.
One paragraph: what this feature is, why it exists, and who it is for.
Bulleted list of what this spec achieves. Be specific.
What this spec explicitly does NOT cover. This prevents scope creep.
Context a new engineer would need: existing behavior, related systems, constraints, prior decisions and why they were made.
Data model New fields, tables, or types. Use actual type notation.
interface PasswordResetToken {
id: string;
userId: string;
token: string; // bcrypt hash of the raw token
expiresAt: Date;
usedAt: Date | null;
}
API / Interface New endpoints, functions, or components. Include signatures and behavior contracts.
POST /auth/password-reset
Body: { email: string }
Response 200: {} (always, to avoid email enumeration)
Response 429: { retryAfter: number } (rate limited)
Flow Step-by-step description of the happy path and the main error paths.
State changes What persists, what is temporary, what gets deleted.
Enumerate the cases that could go wrong and how each is handled.
| Case | Behavior |
|---|---|
| Email not found | Return 200 silently (avoid enumeration) |
| Token expired | Return 400 with clear message |
| Token already used | Return 400 |
| Multiple requests | Invalidate previous tokens |
Authentication, authorization, rate limiting, input validation, data exposure.
What needs to be tested and at what level (unit, integration, e2e).
Decisions that are not yet made. Name the tradeoffs and who should decide.
Explicitly list related things this spec does not cover.