Feature Specs skill for Codex

A feature spec is done well when it fits on about one page, an engineer can start without a meeting, every UI state and edge case has a decided behaviour (not “TBD”), and it names the code it touches so estimates are grounded. Small features fail on the states nobody wrote down, not on the happy path.

When to use this vs a PRD

Change	Document
One screen, endpoint or flow; days to two weeks; one team	Feature spec (this skill)
Multi-week, multiple teams, new metrics or pricing	PRD ($prd-writing)
Architecture, data model or service changes	Design doc ($design-docs-rfcs), linked from the spec

Before writing

1. Read the ticket, any design file or screenshot, and related support issues.
2. Read AGENTS.md, then find the code the change touches:

rg -n "InviteMemberDialog|inviteMember" src/      # components and handlers
rg -n "invitations" db/ migrations/ src/models/    # data model
rg -n "can_invite|permissions" src/auth/           # permission checks

3. Note existing components, validation helpers, copy patterns and error handling to reuse. A spec that invents a new pattern where one exists creates inconsistency.

Spec template

# Spec: <feature name>
Ticket: <link> | Owner: <PM/eng> | Designs: <link or "none - follow existing patterns">
Status: draft | ready | in progress

## Context (3-5 sentences)
<Who needs this, the problem, evidence, and why now.>

## Behaviour
1. <rule, testable> e.g. Admins and owners can resend a pending invite; members cannot.
2. <rule> Resend is limited to 3 per invite per 24 h; the 4th attempt shows the limit message.
3. <rule> Resending resets the 7-day expiry from the time of resend.

## States
| State | Trigger | What the user sees | Notes |
|---|---|---|---|
| Empty | No pending invites | "No pending invites" + Invite button | Existing EmptyState component |
| Loading | Fetching invites | Skeleton rows (3) | Do not flash under 300 ms |
| Success | Resend OK | Toast "Invite resent to [email protected]" | Row shows new sent time |
| Error - network | Request fails | Inline row error + Retry | Keep row actions enabled |
| Error - limit | 4th resend in 24 h | "You can resend again after 14:20" | Button disabled until then |
| Permission denied | Member opens page | Resend hidden; list read-only | Server enforces too |
| Expired invite | Past expiry | "Expired" badge; Resend creates fresh invite | |

## Edge cases
- Invitee already joined via another invite: resend hidden, row removed on refresh
- Email bounced previously: show warning and allow edit of address
- Two admins resend at once: one email sent; both see success (idempotent per minute)

## Copy
<all user-facing strings, including errors and confirmations>

## Analytics
- `invite_resent` { workspace_id, inviter_role, attempt_number } (server, on email queued)

## Code touchpoints
- src/components/members/PendingInvites.tsx (UI)
- src/api/invitations.ts resend handler; rate limit via existing RateLimiter
- No schema change: uses invitations.last_sent_at, resend_count

## Out of scope
- Bulk resend; editing role on pending invite

## Acceptance criteria
<Given/When/Then for each behaviour rule, or link>

## Open questions
- <question> - owner, due

States checklist

Walk every item; each one gets a row in the states table or a line saying why it does not apply:

• Empty (first use, and after everything is deleted)
• Loading (initial and incremental; what stays interactive)
• Partial (some data loaded, some failed; pagination end)
• Success (feedback, where focus goes next)
• Validation errors (inline, per field, message text)
• System errors (network, server 5xx, timeout) and retry behaviour
• Disabled (why, and how the user learns why)
• Permission denied (hidden vs disabled vs error; server enforcement)
• Limits reached (counts, sizes, rate limits)
• Offline or slow connection, if the platform supports it
• Long content (names, translations, many items)

For the design and copy of these states, see $ui-copy-states.

Edge case prompts

Ask for each behaviour rule:

• What if the same action happens twice (double click, two tabs, two users)?
• What if the referenced thing was deleted, archived or changed in the meantime?
• What happens at 0, 1, the limit, and the limit + 1?
• What about time zones, daylight saving and expiry boundaries?
• What does an API client (not the UI) experience?
• What happens to existing data when this ships (migration, defaults for old rows)?

Workflow

- [ ] 1. Read ticket, designs, related issues
- [ ] 2. Find and read the code touchpoints; note reusable components
- [ ] 3. Draft context and behaviour rules
- [ ] 4. Fill the states table and edge cases from the checklists
- [ ] 5. Write all copy and analytics events
- [ ] 6. Add acceptance criteria (see $acceptance-criteria) and out-of-scope
- [ ] 7. List open questions; resolve or assign them before "ready"
- [ ] 8. Save beside related docs or attach to the ticket per AGENTS.md conventions

Gotchas

• “Show an error” is not a behaviour; write the message, placement and recovery action.
• Permission rules enforced only in the UI are security bugs; the spec must say the server enforces them.
• Specs that grow past two pages are PRDs or need splitting.
• Designs often show only the success state; the spec owns the rest.
• Do not mark a spec ready while open questions affect behaviour rules.

Verification

Read the spec as the implementing engineer: can you list every file to change and every state to build without asking? Check every behaviour rule has an acceptance criterion, every states checklist item is covered or marked not applicable, all copy is written out, and no open question blocks a behaviour rule.