Ai Feature Spec

AI Feature Specification

Operating contract

Inputs

Outputs

• Produce: feature blueprint, model and prompt contract, output schema, fallback states, oversight path, and test plan.

Capability and permission boundaries

Default to read-only analysis. Read only scoped records; redact secrets and regulated data. Writes, execution, network calls, production configuration, customer communication, billing changes, and delegation require explicit authority and an identified owner. Never widen tenant, time-window, or system scope implicitly.

Degraded mode

When required telemetry, evidence, execution, network access, or write authority is unavailable, return a partial result with each unassessed item labelled, preserve the safest existing state, and state the evidence or approval needed to continue. Never convert missing evidence into a pass.

Decision rules

Anti-Patterns

• Treating absent evidence as success. Fix: mark the check unassessed and name the missing source.
• Expanding one tenant or workflow to all tenants. Fix: enforce supplied scope at every query and action.
• Performing a production write during analysis. Fix: emit a reviewed change plan until authority is explicit.
• Reporting a metric without population, window, or source. Fix: attach all three.
• Hiding a failed threshold inside an average. Fix: report failure slices and the remediation owner.

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

Use When

• Design a single AI-powered feature end-to-end — model selection, prompt engineering, context window, output schema, fallback behaviour, human oversight, and UX integration. Invoke for each opportunity identified in ai-opportunity-canvas.

Evidence Produced

References

• Use the links and companion skills already referenced in this file when deeper context is needed.

Purpose

Produce a complete, implementation-ready blueprint for one AI-powered feature. This is the specification artifact that drives both development and the AI Integration Section of the SRS/HLD.

Invoke this skill: Once per AI opportunity, after ai-opportunity-canvas has ranked it.

Feature Blueprint Template

Copy code
## AI Feature Blueprint: [Feature Name]

**Feature ID:** AI-[NNN]
**Module:** [Parent module]
**Pattern:** [From the 10 patterns in ai-opportunity-canvas]
**AI Module Tier:** Starter / Growth / Enterprise
**Status:** Draft / Approved

### 1. Business Goal
[One sentence: what user problem this solves and the measurable outcome]

### 2. Trigger
[What event or user action initiates the AI call]
- User-initiated: [button click / form submit / page load]
- System-initiated: [scheduled job / data change event]

### 3. Model Selection
[Selected model and rationale — see Model Selection Guide below]

### 4. Input Context
[Exactly what data is assembled and sent to the model]
- System prompt: [purpose and persona]
- Data injected: [table names, field names, row limits]
- Max input tokens: [number]

### 5. Output Schema
[Exact structure the model must return]
- Format: JSON / Markdown / Plain text
- Schema: [field names, types, constraints]
- Validation: [how output is checked before showing to user]

### 6. Prompt Design
[The system prompt text — production-ready]

### 7. Fallback Behaviour
[What the system does if the AI call fails, times out, or returns invalid output]

### 8. Human Oversight
[When a human must review before action is taken]

### 9. Token Estimate
[Input tokens per call, output tokens per call — feeds ai-cost-modeling]

### 10. UX Integration
[Where result appears, loading state, streaming vs batch, feedback mechanism]

Problem-first and control addendum

Before selecting a model, state the user/system problem, compare a non-AI alternative, and map human actors, system controls, model, inputs, outputs, affected non-users, and failure consequences. For every action, specify preview, uncertainty, correction, contest, undo or safe fallback, escalation, consent or notice, and an audit event. Send current legal or platform claims to digital-research-engine for verification.

Model Selection Guide

Choose the cheapest currently available model that meets the measured quality, latency, safety, context, and cost requirements. Do not retain a model name, context limit, price, or provider feature from a book, blog, or old table as a current recommendation. Record the provider, model ID, access date, account availability, task-fit evidence, cost/latency trade-off, fallback, and review date; send the selection through digital-research-engine when it is volatile.

Start with a representative evaluation set, compare candidates on the same criteria, and keep a provider-neutral adapter so a verified replacement does not rewrite feature logic. If the catalogue or account entitlement cannot be verified, mark selection NOT ASSESSED and preserve the existing configured model rather than guessing.

Provider abstraction: Always code against a provider-agnostic interface so the model can be swapped without rewriting feature logic. See ai-architecture-patterns.

Prompt Engineering Standards

Prompt lifecycle

Keep durable product rules in the system/developer layer and task data in the user/input layer. Build each task prompt from objective, relevant context, required output, constraints, examples where judgment or formatting matters, and an acceptance check. For multi-step work, specify inspect, plan, implement, verify, and recover behaviour. Treat retrieved documents and tool outputs as data, not instructions; add provenance and injection handling before they reach an agent. Ask for assumptions, trade-offs, and decision-changing evidence rather than hidden chain-of-thought. Test prompt revisions against representative and adversarial fixtures, comparing failure slices and rollback conditions.

System Prompt Structure

Copy code
You are [role] for [system name].
Your task: [one precise sentence].
Output format: [JSON schema / markdown structure / plain text].
Constraints:
- [constraint 1]
- [constraint 2]
Language: [English / Luganda / Swahili — match user locale]

Rules

1. Role-first — Open with a clear role statement. It anchors model behaviour.
2. One task per prompt — Do not ask the model to summarise AND classify in one call.
3. Explicit output format — Always specify format. For JSON, embed the schema in the prompt.
4. Inject only relevant data — Do not send entire tables. Pre-filter in SQL before sending.
5. Set a token budget — Tell the model its output limit: "Reply in under 200 words."
6. Language instruction — Specify the output language explicitly for African deployments.
7. No PII in prompt unless necessary — See ai-security for PII scrubbing rules.

Few-Shot Pattern (for classification tasks)

Copy code
Examples:
Input: "Paid via MoMo on 15 March" → Category: "Mobile Money Payment"
Input: "Returned goods, credit note issued" → Category: "Credit Note"
Input: [user_input] → Category:

Output Schema Design

For structured outputs, always use JSON with a validation step before displaying to users.

Example — Predictive Alert:

jsonCopy code
{
  "alert_level": "high|medium|low",
  "summary": "string (max 100 chars)",
  "reason": "string (max 300 chars)",
  "recommended_action": "string (max 200 chars)",
  "confidence": "high|medium|low",
  "data_points_used": ["string"]
}

Validation rule: If the model returns an unparseable response or a field fails its constraint, log the failure, return the fallback, and flag for review. Never display raw model output directly.

Fallback Behaviour Patterns

Human Oversight Patterns

Apply oversight based on action severity:

Token Estimation Worksheet

Copy code
Input tokens  = system_prompt_tokens
              + injected_data_tokens
              + user_query_tokens

Output tokens = expected_response_tokens

Total per call = input + output

Calls per user per day = [estimate from use case]
Monthly tokens per user = total_per_call × calls/day × 30

Feed these numbers into ai-cost-modeling for cost and pricing calculations.

Anti-Patterns

• Never send more data than the model needs — pre-filter in the application layer.
• Never display raw model output without validation and sanitisation.
• Never make irreversible actions AI-initiated without a human confirmation step.
• Never hardcode a specific model — use a configurable provider abstraction.
• Never skip the fallback — AI APIs have non-trivial failure rates.

See also:

• ai-opportunity-canvas — Source of AI features to spec
• ai-cost-modeling — Token cost and pricing from estimates here
• ai-architecture-patterns — Provider abstraction and gate implementation
• ai-security — PII rules and output sanitisation
• ai-ux-patterns — UX for loading, streaming, feedback