Skip to main content

​
Overview

Blocks can enhance product requirements and user stories with technical details, implementation suggestions, and code examples from your codebase. This bridges the gap between product and engineering, ensuring tickets are well-defined before development begins.

​
How It Works

When you ask Blocks to refine a ticket, it will:
  1. Analyze Requirements: Review the product requirements and acceptance criteria
  2. Examine Codebase: Find relevant existing code, patterns, and components
  3. Identify Dependencies: Determine what needs to change or be added
  4. Add Technical Details: Include implementation approach, edge cases, and considerations
  5. Suggest Tests: Recommend test scenarios and coverage areas
  6. Estimate Complexity: Provide insights on implementation difficulty

​
Using Technical Refinement

​
Enhance Linear Tickets

Add technical context to Linear issues: 
@blocks add technical details to this ticket based on our codebase

@blocks analyze this feature request and suggest an implementation approach

@blocks update this ticket with code examples from similar features

​
Refine Requirements

Clarify vague requirements: 
@blocks what questions should we answer before implementing this?

@blocks list the technical considerations for this feature

@blocks identify potential edge cases for this user story

​
Break Down Epics

Split large features into implementable tasks: 
@blocks break this epic into smaller tickets with technical details

@blocks create subtasks for implementing this feature

​
What Gets Added

​
Technical Context

  • Existing Patterns: How similar features are implemented
  • Code Examples: Relevant snippets from the codebase
  • Architecture Notes: How this fits into the existing system
  • API Contracts: Expected inputs, outputs, and interfaces

​
Implementation Details

  • Approach: Recommended implementation strategy
  • Components: What needs to be created or modified
  • Dependencies: Libraries, services, or modules involved
  • Database Changes: Schema modifications if needed

​
Testing Requirements

  • Test Scenarios: What should be tested
  • Edge Cases: Unusual or error conditions to handle
  • Integration Points: Where to add integration tests

​
Risk Assessment

  • Technical Debt: Potential shortcuts or compromises
  • Performance Impact: Scalability and optimization concerns
  • Security Considerations: Authentication, authorization, data protection
  • Migration Needs: How to handle existing data or users

​
Common Refinement Workflows

​
Product to Engineering Handoff

Convert product specs into technical tickets: 
@blocks create an implementation ticket based on this product spec

​
Sprint Planning

Prepare tickets for sprint: 
@blocks refine all tickets in the "Ready for Dev" column with technical details

​
Technical Spike Results

Document findings from exploratory work: 
@blocks add the spike findings to this ticket and suggest next steps

​
Best Practices

  • Refine Early: Add technical details during grooming, not during implementation
  • Keep Updated: Update tickets as you learn more during development
  • Include Examples: Reference similar features in your codebase
  • Be Specific: Provide clear acceptance criteria for engineers
  • Consider Edge Cases: Think through error scenarios and unusual inputs
  • Plan for Tests: Define what “done” means in terms of testing

​
Integration with Linear

Technical refinement works seamlessly with the Linear integration: 
@blocks analyze this ticket and add:
- Implementation approach
- Code examples from our auth system
- Test scenarios
- Potential challenges

​
Collaborative Refinement

Use Blocks to facilitate technical discussions: 
@blocks what are the pros and cons of implementing this with GraphQL vs REST?

@blocks how does this feature compare to what we did for project X?

@blocks what would be the impact of this change on our mobile apps?

​
Plan Mode for Complex Features

For large features, use Plan Mode to create a detailed implementation plan: 
@blocks /plan create an implementation plan for this feature with all technical details
This generates a comprehensive plan including:
  • Architecture decisions
  • Step-by-step implementation approach
  • Testing strategy
  • Migration path
  • Rollout considerations
Learn more about Plan Mode.

​
Output Examples

Before Refinement: 
Add ability to export reports
After Refinement: 
Add ability to export reports

## Technical Details
- Implement CSV and PDF export using existing ReportGenerator service
- Add new /api/reports/:id/export endpoint
- Use existing download pattern from InvoiceController (line 145)
- Store exports in S3 with 24-hour expiry

## Edge Cases
- Handle large reports (>10MB) with streaming
- Rate limit to prevent abuse (5 exports per hour per user)
- Validate user permissions for report access

## Testing
- Unit tests for export formatting
- Integration test for S3 upload
- E2E test for full export flow
- Load test for concurrent exports

## Database Changes
None required - use existing reports table

## Estimated Complexity
Medium - 3-5 days

​
Learn More