A framework for designing proactive AI features—moving beyond static screens to rule-based, intelligent systems.
Traditional design specs describe what users see. AI-first products need specs that describe how the system thinks—what patterns to detect, when to surface insights, and how to learn from user feedback.
This template helps product designers and teams:
- Structure thinking around proactive AI behavior
- Document decision logic for developer handoff
- Define the rules that govern intelligent systems
- Bridge the gap between design intent and implementation
ai-feature-spec-template/
├── README.md # You're here
├── ai-feature-spec-template.md # The main template
└── LICENSE
The specification template covers 12 key areas:
| Section | Purpose |
|---|---|
| Feature Overview | What the AI notices and surfaces |
| Data Inputs | Sources, metrics, and context signals |
| Pattern Recognition | What to detect and how |
| Trigger Conditions | When to surface insights |
| Silence Conditions | When to stay quiet |
| Presentation Rules | How to display based on urgency/confidence |
| User Controls | Actions and settings |
| Transparency | Explaining AI reasoning |
| Edge Cases | Handling unusual scenarios |
| Success Metrics | Measuring effectiveness |
| Example Scenarios | Concrete walkthroughs |
| Open Questions | Unresolved decisions |
Click the "Use this template" button on GitHub to create your own repository.
Duplicate ai-feature-spec-template.md for each AI feature you're designing.
Work through each section, replacing placeholders with your specific:
- Data sources and metrics
- Pattern detection logic
- Trigger and silence conditions
- Presentation rules
- User controls
Use the completed spec as a living document for:
- Design reviews
- Engineering handoff
- Product discussions
- QA testing criteria
Before (Template):
| Pattern ID | Description | Detection Logic | Confidence Threshold |
|------------|-------------|-----------------|---------------------|
| `P001` | `[e.g., Productivity decline]` | `[e.g., >25% below 14-day average]` | `[e.g., 0.75]` |After (Filled In):
| Pattern ID | Description | Detection Logic | Confidence Threshold |
|------------|-------------|-----------------|---------------------|
| P001 | Meeting overload | 4+ meetings before noon | 0.85 |
| P002 | Focus time erosion | <2 hours uninterrupted in 3 consecutive days | 0.80 |
| P003 | Energy mismatch | High-effort tasks scheduled during low-energy periods | 0.70 |Reactive: User asks a question → AI responds Proactive: AI detects a pattern → surfaces insight without being asked
This template is designed for proactive AI features—systems that anticipate user needs.
The template includes a framework for choosing presentation based on:
- Confidence: How certain is the AI about this insight?
- Urgency: How time-sensitive is this information?
High confidence + high urgency = prominent display Low confidence + low urgency = ambient/peripheral display
Every user interaction teaches the system:
- Dismissals = reduce similar alerts
- Actions taken = reinforce pattern recognition
- "Not relevant" = significant decrease in similar
- Start with the problem — What user pain does this solve?
- Define clear thresholds — Avoid vague conditions like "when appropriate"
- Respect attention — Every proactive alert has a cost
- Build in transparency — Users should always understand "why am I seeing this?"
- Plan for failure — What happens when data is missing or the AI is wrong?
Use this template when designing:
- Smart notifications and alerts
- Proactive suggestions and recommendations
- Predictive features
- Behavioral insights
- Automated interventions
- Any feature where the AI acts without explicit user request
Found ways to improve the template? Contributions are welcome:
- Fork the repository
- Create a feature branch
- Submit a pull request
This template is available under the MIT License. See LICENSE for details.
Designing for AI isn't about predicting every screen—it's about defining the rules that generate the right response at the right time.