Issue Spec

Create consistent, comprehensive issue specs. Opinionated structure for technology products.

About Issue Spec

Jira, Linear, and GitHub Issues work for any industry. But technology products have specific needs that generic tools don't address. Issue Spec is opinionated about what good tech product issues look like, embedding best practices directly into the creation experience.

The Gap

Generic tools leave structure open-ended. Teams reinvent ticket formats, and consistency becomes something you enforce rather than something that happens by default.

Opinionated by Design

Product defines what and why. Engineering defines how. This tool encodes that split and guides you toward completeness.

Domain-Specific Guidance

Frontend, Backend, Data, Growth. Each domain has different acceptance criteria, and Issue Spec pre-loads the relevant ones so nothing gets missed.

Consistency as Default

Every spec from every team member follows the same structure. Less back-and-forth, clearer handoffs, faster execution.

Perspective

Who is creating this ticket?

Domain

What type of work is this?

→

Story Details

Title

Prefix

Core

Description

Preview:

User Story

As a

I want

So that

Priority

P0 P1 P2 P3

Resources

Design / Figma

PRD / Requirements

API Spec / Swagger

Success Metrics

How will we measure success?

Technical Awareness

Help engineering understand scope (don't prescribe solutions)

Likely involves:

API changes Database changes New UI components Auth/permissions Third-party integrations Background jobs

Performance Sensitivity

Complexity Estimate

Design Details

Affected Screens/Flows

Interaction Patterns

Expected Deliverables

Design Checklist

Visual design consistent with brand guidelines Responsive designs for mobile, tablet, desktop Accessibility requirements addressed (color contrast, touch targets) Loading and error states designed Empty states designed Interaction states defined (hover, focus, active) Design handoff assets prepared

UX Research Details

Research Questions

Methodology

Target Participants

Research Checklist

Research objectives clearly defined Participant criteria documented Discussion guide / test script prepared Recruitment plan in place Findings synthesized and documented Actionable recommendations provided

Onboarding Details

Onboarding Flow

Activation Moment

Onboarding Checklist

User journey mapped from signup to activation Drop-off points identified and addressed Progress indicators included Skip/exit options available Analytics events defined for funnel tracking Email/notification triggers defined

Growth Details

Hypothesis

Primary Metric

Growth Checklist

Hypothesis clearly stated Success metrics defined with targets Experiment design documented (A/B, holdout, etc.) Sample size and duration calculated Analytics tracking implemented Rollback plan defined

Core Tech Involved

Pre-selected based on domain. Adjust as needed.

API Database UI Component Queue / Async Auth Caching

Technical Requirements

Pre-checked requirements. Uncheck what doesn't apply.

API

Design RESTful conventions (HTTP verbs, resource naming) Appropriate status codes (200, 201, 400, 401, 403, 404, 500) Versioning strategy defined (URL, header, or query param) Pagination for list endpoints (cursor or offset) Validation & Errors Request validation with clear error messages Consistent error response structure Idempotency for mutation endpoints (POST, PUT, DELETE) Documentation & Operations OpenAPI/Swagger spec updated Request/response logging configured Rate limiting configured Timeout handling (client and server) CORS configured if needed

Database

Schema Design Appropriate data types and sizes Foreign key / integrity constraints Audit fields (created_at, updated_at, created_by) Soft delete vs hard delete decision documented Performance Indexes for expected queries N+1 query patterns avoided Query performance tested with realistic data Connection pooling configured Operations Migration script with rollback Transaction handling for multi-step operations Sensitive data encryption (PII, credentials) Backup/recovery strategy considered

UI Component

Accessibility Keyboard navigable (tab order, focus management) Screen reader accessible (ARIA labels, roles) Color contrast meets WCAG AA States Loading state implemented Error state implemented Empty state implemented Hover/focus/active states defined Disabled state if applicable Responsiveness & Compatibility Responsive: mobile, tablet, desktop Cross-browser tested (Chrome, Safari, Firefox, Edge) Dark mode support if applicable Performance & Quality Render performance acceptable (<100ms) Memory cleanup (no leaks on unmount) Component tests written

Queue / Async

Reliability Idempotent message processing Retry logic with exponential backoff Dead letter queue for persistent failures Poison message handling Semantics Delivery guarantee defined (at-least-once, exactly-once) Message ordering requirements documented Visibility timeout configured appropriately Operations Timeout handling for long-running jobs Backpressure handling (queue depth limits) Monitoring and alerting configured Batch processing optimized if applicable

Auth

Access Control Permission model defined (RBAC, ABAC, etc.) 401 (unauthenticated) vs 403 (unauthorized) distinction Resource-level authorization checks Token & Session Token expiry and refresh handling Secure token storage (httpOnly, secure flags) Session invalidation on logout/password change Security Rate limiting on auth endpoints CSRF protection if using cookies Audit logging for sensitive actions MFA consideration if high-security

Caching

Strategy Cache invalidation strategy defined TTL (time-to-live) appropriate for data freshness Cache key design documented Write-through vs write-behind decision Reliability Fallback behavior on cache miss Thundering herd prevention (locking/coalescing) Cache warming strategy if needed Operations Memory limits configured Cache hit/miss monitoring

Frontend Details

Components Affected

State Management

API Dependencies

Backend Details

Endpoints

Data Models

Validation Rules

Infrastructure Details

Services Affected

Configuration Changes

Scaling Considerations

Infrastructure Checklist

Deployment strategy documented (blue/green, canary, etc.) Rollback procedure defined Monitoring and alerting configured Load testing performed Security review completed

Data Details

Data Sources

Transformations

Output / Destination

Data Checklist

Data schema documented Data quality checks in place Backfill strategy defined (if needed) PII handling compliant Pipeline monitoring configured

Additional Criteria

Dependencies

Output

Title

—

Description

Select a perspective and domain to get started...

Acceptance Criteria

—