# AI Coding Spec Packet Starter Kit

Use this starter kit before asking an AI coding tool to implement a feature. It turns a vague request into four reviewable files:

- `spec.md`
- `tasks.md`
- `acceptance-criteria.md`
- `evidence.md`

Keep the files beside the issue, pull request, or repository change folder. The packet is ready when a reviewer can reject scope drift and QA can create tests without interviewing the author.

---

## 1. spec.md

```md
# Feature Spec: <feature name>

Owner:
Status: Draft | Ready for review | Approved
Last updated:

## Context
- What system, user, or workflow is changing?
- What is the current behavior?
- Why does this need to change now?

## Goal
- What behavior should exist after this change ships?

## Non-goals
- What should this work explicitly not change?
- Which adjacent features, refactors, or policy decisions are out of scope?

## Requirements
1. The system must...
2. The user must be able to...
3. Existing behavior must continue to...

## Edge cases
- Empty or missing input:
- Permission or role mismatch:
- Retry, duplicate request, or idempotency:
- Legacy client or old data state:

## Constraints
- Allowed files or services:
- Public API or database contracts:
- Performance, security, privacy, or rollout constraints:

## Open questions
- [ ] Question:
  Owner:
  Required before:
```

---

## 2. tasks.md

```md
# Tasks: <feature name>

## Task 1: <small implementation slice>
Write scope:
- 

Acceptance mapping:
- AC-1:

Evidence required:
- Test:
- Log, screenshot, fixture, or metric:

## Task 2: <small implementation slice>
Write scope:
- 

Acceptance mapping:
- AC-2:

Evidence required:
- Test:
- Log, screenshot, fixture, or metric:

## Out-of-scope guardrail
The implementation must not:
- 
- 
```

---

## 3. acceptance-criteria.md

```md
# Acceptance Criteria: <feature name>

## AC-1: Happy path
Given
When
Then

Evidence:
- 

## AC-2: Invalid or blocked state
Given
When
Then

Evidence:
- 

## AC-3: Existing behavior preserved
Given
When
Then

Evidence:
- 

## AC-4: Rollback or failure path
Given
When
Then

Evidence:
- 
```

---

## 4. evidence.md

```md
# Evidence Checklist: <feature name>

## Automated checks
- [ ] Unit test:
- [ ] Integration or contract test:
- [ ] Regression test:
- [ ] Typecheck, lint, or build command:

## Manual checks
- [ ] Screenshot or recording:
- [ ] QA review:
- [ ] Product owner review:
- [ ] Accessibility or mobile check:

## Release evidence
- [ ] Feature flag or rollback switch:
- [ ] Log query or metric:
- [ ] Monitoring owner:
- [ ] Support or operations note:

## Review decision
Ready to merge? Yes / No
Reviewer:
Reason:
Follow-up:
```

---

## Reviewer Prompt

Before implementation starts, ask:

1. What would still be ambiguous to someone who missed the planning meeting?
2. Which non-goal would prevent the AI coding tool from expanding scope?
3. Which acceptance criterion cannot yet be tested?
4. What evidence would make this safe enough to merge?