A structured approach to explore features before production development. The goal is to learn, build acceptance criteria, experiment with verifiable prototypes, and codify learnings.
Task Folder Structure
tasks/NNN-taskname/
├── 01-objectives.md
├── 02-acceptance-criteria.md
├── 03-architecture.md
├── 04-verifiable-prototype.md
├── 05-verification.md
├── 06-outcome.md
├── 99-research/
└── 99-findings/
Document Templates
You MUST read the template files in ./references/001-example-task/ before scaffolding a task folder. These templates show the exact structure and format to use:
- 01-objectives.md
- 02-acceptance-criteria.md
- 03-architecture.md
- 04-verifiable-prototype.md
- 05-verification.md
- 06-outcome.md
Key Patterns
Stub Markers
For sections to be filled in later:
> Stub - to be filled in after objectives and acceptance criteria are approved.
Criteria Tables
Always pair criteria with verification method:
| Criterion | Verification Method |
|-----------|---------------------|
| User can log in | Manual test: complete flow, see logged-in state |
| API returns 401 on bad auth | `curl -H "Auth: bad"` shows 401 |
Checkpoint Lists
For prototypes, use checkboxes:
**Checkpoint 1:**
- [ ] Auth0 application configured
- [ ] PKCE enabled
ASCII Diagrams
Keep simple:
┌─────────────┐ ┌─────────────┐
│ Popup │────▶│ Background │────▶ API
└─────────────┘ └─────────────┘
Phase Flow
- Objectives → user reviews
- Acceptance Criteria → user approves before work begins
- Architecture → stub until criteria approved
- Prototype → incremental with checkpoints
- Verification → evidence for each criterion
- Outcome → learnings and follow-on work